Update Shipment Info of Package Command

Actors

• Akinon Order Management System (OMS)

• Akinon Omnitron System

• Integrated Application (ERP)

Domain Objects

• Packaging Orders

• OMS Command

Process

1. The OMS application copies orders from the Akinon Omnitron application to itself to prepare delivery/distribution plans, generate packaging orders, and transfer them to the operational points.

2. The products in the order are distributed into Packaging Orders according to the rules of the distribution scenarios chosen by the brand.

3. Packaging Orders are transferred to the Akinon Instore Application or the brand's integrated software (Packaging Orders Webhooks).

4. Packaging orders assigned by the Store/Warehouse begin in the Waiting status.

5. When the packaging is physically prepared for distribution in one or more steps, it is updated to the Packed status using the screens in the Akinon Instore application or by executing OMS commands through other software integrated with the OMS application (see: OMS Commands API).

6. When the package is handed over to the shipping company, its status is updated to Shipped using the screens in the Akinon Instore application or by executing OMS commands through other software integrated with the OMS application.

7. The shipping company may then update the package's status to Attempted Delivery or Delivery Failed.

8. This command can be run when the package is in the Packed, Shipped, Delivered, or Attempted Delivery status to update the package's shipment details, including the shipping company, tracking number, and query number information.

After this command is executed, the package's shipment will be tracked using the new shipping company and tracking number information. The package label file will also be updated to reflect the new shipping company and tracking number details.

Command Parameters and Prerequisites

For each packaging order;

• Packing Order ID (integer - dynamic for each order)

• Command Transition ID (integer - fixed - prepared and informed during OMS installation)

• Shipment Tracking Number (referred to as `awb_number` in the parameters)

• Shipment Query Number (optional)

• Cargo Company

If this command is executed before a packaging order reaches the Packed status, it will result in a validation error. The prerequisite for all packages that have reached the Packed status is considered complete (e.g., shipped status).

---

POST Update The Package’s Shipment Status

Path: https://{customer_api_url}-oms.akinon.net/api/v1/oms/packages/{package_id}/command/

Body Parameters

Parameter	Data Type	In	Description
token	string	header	The API key of the customer account

• Package ID: package_id (integer)

• Transition ID: transition_id (integer) (set after OMS installation)

• Shipment Tracking Number: awb_number (string)

• Shipment Query Number: query_number (string, optional)

• Cargo Company: cargo_company (integer) (OMS id of the cargo company)

Request Body

{
    "transition": <transition-id>,
    "package": <package-id>,
    "input_parameters": {
        "awb_number": <tracking-number>,
        "cargo_company": <shipping-company>,
        "query_number": <query-number>
    }
}

Example Response (204 No Content)

Status Code: 204 No Content

Example Response of the Validation Error

Status Code: 400 Bad Request

{
  "error": {
    "awb_number": [
      "This field is required."
    ]
  },
  "status_code": 400
}

Example Response of the Command Error

Status Code: 406 Not Acceptable

{
  "error": {
    "non_field_errors": "Shipment information could not be updated for package: {number}, due to an error: {errors}",
    "error_code": "package_commands_100_13"
  },
  "status_code": 406
}

Example Response of the Command Error

Status Code: 406 Not Acceptable

{
  "error": {
    "non_field_errors": "Invalid state transition ({source_state} -> {destination_state}) for ({package_state}) package.",
    "error_code": "package_100_5"
  },
  "status_code": 406
}

Transitions and Validations

The command transition source and destination values must be the same.

valid source states:
- PackageStatus.packed
- PackageStatus.shipped
- PackageStatus.attempted_delivery
- PackageStatus.delivery_failed

Valid destination states:
- PackageStatus.packed
- PackageStatus.shipped
- PackageStatus.attempted_delivery
- PackageStatus.delivery_failed

Valid state transitions:
- PackageStatus.packed → PackageStatus.packed
- PackageStatus.shipped → PackageStatus.shipped
- PackageStatus.attempted_delivery → PackageStatus.attempted_delivery
- PackageStatus.delivery_failed → PackageStatus.delivery_failed