Skip to content

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/profile
  • users.createApiKey() — POST /users/keys
  • users.searchApiKeys() — POST /users/keys/search
  • users.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.

ts
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:

ts
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.

Released under the MIT License. Not affiliated with ZR Express.