# 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 carrier `Transporteur test`;
  - a live key, `mk_live_...`, which books the real carriers.
- 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:

```http
Authorization: Bearer mk_test_...
```

The examples below use `curl` and the demo host. Set your key once:

```sh
export SHIPPING_NC_KEY=mk_test_...
export SHIPPING_NC_API=https://api.demo.shipping.nc
```

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`).

```sh
curl -X POST "$SHIPPING_NC_API/v1/aggregator/quotes" \
  -H "Authorization: Bearer $SHIPPING_NC_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "origin": { "commune": "Nouméa" },
    "destination": { "commune": "Koné" },
    "parcels": [{ "weight_grams": 2400, "length_mm": 400, "width_mm": 300, "height_mm": 200 }],
    "delivery": "home"
  }'
```

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:

```json
{
  "data": [
    {
      "id": "ofr_c2FuZGJveDpob21lX2RlbGl2ZXJ5",
      "carrier": { "id": "sandbox", "name": "Transporteur test" },
      "service_kind": "home_delivery",
      "delivery": "home",
      "delivery_confirmation": "none",
      "zone": "brousse_west",
      "weight_grams": 2400,
      "excluding_tax_xpf": 1000,
      "tgc_xpf": 0,
      "tgc_rate_basis_points": 0,
      "total_xpf": 1000,
      "commission_xpf": 0,
      "sandbox": true
    }
  ]
}
```

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.

```sh
curl -X POST "$SHIPPING_NC_API/v1/aggregator/shipments" \
  -H "Authorization: Bearer $SHIPPING_NC_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: CMD-20931' \
  -d '{
    "offer_id": "ofr_c2FuZGJveDpob21lX2RlbGl2ZXJ5",
    "merchant_reference": "CMD-20931",
    "sender": { "name": "Boutique du Caillou", "phone": "254321", "address_lines": ["12 rue Jules Garnier"], "commune": "Nouméa" },
    "recipient": {
      "name": "Marie Martin",
      "phone": "781234",
      "address_lines": ["4 rue des Cocotiers"],
      "commune": "Koné",
      "landmark": "Blue gate after the bakery"
    },
    "parcels": [{ "weight_grams": 2400, "description": "Clothes" }]
  }'
```

The API answers `201` with the shipment. A test shipment gets a tracking number that starts with `ZZ`:

```json
{
  "id": "0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10",
  "tracking_number": "ZZ000000014",
  "status": "created",
  "carrier": { "id": "sandbox", "name": "Transporteur test" },
  "service_kind": "home_delivery",
  "delivery": "home",
  "delivery_confirmation": "none",
  "merchant_reference": "CMD-20931",
  "excluding_tax_xpf": 1000,
  "tgc_xpf": 0,
  "tgc_rate_basis_points": 0,
  "total_xpf": 1000,
  "commission_xpf": 0,
  "sandbox": true,
  "label_url": "/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/label",
  "created_at": "2026-11-16T08:00:00.000Z"
}
```

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:

```sh
curl "$SHIPPING_NC_API/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/label?format=10x15&locale=fr" \
  -H "Authorization: Bearer $SHIPPING_NC_KEY"
```

```json
{
  "url": "https://...",
  "expires_at": "2026-11-16T08:15:00.000Z",
  "format": "10x15",
  "label_count": 1,
  "shipment_count": 1
}
```

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:

```sh
curl "$SHIPPING_NC_API/v1/aggregator/tracking/ZZ000000014" \
  -H "Authorization: Bearer $SHIPPING_NC_KEY"
```

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:

```sh
curl -X POST "$SHIPPING_NC_API/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/simulate" \
  -H "Authorization: Bearer $SHIPPING_NC_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "status": "picked_up" }'
```

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](/merchants/webhooks).

## Cancel the shipment

Cancel a shipment the carrier has not picked up yet, while its status is `created`:

```sh
curl -X POST "$SHIPPING_NC_API/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/cancel" \
  -H "Authorization: Bearer $SHIPPING_NC_KEY"
```

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](/merchants/webhooks): follow your shipments without polling.
- [API reference](/reference): every route of the Aggregator tag, with its fields and errors.
