# Update Shipment Info of Package Command

## <mark style="color:red;">Actors</mark>

* Akinon Order Management System (OMS)
* Akinon Omnitron System
* Integrated Application (ERP)

## <mark style="color:red;">Domain Objects</mark>

* Packaging Orders
* OMS Command

### <mark style="color:red;">Process</mark>

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.

### <mark style="color:red;">Command Parameters and Prerequisites</mark>

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).

***

### <mark style="color:red;">`POST`</mark> <mark style="color:red;">Update The Package’s Shipment Status</mark>

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

#### Body Parameters

<table><thead><tr><th width="121.76953125">Parameter</th><th width="130.03515625">Data Type</th><th width="143.9453125">In</th><th>Description</th></tr></thead><tbody><tr><td>token</td><td>string</td><td>header</td><td>The API key of the customer account</td></tr></tbody></table>

* ***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`

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

#### Example Response of the Command Error

**Status Code:** `406 Not Acceptable`

```json
{
  "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`

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

### <mark style="color:red;">Transitions and Validations</mark>

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
```