Overview
One API to create, send, and track shipments across every supported Algerian carrier.
Scope: parcels:read for reads, parcels:write for anything that changes
state. Base path: /parcels. Launch carriers: Ecotrack, Yalidine/Guepex, ZR
Express, E-com Delivery, NOEST Express — connect one from Carrier accounts.
The model
Creating a parcel writes it to the platform first, with status created.
Sending it (submit: true on create, or a separate
POST /:id/send) is what actually reaches the
carrier. The two stay synced for life afterward — by webhook where the
carrier has one, by polling where it doesn't — but the platform copy always
exists even if a carrier call never fires. This split matters operationally:
you can create and validate a shipment (destination resolved, COD amount
set, label previewable) before committing to the carrier, and a failed send
never leaves you with an order that only half-exists.
COD amount is a first-class field, not something bolted onto metadata —
every carrier adapter maps it to whatever that carrier calls it internally.
Three things that trip people up
A carrier timeout requires checking the outcome. Cloud may leave a parcel at created when submission fails, but the carrier can have accepted it before the response was lost. Check tracking and carrier state before another submission to avoid duplicates.
Destination resolution runs on every create, not just when you ask for
it. state and city in the create payload accept dirty labels — the
same Atlas resolver behind /geo/resolve runs on them
automatically. A 422 unresolvable_geo with alternatives[] means the
platform genuinely couldn't auto-accept the destination; it will not
silently ship to a best-guess wilaya.
PATCH after submission is capability-checked per carrier, not
platform-wide. Editing a created parcel is free-form. Editing a
submitted one depends on what the specific carrier actually supports — an
unsupported field comes back as 501 carrier_unsupported, naming the field.
Check /geo/couriers if you need to know ahead of time
whether a given carrier account can edit post-submission.
Where to go
Create — the create payload, destination resolution, idempotency. Lifecycle — send, read, edit, cancel. Quotes — compare accounts, coverage, cheapest recommendation. Labels — single and merged-PDF label printing. Events — the status timeline and outbound webhooks. Batches — up to 1,000 parcels per call.