shipping.nc API

shipping.nc API

Parcel shipping infrastructure for New Caledonia.

Tags
Shipments
Create, list and read the shipments of the authenticated carrier.
Tracking events
Record what happens to a shipment. Safe to retry: each event carries a client event id.
Shipper accounts
The businesses that ship with the carrier on account.
Team
The members of the carrier and the invitations still open.
Public tracking
What a recipient sees, without personal data.
Tours
Plan the tours of a day, publish them to the drivers and follow them live.
Pickups
Ask the carrier to pick up parcels at a shipper, put the request on a tour and read its outcome.
Driver phone
What a paired driver phone reads and records about its own tours.
Shipment imports
Create many shipments at once from a spreadsheet export, checked row by row before anything is created.
Labels
Print the 10x15 labels of shipments, as PDF or ZPL, and follow which ones are printed.
Shipper accounts
The merchants who ship with the carrier, their users and their API keys.
Company register
Look up the New Caledonian companies of the ISEE RIDET register (data.gouv.nc, Licence Ouverte v2.0) to fill in a company.
Webhooks
Register an HTTPS endpoint and the events it wants: each event is sent as a POST of a JSON body (see the webhooks section of this document), with the Shipping-Nc-Event-Id, Shipping-Nc-Event-Type, Shipping-Nc-Delivery-Id, Shipping-Nc-Delivery-Attempt and Shipping-Nc-Signature headers. Check the signature. Shipping-Nc-Signature reads t=<unix seconds>,v1=<hex>. Compute the HMAC-SHA256 of <t>.<raw body> keyed with the endpoint secret (the whole whsec_... string), compare it with the v1 value in constant time, and refuse the request when they differ or when t is more than 5 minutes from your clock. Check the raw bytes you received, before any JSON parsing.
JavascriptCode
const [t, v1] = ['t', 'v1'].map((key) => header.split(',').find((part) => part.startsWith(`${key}=`))?.slice(key.length + 1)); const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'); const valid = v1 !== undefined && v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected)) && Math.abs(Date.now() / 1000 - Number(t)) <= 300;
Answer fast. Any 2xx within 5 seconds is a success. Redirects are not followed. Anything else is retried after 1, 4, 16 and 64 minutes, then about 4 and 12 hours: 7 attempts in all. An event can arrive more than once and out of order: skip the event ids you already handled, and read data.shipment.status for the current status. An endpoint whose attempts all failed for a day (10 failures at least) is disabled, and its pending deliveries are given up; enable it again, then replay what it missed from its delivery log. Endpoints must use https on a public host name: addresses that resolve to a private, loopback or link-local network are refused.
Pickup points
The shops of the shipping.nc pickup point network, where recipients collect their parcels. For checkout pages and shipment forms.
Pickup point counter
What the staff of a pickup point do at the counter: check parcels in, hand them over, give them back. Each call sees only the parcels of the signed-in point.
Aggregator
One API for every carrier of New Caledonia: quote them all at once, book the offer you choose, print its label, find a pickup point, follow the parcel and cancel it before pickup. Authenticate with a merchant key (Authorization: Bearer mk_...). Test and live. A mk_test_ key never reaches a real carrier: the sandbox carrier answers it, with the same offers, tracking numbers (ZZ...) and labels on every run. A mk_live_ key books the real carriers. Test and live shipments never see each other. Retry safely. POST /v1/aggregator/shipments requires an Idempotency-Key header: a retry with the same key and body returns the shipment created first. Webhooks. Register an endpoint under /v1/aggregator/webhook-endpoints to receive the events of your shipments, signed and retried as the Webhooks tag explains (the merchant.* entries of the webhooks section show the body). A key manages the endpoints of its own mode. A test key also emits events: on booking, on cancellation, and when POST /v1/aggregator/shipments/{id}/simulate moves a sandbox shipment, so you can test your integration end to end without a carrier. Limits. Each key may send about 600 requests a minute in production (300 on demo). Above that, the answer is 429 with Retry-After: 60 and the error code too_many_requests: wait, then retry.
Platform console
shipping.nc staff only: provisioning carriers, support sessions, audit log and stage health. Every call is authorized against platform_staff and audited.
Carrier signup
Public: a carrier asks for an account, proves its email with a code, and waits for the shipping.nc staff to accept it.
Driver devices
Account
Incidents
Recipient self-service
Carrier settings
Rate cards
Notification settings
Onboarding
Webhooks
shipment.created

The `shipment.created` event

POST
shipment.status_changed

The `shipment.status_changed` event

POST
shipment.delivered

The `shipment.delivered` event

POST
shipment.delivery_failed

The `shipment.delivery_failed` event

POST
incident.opened

The `incident.opened` event

POST
incident.resolved

The `incident.resolved` event

POST
webhook.test

The `webhook.test` event

POST
merchant.shipment.created

The `shipment.created` event of a merchant endpoint

POST
merchant.shipment.status_changed

The `shipment.status_changed` event of a merchant endpoint

POST
merchant.shipment.delivered

The `shipment.delivered` event of a merchant endpoint

POST
merchant.shipment.delivery_failed

The `shipment.delivery_failed` event of a merchant endpoint

POST
merchant.webhook.test

The `webhook.test` event of a merchant endpoint

POST