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