Book your first shipment
This tutorial takes you through the aggregator API with a test key: you quote every carrier, book an offer, print its label, follow the parcel, and cancel it. A test key never reaches a real carrier, so you can run it as often as you like.
Before you start
- Ask shipping.nc for a merchant account. The shipping.nc team creates it and hands you two API keys, shown once:
- a test key,
mk_test_..., answered by the sandbox carrierTransporteur test; - a live key,
mk_live_..., which books the real carriers.
- a test key,
- Keep both keys on your server. Never put them in a web page or a mobile app.
Every request authenticates with the key in the Authorization header:
Code
The examples below use curl and the demo host. Set your key once:
Code
A test key and a live key see different shipments: a shipment booked with one is not found with the other.
Quote every carrier
Send the route and the parcels to POST /v1/aggregator/quotes. The destination is a commune of New Caledonia, written as in the API reference (Nouméa, Koné, Lifou).
Code
The answer lists the offers, cheapest first. With a test key, they are the offers of the sandbox carrier, at the same prices on every run:
Code
Nothing is booked yet. An offer id names a carrier and a service, not a price: keep it to book.
To deliver to a pickup point, list the points with GET /v1/aggregator/pickup-points, then quote with "delivery": "pickup_point" and the relay_point_id of the point the recipient chose.
Book the offer
Send the offer, the sender, the recipient and the parcels to POST /v1/aggregator/shipments, with an Idempotency-Key header. Use a key that is unique for the order, such as its number.
Code
The API answers 201 with the shipment. A test shipment gets a tracking number that starts with ZZ:
Code
If the network fails, send the same request again with the same Idempotency-Key: you get the shipment booked first, never a second one. The same key with another body answers 409 idempotency_key_reused.
The shipment is priced again from the carrier rate card when you book it, so its total_xpf can differ from the quote when the carrier changed its rates in between.
Print the label
Ask for the label document with GET on label_url. It answers with a short-lived download link of a PDF, one 10x15 label per parcel:
Code
Code
Download the PDF before expires_at, print it, and stick each label on its parcel. Use format=A4 for sheets of four labels.
Follow the parcel
Read the status and the history with the tracking number:
Code
The answer gives the status and the events, oldest first, as the public tracking page shows them: the time, a coarse place, and the reason of a failed delivery attempt. It never returns the recipient.
A sandbox shipment moves only when you move it. Ask for the next status with POST /v1/aggregator/shipments/{id}/simulate, as a carrier would record it:
Code
Then out_for_delivery, and delivered, or delivery_failed with a failure_reason such as recipient_absent. A status that cannot follow the current one answers 409 invalid_status_transition. The route accepts test keys only: a live shipment moves when its carrier moves it.
Rather than polling the tracking route, receive the events: see Receive webhooks.
Cancel the shipment
Cancel a shipment the carrier has not picked up yet, while its status is created:
Code
The answer is the shipment, now cancelled. Cancelling it again returns it unchanged, so a retry is safe. Once the carrier has picked the parcels up, the answer is 409 invalid_status_transition.
Stay within the limits
Each key may send about 600 requests a minute in production, and 300 on the demo stage. Above that, the API answers 429 with a Retry-After: 60 header and the error code too_many_requests. Wait for the number of seconds in Retry-After, then retry. Quote once for a cart rather than on every page view.
Go live
When your integration works with the test key, swap it for the live key. Nothing else changes in your code:
- the quotes list the offers of the real carriers that serve the destination, each priced from its own rate card;
- a booking creates the shipment at the carrier, which picks it up, delivers it and tracks it;
- the tracking numbers and labels are the carrier's own.
Register your live webhook endpoints with the live key: a key manages the endpoints of its own mode.
Next steps
- Receive webhooks: follow your shipments without polling.
- API reference: every route of the Aggregator tag, with its fields and errors.