Skip to content

API Quirks & Compatibility ​

The live ZR Express API sometimes behaves differently from its own OpenAPI spec and docs. These are verified live and drive how the SDK (and your code) must build requests. Reading this page will save you from the common 400/403/500s.

This mirrors the drift register in docs/API_REFERENCE.md §9. Rule: live behaviour wins.

At a glance ​

#QuirkImpact
9.1401/403 have empty bodiesDon't assume a JSON error body
9.2TerritoryResponse includes nameArabic liveExtra field, typed as optional
9.3Supplier balance shape differs from specRead fields defensively
9.4Webhook phone shape is PhoneDto, not {countryCode,number}Permissive union
9.5Server tolerates out-of-range pagingValidate client-side
9.9getPortal not callable with an API keyExpect 403
9.10Webhook emission not synchronous/guaranteedDon't assume instant delivery
9.11supplier.get needs the id in the body tooEcho supplierId
9.12Label-PDF format must be a bare string'A4'/'A6', not the object
9.13Parcel create requires productId+sku, valid phone, hub for pickupMost common 400
9.14reports/documents search blocked for API keys404/403
9.15Webhook create 500s if eventTypes omittedAlways send eventTypes

9.1 — Empty-body 401 / 403 ​

Auth failures return no JSON body: a missing/invalid API key is 401; a missing/invalid X-Tenant or an insufficient role is 403. The SDK maps these on status alone, so ZrExpressAuthError/ZrExpressForbiddenError still carry a useful message. (Some role-forbidden endpoints — §9.14 — do return a ProblemDetails.)

9.2 — nameArabic on territories ​

Live /territories/search items include a nameArabic field absent from the spec. The SDK types it as nameArabic?: string | null. Great for RTL displays.

9.3 — Supplier balance shape ​

GET /supplier-payment/supplier-balance returns, live: totalAmountPaid, totalAmountReadyToBePaid, totalAmountDelivered, totalAmountNotReadyCashed, totalAmountReadyToBeCashed — not the spec's totalAmountNotCashed/totalAmountCashed. The type is the union (all optional); read balance fields defensively.

9.4 — Webhook phone shape ​

The webhook guide shows phone as { countryCode, number }, but a captured live delivery serialized customer.phone as the REST PhoneDto ({ number1 }). ParcelWebhookDto keeps a permissive WebhookPhone union admitting both.

9.5 — Tolerant paging ​

pageNumber: 0 / pageSize: 0 returned 200 with defaults rather than 400. Don't rely on server-side validation for client bugs — validate paging yourself.

9.9 — getPortal denied to API keys ​

zr.webhookEndpoints.getPortal() returns 403 DenyApiKey.ApiKeyNotAllowed ("This endpoint is not accessible via API") — the embedded Svix consumer portal is reachable only via the portal's own JWT session, not X-Api-Key.

9.10 — Webhook emission is not guaranteed-immediate ​

Transitioning a parcel through early workflow states did not always produce an endpoint delivery within the observation window. Prefer webhooks for state tracking, but do not assume synchronous delivery of every transition; de-dupe by svix-id and reconcile.

9.11 — supplier.get echoes the id in the body ​

POST /supplier/{supplierId} returns 400 Validation failed when the id is only in the path. Repeat it in the body:

ts
const supplier = await zr.supplier.get(supplierId, {
  supplierId,               // required in the body too
  includeServices: true,
});

Same "id echoed in the body" shape as UpdateParcelStateRequest.parcelId.

9.12 — Label-PDF format is a bare string ​

The generated type models format as PdfLabelFormat { value } with a readOnly value, so format: { value: 'A4' } — or even {} — is rejected with 400. The live API wants a plain string. Since SDK 0.1.1 the format type accepts it directly:

ts
await zr.labels.generateMultiplePdf({
  trackingNumbers: ['ZR-123'],
  format: 'A4', // or 'A6', or omit for the server default
});

9.13 — Parcel create requirements ​

The single most common 400 (General.Validation). A valid CreateParcelRequest needs:

  • customer.customerId — a real GUID.
  • customer.phone.number1 — present and a valid international number.
  • at least one orderedProducts[] carrying both a valid productId (GUID) and a non-empty productSku (the sku isn't cross-checked — any non-empty string works). stockType: 'none' is accepted.
  • for deliveryType: 'pickup-point', a hubId — 'home' needs none.

Note products.search can return 0 while parcels still reference real product ids, so you may have to resolve a productId from an existing parcel's orderedProducts rather than the catalog. See the full verified create example.

9.14 — reports/documents search blocked for API keys ​

zr.reports.search → 404 (/reports/search not served for API-key callers). zr.documents.search → 403 DenyApiKey.ApiKeyNotAllowed. Both methods exist (a portal/JWT session may reach them); with an API key, handle the errors. See Reports & Documents.

9.15 — Webhook create needs eventTypes ​

The docs say "omit eventTypes for all events", but omitting it returns 500. Always send a non-empty array — to subscribe to everything, send the full ZR_WEBHOOK_EVENTS:

ts
import { ZR_WEBHOOK_EVENTS } from '@terminaldz/zrexpress-sdk/webhooks';

await zr.webhookEndpoints.create({
  url: 'https://your.app/webhooks/zr',
  eventTypes: [...ZR_WEBHOOK_EVENTS], // never omit
});

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