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.
// 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— fromzr.customers.search(...)(or create one withzr.customers.createIndividual(...)). See Customers.cityTerritoryId/districtTerritoryId— fromzr.territories.search. The district must support the chosendeliveryType.productId/productSku— fromzr.products.search(...). On some tenants the catalog search is empty even though parcels reference products; in that case resolve aproductIdfrom an existing parcel'sorderedProducts(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):
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
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
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:
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
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.
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 failedAlso available: deleteBulk, deleteBulkByTrackingNumber, createExchangeBulk, createRefundBulk.
Exchanges & refunds
await zr.parcels.createExchange({ /* CreateParcelExchangeRequest */ });
await zr.parcels.createRefund({ /* CreateParcelRefundRequest */ }); // balance-checked server-side
await zr.parcels.updateRefundState(id, { /* … */ });Edits & stats
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
const result = await zr.parcels.import({ file: excelBlob, fileName: 'parcels.xlsx' });
const template = await zr.parcels.downloadImportTemplate(); // ArrayBufferLabels → 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.
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.