Commands

These services provide the ability to perform actions such as commands, cancellations, or completion procedures for a package or transfer. The commands that can be executed for a Package or Transfer object are dependent on the current status of the relevant record. When a GET request is sent with the object's ID (PK) to be processed, the commands that can be run are listed under the "commands" keyword.

Regardless of scenarios, the process of lowering and raising quotas continues, the quota amount continues to increase and decrease on a location basis. However, for these alterations to impact planning, the scenario rules must have the SELECT_BY_QUOTA value.

The maximum quota value specifies how many packages can be created from the respective location. The quota value is a user-unspecified parameter used for monitoring the maximum quota value and performing increase or decrease operations.
max_quota - quota = available_quota
If the available_quota value is 0, no packages can be created. (To encounter this scenario, the SELECT_BY_QUOTA value must be chosen in the scenario rules.)
For packages with a status below 400 and in the cancellation_waiting state, the quota value increases by 1. (During this stage, when the package is in the waiting state, the quota amount is considered to increase by 1.)
Upon packaging a package, the quota value decreases by 1. Consequently, the available_quota increases, enhancing the likelihood of packaging from the respective location.
In the event of a package cancellation, the quota amount decreases by 1 in a similar way.

Usage

A sample packaging order: https://<customer>-oms.akinon.net/api/v1/oms/packages/{package_id}

Package ID: XXX
Transition ID: NNN (set after OMS installation)
Slug: unique-slug-value

Note: When you execute a command, you must use Transition ID or Slug value. One is enough to execute command that you need. In the examples, the slug and TransitionID can be seen together, however you may only choose one when you send request.

Command List Example:

 [
  {
    "id": 1841, // TransitionID
    "label": "Test Label",
    "ui_visibility": [
      "oms_web"
    ],
    "slug": "package__assign_package_items_manually__waiting__packaging-canceled", // Unique-Slug
    "created_date": "2023-02-28T08:48:29.679101Z",
    "modified_date": "2023-02-28T08:48:29.679141Z",
    "translations": null,
    "command": "ASSIGN_PACKAGE_ITEMS_MANUALLY",
    "source_state": 33,
    "destination_state": 44
  },
  {
    "id": 1809,
    "label": "Test-2 Label",
    "ui_visibility": [
      "third_party",
      "oms_web",
      "instore"
    ],
    "slug": "package__pkg_state_transition__uzaktan-eylem-bekleniyor__hazırlanıyor",
    "created_date": "2023-02-03T11:16:08.065410Z",
    "modified_date": "2023-02-14T10:38:27.133471Z",
    "translations": null,
    "command": "PKG_STATE_TRANSITION",
    "source_state": 142,
    "destination_state": 34
  }
]

The system distinguishes the command to be run by the relevant ID (PK) and slug value. The command IDs will therefore be required in the future.

Commands Examples

1. Pack Command

The "pack" command is used to signify that the products are ready once all products to be placed in the package are confirmed to be in the current location. Executing this command generates the OMS Shipping information for the packaged products and prepares the Shipment receipt information, which can then be printed on the physical package. It should be noted that the shipment receipt is obtained from the integrated shipping company. Below is an example of how to execute the "pack" command.

Request `POST`

Path: <OMS_URL>/api/v1/oms/packages/<package_id>/command/

Request Header

Content-Type: application/json

Request Body

{
  "transition": 333,
  "input_parameters": {},
  "slug": "unique-slug-value"
}

Request Parameters

Name	Data Type	Explanation
OMS_URL	string	The base URL information of the OMS application.
package_id	int	The ID of the package used to run the command.
transition_id	int	The ID of the “Pack” command in the commands listed when a GET request is sent to the package object.
slug	string	The Slug of the “Pack” command in the commands listed when a GET request is sent to the package object.

Failed Response Example

Error code: 406

{
  "error": {
    "non_field_errors": "Command definition is not allowed! Check source & destination states of command to be created",
    "error_code": "commands_100_1"
  },
  "status_code": 406
}

2. Ship Command

The command that must be run after a package has been shipped. It signifies that the package has been shipped from the relevant store or warehouse.

Request `POST`

Path: <OMS_URL>/api/v1/oms/packages/<package_id>/command/

Request Header

Content-Type: application/json

Request Body

{
  "transition": 333,
  "input_parameters": {
    "package_items": [
      1,
      2,
      3
    ]
  },
  "slug": "unique-slug-value"
}

Request Parameters

Name	Data Type	Explanation
OMS_URL	string	The base URL information of the OMS application.
package_id	int	The ID of the package used to run the command.
transition_id	int	The ID of the “Pack” command in the commands listed when a GET request is sent to the package object.
slug	string	The Slug of the “Pack” command in the commands listed when a GET request is sent to the package object.
package_items	int array	Information regarding the package IDs of listed products that are faulty or unavailable. By sending a GET request for the relevant package, you can access the ID information of the package items under “packageitem_set” in the incoming result. When a request is sent successfully, a response is returned with the code 200 in the following format.

Successful Response Example

Error code: 200

{
  "package_id": "<package_id>",
  "package_number": "<package_number>",
  "package_stock_location_id": "<stock_location_id>",
  "package_stock_location_name": "<stock_location_name>",
  "is_same_location": "<bool_value>"
}

Response Parameters

Name	Data Type	Explanation
package_id	int	The ID of the package used to run the command.
package_number	string	The numerical information for the relevant package.
package_stock_location_id	int	The ID information of the stock location for the relevant package.
package_stock_location_name	string	The name information of the stock location for the relevant package.
is_same_location	bool	The information regarding whether the relevant package exists in the same stock location, returned True or False In case of any problems, the response content related to the error with the error code 406 is returned.

Failed Response Example

Status code: 406

{
  "error": {
    "non_field_errors": "Command definition is not allowed! Check source & destination states of command to be created",
    "error_code": "commands_100_1"
  },
  "status_code": 406
}

Status code: 406

{
  "error": {
    "non_field_errors": "Command id and slug mismatch",
    "error_code": "commands_100_5"
  },
  "status_code": 406
}

Status code: 400 (Validation Error)

{
  "error": {
    "non_field_errors": "transition or slug required"
  },
  "status_code": 400
}

3. Out-of-stock Command

This command is used to indicate that one or more products in a package is/are unavailable in the relevant location. When this command is run, it will revise the products marked as “OMS Not Found” and “Needs Rescheduling”. If there is available stock, the command will assign it for packaging at a different location.

Request `POST`

Path: <OMS_URL>/api/v1/oms/packages/<package_id>/command/

Request Header

Content-Type: application/json

Request Body

{
  "transition": 333,
  "input_parameters": {
    "package_items": [
      1,
      2,
      3
    ]
  },
  "slug": "unique-slug-value"
}

Request Parameters

Name	Data Type	Explanation
OMS_URL	string	The base URL information of the OMS application.
package_id	int	The ID of the package used to run the command.
transition_id	int	The ID of the “Pack” command in the commands listed when a GET request is sent to the package object.
slug	string	The Slug of the “Pack” command in the commands listed when a GET request is sent to the package object.
package_items	int array	Information regarding the package IDs of listed products that are faulty or unavailable. By sending a GET request for the relevant package, you can access the ID information of the package items under “packageitem_set” in the incoming result. When a request is sent successfully, a response is returned with the code 200 in the following format.

Successful Response Example

Error code: 200

{
  "package_id": "<package_id>",
  "package_number": "<package_number>",
  "package_stock_location_id": "<stock_location_id>",
  "package_stock_location_name": "<stock_location_name>",
  "is_same_location": "<bool_value>"
}

Response Parameters

Name	Data Type	Explanation
package_id	int	The ID of the package used to run the command.
package_number	string	The numerical information for the relevant package.
package_stock_location_id	int	The ID information of the stock location for the relevant package.
package_stock_location_name	string	The name information of the stock location for the relevant package.
is_same_location	bool	The information regarding whether the relevant package exists in the same stock location, returned True or False In case of any problems, the response content related to the error with the error code 406 is returned.

Failed Response Example

Status code: 406

{
  "error": {
    "non_field_errors": "Command definition is not allowed! Check source & destination states of command to be created",
    "error_code": "commands_100_1"
  },
  "status_code": 406
}

Status code: 406

{
  "error": {
    "non_field_errors": "Command id and slug mismatch",
    "error_code": "commands_100_5"
  },
  "status_code": 406
}

Status code: 400 (Validation Error)

{
  "error": {
    "non_field_errors": "transition or slug required"
  },
  "status_code": 400
}

4. Repack Command

The command used to reschedule packages that have been marked “Out of Stock” or “Needs Rescheduling” by OMS, and used to prepare them for packaging.

Request `POST`

Path: <OMS_URL>/api/v1/oms/packages/<package_id>/command/

Request Header

Content-Type: application/json

Request Body

{
  "transition": 333,
  "input_parameters": {},
  "slug": "unique-slug-value"
}

Request Parameters

Name	Data Type	Explanation
OMS_URL	string	The base URL information of the OMS application.
package_id	int	The ID of the package used to run the command.
transition_id	int	The ID of the “Pack” command in the commands listed when a GET request is sent to the package object. When a request is sent successfully, a response is returned with the code 200 in the following format. In case of any problems, the response content related to the error with the error code 406 is returned.
slug	string	The Slug of the “Pack” command in the commands listed when a GET request is sent to the package object.

Failed Response Example

Status code: 406

{
  "error": {
    "non_field_errors": "Command definition is not allowed! Check source & destination states of command to be created",
    "error_code": "commands_100_1"
  },
  "status_code": 406
}

Status code: 406

{
  "error": {
    "non_field_errors": "Command id and slug mismatch",
    "error_code": "commands_100_5"
  },
  "status_code": 406
}

Status code: 400 (Validation Error)

{
  "error": {
    "non_field_errors": "transition or slug required"
  },
  "status_code": 400
}

5. Pack Order Command From Different Channels

This command indicates that the products are prepared for shipment once all products intended for the package are confirmed to be in the current location. However, unlike the "Pack" command, this command does not generate any shipping documents. Instead, it proceeds directly to the shipment stage.

Request `POST`

Path: <OMS_URL>/api/v1/oms/packages/<package_id>/command/

Request Header

Content-Type: application/json

Request Body

{
  "transition": 333,
  "input_parameters": {},
  "slug": "unique-slug-value"
}

Request Parameters

Name	Data Type	Explanation
OMS_URL	string	The base URL information of the OMS application.
package_id	int	The ID of the package used to run the command.
transition_id	int	The ID of the “Pack” command in the commands listed when a GET request is sent to the package object. When a request is sent successfully, a response is returned with the code 200 in the following format. In case of any problems, the response content related to the error with the error code 406 is returned.
slug	string	The Slug of the “Pack” command in the commands listed when a GET request is sent to the package object.

Failed Response Example

Status code: 406

{
  "error": {
    "non_field_errors": "Command definition is not allowed! Check source & destination states of command to be created",
    "error_code": "commands_100_1"
  },
  "status_code": 406
}

Status code: 406

{
  "error": {
    "non_field_errors": "Command id and slug mismatch",
    "error_code": "commands_100_5"
  },
  "status_code": 406
}

Status code: 400 (Validation Error)

{
  "error": {
    "non_field_errors": "transition or slug required"
  },
  "status_code": 400
}

6. Advanced Ship Command

The command that must be run after a package has been shipped. Unlike the standard ship command, the shipping company and number must be provided as parameters.

Request `POST`

Path: <OMS_URL>/api/v1/oms/packages/<package_id>/command/

Request Header

Content-Type: application/json

Request Body

{
  "transition": 333,
  "input_parameters": {
    "tracking_number": "<tracking_number>",
    "cargo_company": "str or id !!!!!!!!!!!!!!"
  },
  "slug": "unique-slug-value"
}

Request Parameters

Name	Data Type	Explanation
OMS_URL	string	The base URL information of the OMS application.
package_id	int	The ID of the package used to run the command.
transition_id	int	The ID of the “Pack” command in the commands listed when a GET request is sent to the package object.
slug	string	The Slug of the “Pack” command in the commands listed when a GET request is sent to the package object.
tracking_number	string	The shipping number of the package to be shipped.
cargo_company	int	The ID of a shipping company that can be accessed upon issuing a GET request to “/api/v1/oms/cargo-company/” must be sent.

When a request is sent successfully, a response is returned with the code 200 in the following format. In case of any problems, the response content related to the error with the error code 406 is returned.

Failed Response Example

Status code: 406

{
  "error": {
    "non_field_errors": "Command definition is not allowed! Check source & destination states of command to be created",
    "error_code": "commands_100_1"
  },
  "status_code": 406
}

Status code: 406

{
  "error": {
    "non_field_errors": "Command id and slug mismatch",
    "error_code": "commands_100_5"
  },
  "status_code": 406
}

Status code: 400 (Validation Error)

{
  "error": {
    "non_field_errors": "transition or slug required"
  },
  "status_code": 400
}

Commands

Usage​

Commands Examples​

1. Pack Command​

Request POST​

Request Header​

Request Body​

Request Parameters​

Failed Response Example​

2. Ship Command​

Request POST​

Request Header​

Request Body​

Request Parameters​

Successful Response Example​

Response Parameters​

Failed Response Example​

3. Out-of-stock Command​

Request POST​

Request Header​

Request Body​

Request Parameters​

Successful Response Example​

Response Parameters​

Failed Response Example​

4. Repack Command​

Request POST​

Request Header​

Request Body​

Request Parameters​

Failed Response Example​

5. Pack Order Command From Different Channels​

Request POST​

Request Header​

Request Body​

Request Parameters​

Failed Response Example​

6. Advanced Ship Command​

Request POST​

Request Header​

Request Body​

Request Parameters​

Failed Response Example​

Usage

Commands Examples

1. Pack Command

Request `POST`

Request Header

Request Body

Request Parameters

Failed Response Example

2. Ship Command

Request `POST`

Request Header

Request Body

Request Parameters

Successful Response Example

Response Parameters

Failed Response Example

3. Out-of-stock Command

Request `POST`

Request Header

Request Body

Request Parameters

Successful Response Example

Response Parameters

Failed Response Example

4. Repack Command

Request `POST`

Request Header

Request Body

Request Parameters

Failed Response Example

5. Pack Order Command From Different Channels

Request `POST`

Request Header

Request Body

Request Parameters

Failed Response Example

6. Advanced Ship Command

Request `POST`

Request Header

Request Body

Request Parameters

Failed Response Example