Core Concepts
A few ZR Express concepts show up throughout the API. Understanding them up front avoids most surprises.
Tenant vs. supplier
ZR Express is multi-tenant. Your tenant is the account context (identified by the X-Tenant GUID); your supplier is the business entity within it (name, hub, address, services). One API key belongs to a user who has one or more tenant memberships with roles — the test account has a single membership with the supplier-admin role.
users.getProfile() returns the user + memberships; supplier.get(supplierId, …) returns the supplier entity.
Headers: X-Api-Key and X-Tenant
Every request carries X-Api-Key. Every request also carries X-Tenant except four tenant-exempt operations (key/profile management), which the SDK handles per-operation:
users.getProfile()—GET /users/profileusers.createApiKey()—POST /users/keysusers.searchApiKeys()—POST /users/keys/searchusers.deleteApiKey()—DELETE /users/keys/{id}
You never set headers yourself — the SDK encodes the exemptions.
The /api/v1 base
Requests go to ${baseUrl}/api/v${apiVersion}${path} — by default https://api.zrexpress.app/api/v1/…. Only version "1" exists today.
Territories: wilaya & commune
Algeria's geography is modelled as territories with a level of wilaya (province) or commune. Live territory rows include a nameArabic field (drift §9.2). Resolve territory ids for parcel delivery addresses and rate lookups via territories.search.
const communes = await zr.territories.search({
pageSize: 50,
advancedFilter: { field: 'level', operator: 'eq', value: 'commune' },
});Hubs
Hubs are sorting centres, agencies, and pickup points. A parcel delivered by deliveryType: 'pickup-point' requires a hubId — resolve one via hubs.search (hubs also has a POST-by-id get).
Workflows and tenant-specific state ids
Parcels move through a tenant-specific workflow — a state machine whose state ids and legal transitions are UUIDs unique to your tenant. Never hard-code a state id. Read them from workflows.search, and only transition a parcel to a state that is a legal target from its current state:
const wf = (await zr.workflows.search({ pageSize: 5 })).items[0];
const current = wf.states?.find((s) => s.id === parcel.state?.id);
const legalTargets = (current?.transitions ?? [])
.filter((t) => t.fromStateId === parcel.state?.id)
.map((t) => ({ id: t.toStateId, name: wf.states?.find((s) => s.id === t.toStateId)?.name }));See Parcels → Transition state.
Short-lived SAS URLs
Labels, reports, and document downloads return Azure SAS URLs — time-limited (and sometimes IP-locked) blob links. Download them promptly; never store the URL. Regenerate if you need the file again later.
Empty-body 401 / 403
Auth failures come back with no JSON body: a missing/invalid API key is 401; a missing/invalid X-Tenant or an insufficient role is 403. The SDK's error mapping does not assume a body, so ZrExpressAuthError / ZrExpressForbiddenError still carry a helpful message. Some role-forbidden operations do return a ProblemDetails body (e.g. the API-key-blocked reports/documents endpoints).
ProblemDetails.title is a machine code
Error bodies are application/problem+json. The title is a machine-readable code like ParcelErrors.NotFound (surfaced as error.code); detail is the human message; traceId is for support correlation. See Error Handling.