> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/oms/commands/packages/package-sync-omnitron-status-command.md).

# Package Sync Omnitron Status Command

This guide explains how the `PACKAGE_SYNC_OMNITRON_STATUS` command synchronizes an OMS package's status with the status of its order items in Omnitron, and how to run the command through the OMS API.

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

The Akinon Order Management System (OMS) copies orders from Omnitron to prepare delivery and distribution plans, generate package orders, and transfer them to operation points.

When a package is in the `waiting_remote_action` state, it is waiting for an update from an external system before it can continue its lifecycle. The `PACKAGE_SYNC_OMNITRON_STATUS` command retrieves the current status of the package's order items from Omnitron and moves the package to the matching OMS state.

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

| Actor              | Role                                                         |
| ------------------ | ------------------------------------------------------------ |
| Akinon OMS         | Runs the command and updates the package state.              |
| Omnitron           | Provides the current status of the package's order items.    |
| Retail store staff | Triggers the command from the OMS web interface when needed. |

## <mark style="color:red;">How It Works</mark>

1. The command queries Omnitron for the current status of every order item in the package.
2. It checks that all order items share the same status code in Omnitron. If the statuses differ, the sync fails.
3. It maps the Omnitron status code to the corresponding OMS package state and performs the state transition.
4. If the new state requires it (for example, a transition to **Shipped**), the command releases the related inventory reservations.
5. It updates the package and all of its package items to the synchronized state.

{% hint style="info" %}
OMS does not apply partial updates. Either the whole package is synchronized, or no change is made.
{% endhint %}

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

The destination state is determined dynamically by the Omnitron status code of the order items. The source state is always **Waiting Remote Action** (`waiting_remote_action`).

| Omnitron status code | OMS destination state   | Description                                                      |
| -------------------- | ----------------------- | ---------------------------------------------------------------- |
| `100`                | Cancelled (`cancelled`) | The package has been cancelled.                                  |
| `400`                | Waiting (`waiting`)     | The package returns to the waiting state for further processing. |
| `450`                | Preparing (`preparing`) | The package is being prepared for shipment.                      |
| `500`                | Shipped (`shipped`)     | The package has been shipped to the customer.                    |
| `550`                | Delivered (`delivered`) | The package has been delivered to the customer.                  |
| `600`                | Refund (`refund`)       | The package is in the refund or return process.                  |

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

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

```
POST https://<customer>.omnitron.akinon.net/api/v1/oms/packages/{id}/command/
```

| Path parameter | Description                       |
| -------------- | --------------------------------- |
| `id`           | ID of the package to synchronize. |

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

```json
{
  "Authorization": "Token <token>",
  "Content-Type": "application/json",
  "Accept": "application/json, text/plain, */*",
  "Accept-Language": "en"
}
```

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

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

```json
{
  "input_parameters": {
    "package_items": []
  },
  "transition": 662,
  "is_packageitem_parameter_required": false,
  "configuration": {},
  "translations": null,
  "slug": "package-sync-omnitron-status",
  "ui_visibility": [
    "oms_web"
  ],
  "source_state": 2,
  "destination_state": 13
}
```

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

| Parameter          | Type    | Description                                                                                       |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------- |
| `input_parameters` | Object  | Command-specific parameters. See [Input Parameters](#input-parameters).                           |
| `transition`       | Integer | ID of the state transition to execute (for example, `662`). Required if `slug` is not sent.       |
| `slug`             | String  | Command slug (for example, `package-sync-omnitron-status`). Required if `transition` is not sent. |

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

| Parameter       | Type    | Required | Description                                                                                         |
| --------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| `package`       | Integer | No       | Package ID. Set automatically from the URL path.                                                    |
| `package_items` | Array   | Yes      | Package item IDs. Can be an empty array (`[]`), because the command operates on the entire package. |
| `user`          | Integer | No       | ID of the user running the command.                                                                 |

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

| Parameter                           | Type    | Default | Description                                                                                     |
| ----------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------- |
| `is_packageitem_parameter_required` | Boolean | `false` | Whether the `package_items` parameter is required.                                              |
| `configuration`                     | Object  | `{}`    | Additional configuration.                                                                       |
| `translations`                      | Object  | `null`  | Translation data.                                                                               |
| `ui_visibility`                     | Array   | —       | Interfaces where the command is visible (for example, `["third_party", "oms_web", "instore"]`). |
| `source_state`                      | Integer | —       | Source state ID. Used for validation and documentation purposes only.                           |
| `destination_state`                 | Integer | —       | Destination state ID. Used for validation and documentation purposes only.                      |

{% hint style="info" %}
You can send either `transition` or `slug`. Sending `transition` is recommended for simpler requests.
{% endhint %}

{% hint style="info" %}
The `package` parameter is inferred from the URL path (`/packages/{id}/command/`), so you don't need to send it.
{% endhint %}

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

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

**204 No Content**: The package was synchronized successfully. The response has no body.

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

| Status code                 | Cause                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `400 Bad Request`           | Invalid parameters or a business rule violation.                                     |
| `401 Unauthorized`          | The authentication token is missing or invalid.                                      |
| `403 Forbidden`             | The user doesn't have permission to run the command.                                 |
| `404 Not Found`             | The package doesn't exist.                                                           |
| `406 Not Acceptable`        | Invalid state transition, mixed Omnitron statuses, or the package is already synced. |
| `500 Internal Server Error` | OMS couldn't retrieve order details from Omnitron.                                   |

**400 Bad Request: Missing transition or slug**

```json
{
  "error": {
    "non_field_errors": [
      "transition or slug required."
    ]
  },
  "status_code": 400
}
```

**401 Unauthorized: Missing or invalid token**

```json
{
  "error": {
    "detail": "Authentication credentials were not provided."
  },
  "status_code": 401
}
```

**403 Forbidden: Insufficient permissions**

```json
{
  "error": {
    "detail": "You do not have permission to perform this action."
  },
  "status_code": 403
}
```

**404 Not Found: Package not found**

```json
{
  "error": {
    "detail": "No Package matches the given query."
  },
  "status_code": 404
}
```

**406 Not Acceptable: Invalid state transition**

Returned when the package is not in the state required for the transition.

```json
{
  "error": {
    "code": "package_100_5",
    "message": "Invalid package state transition",
    "params": {
      "source_state": "Waiting Remote Action",
      "destination_state": "Delivered",
      "package_state": "Preparing",
      "package_number": "PKG-12345"
    }
  },
  "status_code": 406
}
```

**406 Not Acceptable: Multiple order statuses**

Returned when the package's order items have different statuses in Omnitron.

```json
{
  "message": "package_commands_100_20:Sync with Omnitron failed due to multiple order statuses"
}
```

**406 Not Acceptable: Already synced**

Returned when the package is already in the state that matches the Omnitron status.

```json
{
  "message": "package_commands_100_21:Already synced with Omnitron in the same status"
}
```

**500 Internal Server Error: Omnitron communication error**

```json
{
  "error": {
    "message": "Failed to fetch order details from Omnitron",
    "order_id": 67890,
    "package_id": 12345
  },
  "status_code": 500
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/technical-guides/oms/commands/packages/package-sync-omnitron-status-command.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
