Fulfilling an order
A regionally fulfilled order is handed to you at the Sadarak hub and ends at the customer's door. This page is the stretch you own: where you take the order over, which events you report, and which transitions the order state machine accepts from you.
Where you take over
Runners bring the goods in from the stalls, the hub scans every line into intake and packs the order into parcels — each with a code like ES-1042-P1. Only then is there anything to load.
RUNNER_PICKUP → AT_HUB → PACKED → EN_ROUTE → DELIVEREDThe order you collect at the hub is a PACKED order. AT_HUB means received but not packed yet: the parcels do not exist, so there is nothing to put in your van.
Assignment can come before the packing
An operator may hand an order to your key in any of these statuses: AT_HUB, PACKED. The order.assigned_to_partner webhook can therefore reach you while the hub is still packing — treat that as a heads-up and wait for the packed order before you send a van.
The events you report
POST /v1/partner/orders/:code/events, with the logistics:write scope. Each type maps to exactly one transition, taken with the PARTNER actor and noted with your partner name:
| type | Meaning |
|---|---|
PICKED_UP | The parcels went onto the van through our hand-over scan at the hub. The order becomes SCANNED_TO_VAN. |
EN_ROUTE | The parcels are on their way to the customer. Report it straight from PACKED when you load into your own van. |
DELIVERED | Handed to the customer. Send codCollectedQepik on a cash-on-delivery order — an integer in qəpik, so 4750 is 47.50 ₼. |
FAILED | The delivery did not happen. The order stays with you until you retry it or send it back. |
The transitions we accept
Every from → to pair the API takes from a partner key, in reporting order:
PICKED_UP PACKED → SCANNED_TO_VAN
EN_ROUTE PACKED → EN_ROUTE (partner only)
EN_ROUTE SCANNED_TO_VAN → EN_ROUTE
DELIVERED EN_ROUTE → DELIVERED
FAILED EN_ROUTE → FAILEDPACKED → EN_ROUTE is yours alone. A regionally fulfilled order leaves the hub in your own van, so it never passes through SCANNED_TO_VAN — that status means the parcels were scanned onto an Turanyol van, and that gate is ours. No other actor on the platform can take that edge.
When we refuse
Anything outside the table above is refused and the order keeps the status it had — an impossible transition never corrupts an order.
ERR_INVALID_TRANSITIONThe order state machine refuses this transition from the current status.
ERR_PARTNER_ORDER_NOT_ASSIGNEDThe order is not assigned to your partner account.
ERR_API_KEY_SCOPEThe key is valid but does not carry the scope this endpoint needs.
Reporting a delivery
The order code is the one printed on the parcel label (ES-1042), not the order id.
curl -sS -X POST "https://api.turanyol.com/v1/partner/orders/ES-1042/events" \
-H "X-Api-Key: $ESADARAK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"DELIVERED","codCollectedQepik":4750}'