Importing orders

Order fields

Field	Type	Required	Description
externalId	string ≤ 100	yes for bulk	document code in your system — the update key
number	string ≤ 100	yes	order number shown to dispatchers and drivers; unique within a day
deliveryDate	YYYY-MM-DD	yes	delivery day
customerExternalId / customerId	string / uuid	one of three*	delivery point from the directory
address, location	string, {lat, lon}	one of three*	the order’s own address and coordinates
warehouseExternalId / warehouseId	string / uuid	no	shipping warehouse
windowFrom, windowTo	HH:MM	no	delivery window (otherwise the point’s window)
serviceMinutes	integer	no	unloading time, minutes
weightKg, volumeM3, pallets	numbers	no	weight, volume, pallets — for vehicle capacity
amount, currency, paymentType	number, KZT…, prepaid/cash/card/transfer	no	amount to collect on delivery
recipientName, recipientPhone	strings	no	recipient; phone in any format, stored as +7…
priority	0–9	no	priority
notes	string ≤ 1000	no	note for the driver

* a delivery point or an address or coordinates. Orders without coordinates are planned once a dispatcher places them on the map (address geocoding is in development).

Single order

POST /orders creates, PATCH /orders/{id} changes fields, GET /orders/external/{externalId} finds by your code.

Bulk upload — recommended

POST /orders/bulk with { "orders": [ … ] } — 1 to 1000 orders per call (body up to 1 MB).

• A new externalId is created, a known one is updated (only the fields you send change).
• Every row is processed on its own: one bad row does not reject the others.
• The answer is always 200 with totals and a result per row, in input order:

{
  "created": 1, "updated": 1, "failed": 1,
  "results": [
    { "index": 0, "externalId": "SO-00001", "result": "created", "id": "4b0c…" },
    { "index": 1, "externalId": "SO-00002", "result": "updated", "id": "9d1e…" },
    { "index": 2, "externalId": "SO-00003", "result": "error",
      "error": { "code": "CUSTOMER_NOT_FOUND", "message": "No delivery point with this customerExternalId", "field": "customerExternalId" } }
  ]
}

Row code	Cause	What to do
VALIDATION_FAILED	wrong field format; see issues	fix the data
CUSTOMER_NOT_FOUND / WAREHOUSE_NOT_FOUND	no point/warehouse with this code	send the directory first
DUPLICATE_IN_BATCH	externalId repeats in one request	keep one row
DUPLICATE	number is used by another order of that day	use a unique number
ORDER_LOCKED	the order is with the driver or finished	changes go through the dispatcher

Cancellation: send the order in bulk with "status": "cancelled"; cancelled orders are not planned.

How to export: send changes on a schedule (every 5–15 minutes) and the full day before planning; batches of 500–1000, sequentially; an Idempotency-Key on every call. The key needs orders.create and orders.edit.