Starex Integration

This document is for external systems integrating with Starex. It describes the webhook notifications and the APIs for retrieving shipment statuses.

The base URL and Basic-Auth credentials (login/password) are provided by Starex. Below, the base URL is shown as {BASE_URL}.

1. About the webhook

When a shipment's status changes, Starex automatically sends an HTTP POST request to the URL you provide. This lets you receive status changes in real time.

To start the integration, you provide Starex with:

Webhook URL — your endpoint that receives notifications (e.g. https://your-domain.uz/starex/webhook).

Response: return HTTP 200 to acknowledge receipt. Any other response (4xx, 5xx, timeout) is treated as a failure and Starex will retry several times.

2. Webhook payload

Starex sends the following request to your URL:

POST {YOUR_WEBHOOK_URL}
Content-Type: application/json

Body (JSON):

{
  "barcode": "AB123456789UZ",
  "state": 12,
  "statetime": "2026-06-15 14:30:00"
}

Field	Type	Description
`barcode`	string	Shipment barcode
`state`	integer	Status code (meaning of codes — section 3: Statuses list API)
`statetime`	string	Date-time the status changed

3. Statuses list API

Returns the list of all possible statuses, so you can decode the state code from the webhook.

GET {BASE_URL}/api/v1/dictionaries/states

Authorization: Basic Auth.

GET {BASE_URL}/api/v1/dictionaries/states
Authorization: Basic base64(login:password)
Accept: application/json

Response (200) — example (part of the list):

{
  "success": true,
  "data": [
    { "code": 0, "name": "Ожидает синхронизации", "advanced": "AWAITING_SYNC" },
    { "code": 1, "name": "Новый",                  "advanced": "NEW" },
    { "code": 9, "name": "Доставлен",              "advanced": "COMPLETE" }
  ]
}

Field	Type	Description
`code`	integer	Status code (same as `state` in the webhook)
`name`	string	Status name (returned in Russian)
`advanced`	string	Stable, language-neutral code (machine code)

Important: the list of statuses is not constant — new statuses may be added or existing ones changed. Do not hard-code the list into this document; always fetch the current list from this API.

advanced is a textual (mnemonic) code attached to each status, e.g. NEW, PICKUP, DELIVERY, COMPLETE. Use it together with code in your logic; name is for display (in Russian).

4. Order statuses API

Returns the status history of a single shipment (order) by barcode.

GET {BASE_URL}/api/v1/order/trace

Authorization: Basic Auth.

Parameter	Type	Required	Description
`barcode`	string	Yes	Shipment barcode

GET {BASE_URL}/api/v1/order/trace?barcode=AB123456789UZ
Authorization: Basic base64(login:password)
Accept: application/json

Response (200):

{
  "success": true,
  "data": {
    "barcode": "AB123456789UZ",
    "date": "2026-06-10 09:00:00",
    "weight": 1.5,
    "recipient": "First Last",
    "trace": [
      { "code": 1, "name": "Новый",     "advansed": "NEW",      "statetime": "2026-06-10 09:00:00" },
      { "code": 9, "name": "Доставлен", "advansed": "COMPLETE", "statetime": "2026-06-15 14:30:00" }
    ]
  }
}

Field	Type	Description
`barcode`	string	Shipment barcode
`date`	string\|null	Acceptance date
`weight`	number\|null	Weight
`recipient`	string\|null	Recipient
`trace[]`	array	Status history (chronological)
`trace[].code`	integer	Status code
`trace[].name`	string\|null	Status name
`trace[].advansed`	string\|null	Additional description
`trace[].statetime`	string\|null	Status time

An error (e.g. barcode not found) is returned as:

{
  "success": false,
  "error": { "code": 422, "message": "..." }
}