Skip to content

Parcels ​

zr.parcels is the largest namespace — creation, search, tracking, state transitions, bulk operations, exchanges/refunds, edits, stats, imports, and labels.

Use the verified request shape

The live API rejects a naive create body with 400 General.Validation. The example below is the minimal shape that actually returns 201, discovered by exercising the real API — see API Quirks §9.13. In short: each ordered product needs a real productId and a non-empty productSku; customer.phone.number1 is required and must be a valid international number; deliveryType: 'home' needs no hub ('pickup-point' requires a hubId).

Create a parcel ​

create is never retried (a retried create could duplicate a real shipment). It returns just { id }; fetch the full parcel with get afterwards.

ts
// Resolve real ids first (see the notes below each field).
const parcel = await zr.parcels.create({
  customer: {
    customerId: customerId,                 // a real customer GUID (customers.search)
    name: 'Acme Store',
    phone: { number1: '+213600000000' },    // REQUIRED, valid international number
  },
  deliveryAddress: {
    cityTerritoryId: wilayaId,              // territories.search { level: 'wilaya' }
    districtTerritoryId: communeId,         // territories.search { level: 'commune' }
    street: '12 Rue des Frères',
  },
  orderedProducts: [
    {
      productId: productId,                 // REQUIRED valid GUID
      productSku: 'SKU-001',                // REQUIRED non-empty (not cross-checked)
      productName: 'Widget',
      quantity: 1,
      unitPrice: 1500,
      stockType: 'none',                    // 'none' is accepted
    },
  ],
  deliveryType: 'home',                     // 'pickup-point' additionally needs hubId
  amount: 1500,                             // COD amount
  weight: { weight: 1 },
  externalId: 'order-2026-0001',            // your reference (echoed back)
});

const full = await zr.parcels.get(parcel.id!);

Where do the ids come from?

  • customerId — from zr.customers.search(...) (or create one with zr.customers.createIndividual(...)). See Customers.
  • cityTerritoryId / districtTerritoryId — from zr.territories.search. The district must support the chosen deliveryType.
  • productId / productSku — from zr.products.search(...). On some tenants the catalog search is empty even though parcels reference products; in that case resolve a productId from an existing parcel's orderedProducts (that's what the Playground does).

Search parcels ​

search uses the shared filter DSL and returns a PagedList<SearchSupplierParcelResponse>. Filter by state using the tenant's workflow state ids (never hard-code them — resolve via workflows.search):

ts
const page = await zr.parcels.search({
  pageNumber: 1,
  pageSize: 20,
  keyword: 'ZR-123',
  orderBy: ['createdAt desc'],
  advancedFilter: { field: 'state.id', operator: 'eq', value: stateId },
  includeProducts: true,
});

Iterate every match with the searchAll iterator.

Get a parcel ​

ts
const parcel = await zr.parcels.get(id);                       // GET /parcels/{id}
const byTracking = await zr.parcels.getByTrackingNumber('ZR-123456789', { scan: false });

The server disambiguates id vs. tracking number by value. scan: true marks the lookup as a scan event.

State history ​

ts
const history = await zr.parcels.getStateHistory(id); // ParcelStateHistoryDto[]

Prefer webhooks over polling

GET /parcels/{id}/state-history is rate-limited by design. For real-time tracking use webhooks; the SDK retries a 429 honouring Retry-After.

Transition a parcel's state ​

updateState requires the parcel id in the body too (not only the path), and newStateId must be a legal transition from the parcel's current state — resolve it from the workflow, never guess:

ts
const wf = (await zr.workflows.search({ pageSize: 5 })).items[0];
const current = wf.states?.find((s) => s.id === parcel.state?.id);
const target = (current?.transitions ?? []).find((t) => t.fromStateId === parcel.state?.id)?.toStateId;

if (target) {
  await zr.parcels.updateState(parcel.id!, {
    parcelId: parcel.id!,   // required in the body
    newStateId: target,
    comment: 'picked up',
  });
}

An illegal target is rejected with 400.

Delete ​

ts
await zr.parcels.delete(id); // DELETE /parcels/{id}

On a production tenant this is a real business event. Deleting a parcel with a return parcel cascades; ExchangeReturn parcels cannot be deleted.

Bulk operations ​

Bulk calls return the shared envelope on 200 / 207 / 400 and never throw — see Bulk Operations.

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

const result = await zr.parcels.createBulk({ parcels: [/* ≤ 100 SingleParcelCreationRequest */] });
console.log(result.successCount, result.failureCount);
assertBulkOk(result); // opt-in: throws ZrExpressBulkError if any item failed

Also available: deleteBulk, deleteBulkByTrackingNumber, createExchangeBulk, createRefundBulk.

Exchanges & refunds ​

ts
await zr.parcels.createExchange({ /* CreateParcelExchangeRequest */ });
await zr.parcels.createRefund({ /* CreateParcelRefundRequest */ }); // balance-checked server-side
await zr.parcels.updateRefundState(id, { /* … */ });

Edits & stats ​

ts
await zr.parcels.updateAmount(id, { /* … */ });
await zr.parcels.updateCustomer(id, { /* … */ });
await zr.parcels.updateDeliveryAddress(id, { /* … */ });
await zr.parcels.updateProducts(id, { /* … */ });

const byState = await zr.parcels.statsByState(workflowId, { parcelTypes: ['standard'] });
const bySituation = await zr.parcels.statsBySituation(workflowId, stateId);

Imports ​

ts
const result = await zr.parcels.import({ file: excelBlob, fileName: 'parcels.xlsx' });
const template = await zr.parcels.downloadImportTemplate(); // ArrayBuffer

Labels → SAS URLs ​

Label PDFs come back as short-lived SAS URLs — open them promptly, don't persist them. The format field must be a bare string ('A4' or 'A6'), not the generated PdfLabelFormat object — see API Quirks §9.12.

ts
const { fileUrl, failedTrackingNumbers } = await zr.labels.generateMultiplePdf({
  trackingNumbers: ['ZR-123456789'],
  format: 'A4',
});

Other label methods: generateIndividualPdf, generateMultipleHtml, generateIndividualHtml, generatePickupBagPdf.

See every method and type in the API Reference.

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