shipping.nc API

Aggregator

Server

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.


Quote every carrier

POST
https://api.shipping.nc
/v1/aggregator/quotes

The offers of every active carrier that sells the delivery and serves the destination at that weight, each priced from the carrier own rate card, cheapest first. Nothing is booked. With delivery pickup_point and a relay_point_id, the offers are priced for the commune of the point.

Quote every carrier › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Quote every carrier › Request Body

What decides the offers: the route, the parcels and the delivery.
​object · required

Where the carrier picks the parcels up.

​object · required

Where the parcels go. With pickup_point, the commune of the point replaces it.

​object[] · minItems: 1 · maxItems: 50 · required
delivery
​string · enum

home: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.

Enum values:
home
pickup_point
Default: home
relay_point_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

With delivery pickup_point: the point the recipient collects the parcels at, from GET /v1/aggregator/pickup-points. Without it, the offers are priced for the destination commune.

Example: 8c2f4e61-3b7a-4d95-a0e8-5f1c9d2b7a43
signature
​boolean

Ask the recipient to sign at delivery.

Default: false

Quote every carrier › Responses

The offers, cheapest first.

​object[] · required

Cheapest first.


Book a shipment

POST
https://api.shipping.nc
/v1/aggregator/shipments

Books the chosen offer. A live key creates the shipment at the carrier, which plans, delivers and tracks it; a test key creates a sandbox shipment that no carrier sees. The shipment is priced again from the carrier rate card in effect, so its price can differ from the quote when the carrier changed its rates in between. With a pickup point offer, relay_point_id is required and the parcels go to the address of the point.

Book a shipment › Headers

Idempotency-Key
​string · minLength: 1 · maxLength: 255 · required

Your unique key for this booking, such as the order id. A retry with the same key and body returns the shipment booked first; the same key with another body answers 409 idempotency_key_reused.

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Book a shipment › Request Body

The shipment to book with the chosen offer.
offer_id
​string · minLength: 1 · required

An offer of POST /v1/aggregator/quotes.

Example: ofr_MmU4ZDRjNjEtN2EzZi00YjllLThjMTUtNmYwYTFkM2U1YjcyOmhvbWVfZGVsaXZlcnk
​object · required
​object · required
​object[] · minItems: 1 · maxItems: 50 · required
merchant_reference
​string · minLength: 1 · maxLength: 60

Your own reference, such as the order number.

Example: CMD-20931
declared_value_xpf
​integer · min: 0 · max: 9007199254740991

Declared value of the content, in whole XPF.

Example: 15000
relay_point_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Required with a pickup point offer, refused otherwise: the point the recipient collects the parcels at. Its address replaces the recipient address.

Example: 8c2f4e61-3b7a-4d95-a0e8-5f1c9d2b7a43
signature
​boolean

Ask the recipient to sign at delivery.

Default: false

Book a shipment › Responses

The shipment booked.

A shipment booked through the aggregator.
id
​string · required
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
​object · required
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery
​string · enum · required

home: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.

Enum values:
home
pickup_point
delivery_confirmation
​string · enum · required
Enum values:
none
signature
otp
merchant_reference
​string | null · required
excluding_tax_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_rate_basis_points
​integer · min: 0 · max: 10000 · required
total_xpf
​integer · min: 0 · max: 9007199254740991 · required

The price at booking, TGC included.

Example: 1450
commission_xpf
​integer · min: 0 · max: 9007199254740991 · required

The commission of shipping.nc, not set yet.

Example: 0
sandbox
​boolean · required

True for a shipment of a test key, which no carrier sees.

label_url
​string · required

The API path that hands out the label.

Example: /v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/label
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Cancel a shipment

POST
https://api.shipping.nc
/v1/aggregator/shipments/{id}/cancel

Cancels a shipment the carrier has not picked up yet (status created); once picked up, the answer is 409 invalid_status_transition. The carrier sees the cancellation in its history, recorded by the merchant. Cancelling a cancelled shipment again returns it unchanged, so a retry is safe. Returns are not available yet.

Cancel a shipment › path Parameters

id
​string · minLength: 1 · required

Cancel a shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Cancel a shipment › Responses

The shipment, now cancelled.

A shipment booked through the aggregator.
id
​string · required
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
​object · required
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery
​string · enum · required

home: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.

Enum values:
home
pickup_point
delivery_confirmation
​string · enum · required
Enum values:
none
signature
otp
merchant_reference
​string | null · required
excluding_tax_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_rate_basis_points
​integer · min: 0 · max: 10000 · required
total_xpf
​integer · min: 0 · max: 9007199254740991 · required

The price at booking, TGC included.

Example: 1450
commission_xpf
​integer · min: 0 · max: 9007199254740991 · required

The commission of shipping.nc, not set yet.

Example: 0
sandbox
​boolean · required

True for a shipment of a test key, which no carrier sees.

label_url
​string · required

The API path that hands out the label.

Example: /v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/label
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Move a test shipment

POST
https://api.shipping.nc
/v1/aggregator/shipments/{id}/simulate

Test keys only. Moves a sandbox shipment to the next status, as a carrier would: picked_up, then in_transit or out_for_delivery, then delivered or delivery_failed (with a failure_reason), and so on. The tracking shows the new status, and the test webhook endpoints receive its events. A status that cannot follow the current one answers 409 invalid_status_transition. A live key gets 404: only the carrier moves a live shipment.

Move a test shipment › path Parameters

id
​string · minLength: 1 · required

Move a test shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Move a test shipment › Request Body

status
​string · enum · required

The next status. It must follow the current one, as a carrier would move the shipment.

Enum values:
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
returned_to_sender
failure_reason
​string · enum

Required with delivery_failed, refused with any other status.

Enum values:
recipient_absent
address_not_found
refused
no_access
damaged
id_check_failed
pickup_code_missing

Move a test shipment › Responses

The shipment, in its new status.

A shipment booked through the aggregator.
id
​string · required
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
​object · required
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery
​string · enum · required

home: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.

Enum values:
home
pickup_point
delivery_confirmation
​string · enum · required
Enum values:
none
signature
otp
merchant_reference
​string | null · required
excluding_tax_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_rate_basis_points
​integer · min: 0 · max: 10000 · required
total_xpf
​integer · min: 0 · max: 9007199254740991 · required

The price at booking, TGC included.

Example: 1450
commission_xpf
​integer · min: 0 · max: 9007199254740991 · required

The commission of shipping.nc, not set yet.

Example: 0
sandbox
​boolean · required

True for a shipment of a test key, which no carrier sees.

label_url
​string · required

The API path that hands out the label.

Example: /v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/label
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Get the label of a shipment

GET
https://api.shipping.nc
/v1/aggregator/shipments/{id}/label

Renders the label of the shipment as a PDF, one label per parcel, and hands back a short-lived download link. Print it and stick it on each parcel before the carrier picks them up.

Get the label of a shipment › path Parameters

id
​string · minLength: 1 · required

Get the label of a shipment › query Parameters

format
​string · enum

A 10x15 sticker per parcel, or A4 sheets of four.

Enum values:
10x15
A4
Default: 10x15
locale
​string · enum

Language of the label captions.

Enum values:
fr
en
Default: fr

Get the label of a shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get the label of a shipment › Responses

A download link of the label document.

url
​string · required

A short-lived download link of the document.

expires_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
format
​string · enum · required
Enum values:
10x15
A4
zpl
label_count
​integer · max: 9007199254740991 · required

One label per parcel.

Example: 9
shipment_count
​integer · max: 9007199254740991 · required

Search the pickup points

GET
https://api.shipping.nc
/v1/aggregator/pickup-points

The shops of the shipping.nc network where a recipient can collect a parcel, for a checkout page: name, address, position, opening hours, shop phone, and whether the point takes a parcel now. Closed points are left out. Filter by commune, or by near_lat and near_lng for the nearest first within radius_km. Pass the id of the chosen point as relay_point_id to quote and book a pickup point delivery.

Search the pickup points › query Parameters

commune
​string · enum

A commune of New Caledonia.

Enum values:
Nouméa
Dumbéa
Mont-Dore
Païta
Boulouparis
La Foa
Farino
Sarraméa
near_lat
​number · min: -90 · max: 90
near_lng
​number · min: -180 · max: 180
radius_km
​number · max: 500

With near_lat and near_lng: only the points within this distance, nearest first.

Default: 10
limit
​integer · min: 1 · max: 100
Default: 20

Search the pickup points › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Search the pickup points › Responses

The pickup points.

​object[] · required

Get a pickup point

GET
https://api.shipping.nc
/v1/aggregator/pickup-points/{id}

One shop of the network, with its address, opening hours and whether it takes a parcel now.

Get a pickup point › path Parameters

id
​string · minLength: 1 · required

Get a pickup point › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get a pickup point › Responses

The pickup point.

A shop of the shipping.nc network that holds parcels for recipients.
id
​string · required
name
​string · required
address_lines
​string[] · required
postal_code
​string | null · required
commune
​string · enum · required

A commune of New Caledonia.

Enum values:
Nouméa
Dumbéa
Mont-Dore
Païta
Boulouparis
La Foa
Farino
Sarraméa
​object · required

A GPS position in decimal degrees (WGS 84).

​array · minItems: 7 · maxItems: 7 · required
phone
​string | null · required

The shop phone number, in E.164 format.

status
​string · enum · required

active: takes new parcels. paused: hands over the parcels it holds but takes no new one. closed: left the network.

Enum values:
active
paused
closed
accepts_parcels
​boolean · required

Whether a new parcel can be addressed to the point now: active and not full.

distance_m
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required

The straight-line distance from the near position, when one was given.


Track a shipment

GET
https://api.shipping.nc
/v1/aggregator/tracking/{tracking_number}

The status and the history of a shipment the merchant booked, oldest event first, as the carrier records them: the time, a coarse place and the reason of a failed attempt. No recipient field, actor, note or position is returned. A test key tracks only its sandbox shipments, a live key only its live ones.

Track a shipment › path Parameters

tracking_number
​string · required

Two-letter carrier prefix, 8 digits and a check digit. Spaces and case are ignored.

Example: SN000000014

Track a shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Track a shipment › Responses

The tracking of the shipment.

Where a shipment of the merchant is, oldest event first: what the public tracking page shows, without any recipient field.
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery_confirmation
​string · enum · required

What the recipient must do at the door.

Enum values:
none
signature
otp
destination_zone
​string · enum · required
Enum values:
grand_noumea
brousse_west
brousse_east
loyalty_islands
isle_of_pines
parcel_count
​integer · min: 1 · max: 9007199254740991 · required
​object | null · required

When the next delivery attempt is expected: the window of the current attempt while out for delivery, the next attempt after a failed one. null when unknown.

failure_reason
​string | null · enum · required

Why the last attempt failed, while the status is delivery_failed.

Enum values:
recipient_absent
address_not_found
refused
no_access
damaged
id_check_failed
pickup_code_missing
​object[] · required
id
​string · required
​object · required
delivery
​string · enum · required

home: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.

Enum values:
home
pickup_point
merchant_reference
​string | null · required
sandbox
​boolean · required

True for a shipment of a test key, which no carrier sees.


List webhook endpoints

GET
https://api.shipping.nc
/v1/aggregator/webhook-endpoints

Newest first, cursor paginated. Never returns a secret. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

List webhook endpoints › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of items in the page.

Example: 25
Default: 25
cursor
​string

The next_cursor of the previous page, passed back as is. Omit it to get the first page.

Example: WyIyMDI2LTExLTExVDA4OjQyOjEwLjAwMFoiLCIwYjZmOWMxZS01ZDJhLTRjM2UtOWYxYS03ZTJkOGM0YjZhMTAiXQ

List webhook endpoints › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List webhook endpoints › Responses

One page of endpoints.

​object[] · required
next_cursor
​string | null · required

Pass it as cursor to get the next page. null on the last page.


Create a webhook endpoint

POST
https://api.shipping.nc
/v1/aggregator/webhook-endpoints

The response carries the signing secret once. Each delivery is a POST of a JSON event about one of your shipments: data.shipment as the booking returns it, and data.tracking_event for a status change. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

Create a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Create a webhook endpoint › Request Body

url
​string · uri · maxLength: 2048 · required

An https URL on a public host name. Addresses that resolve to a private, loopback or link-local network are refused when the event is sent.

Example: https://shop.example.nc/hooks/shipping
event_types
​string[] · minItems: 1 · maxItems: 4 · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
description
​string · maxLength: 200

Create a webhook endpoint › Responses

The new endpoint, with its signing secret.

id
​string · required
url
​string · required
description
​string | null · required
status
​string · enum · required
Enum values:
enabled
disabled
disabled_reason
​string | null · enum · required

manual: someone disabled it. failing: every attempt failed for a day, so it was disabled.

Enum values:
manual
failing
secret_prefix
​string · required

The first characters of the signing secret, to recognise it.

Example: whsec_Q2vN
failure_streak
​integer · min: 0 · max: 9007199254740991 · required

Attempts that failed in a row since the last success.

failing_since
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
event_types
​string[] · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
mode
​string · enum · required

test: receives the sandbox shipments. live: receives the live shipments.

Enum values:
test
live
secret
​string · required

The signing secret, shown once. Use it to check the Shipping-Nc-Signature header of each delivery.

Example: whsec_Q2vN0cXyRk4mWb9TzL1pQe6sAfJd3uGh8iKo5aB7cD9

Get a webhook endpoint

GET
https://api.shipping.nc
/v1/aggregator/webhook-endpoints/{id}

A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

Get a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Get a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get a webhook endpoint › Responses

The endpoint.

id
​string · required
url
​string · required
description
​string | null · required
status
​string · enum · required
Enum values:
enabled
disabled
disabled_reason
​string | null · enum · required

manual: someone disabled it. failing: every attempt failed for a day, so it was disabled.

Enum values:
manual
failing
secret_prefix
​string · required

The first characters of the signing secret, to recognise it.

Example: whsec_Q2vN
failure_streak
​integer · min: 0 · max: 9007199254740991 · required

Attempts that failed in a row since the last success.

failing_since
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
event_types
​string[] · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
mode
​string · enum · required

test: receives the sandbox shipments. live: receives the live shipments.

Enum values:
test
live

Change a webhook endpoint

PATCH
https://api.shipping.nc
/v1/aggregator/webhook-endpoints/{id}

Changes only the fields sent. Disabling an endpoint gives up its pending deliveries; enabling it again clears its failure count. The secret never changes. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

Change a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Change a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Change a webhook endpoint › Request Body

url
​string · uri · maxLength: 2048

An https URL on a public host name. Addresses that resolve to a private, loopback or link-local network are refused when the event is sent.

Example: https://shop.example.nc/hooks/shipping
description
​string | null · maxLength: 200
event_types
​string[] · minItems: 1 · maxItems: 4
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
status
​string · enum

Enabling an endpoint again clears its failure count.

Enum values:
enabled
disabled

Change a webhook endpoint › Responses

The endpoint.

id
​string · required
url
​string · required
description
​string | null · required
status
​string · enum · required
Enum values:
enabled
disabled
disabled_reason
​string | null · enum · required

manual: someone disabled it. failing: every attempt failed for a day, so it was disabled.

Enum values:
manual
failing
secret_prefix
​string · required

The first characters of the signing secret, to recognise it.

Example: whsec_Q2vN
failure_streak
​integer · min: 0 · max: 9007199254740991 · required

Attempts that failed in a row since the last success.

failing_since
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
event_types
​string[] · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
mode
​string · enum · required

test: receives the sandbox shipments. live: receives the live shipments.

Enum values:
test
live

Delete a webhook endpoint

DELETE
https://api.shipping.nc
/v1/aggregator/webhook-endpoints/{id}

Deletes the endpoint and its delivery log. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

Delete a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Delete a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Delete a webhook endpoint › Responses

The endpoint is deleted.

No data returned

List the deliveries of a webhook endpoint

GET
https://api.shipping.nc
/v1/aggregator/webhook-endpoints/{id}/deliveries

Newest first, cursor paginated: what was sent, how many attempts, the last answer. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

List the deliveries of a webhook endpoint › path Parameters

id
​string · uuid · required

The webhook endpoint id.

List the deliveries of a webhook endpoint › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of items in the page.

Example: 25
Default: 25
cursor
​string

The next_cursor of the previous page, passed back as is. Omit it to get the first page.

Example: WyIyMDI2LTExLTExVDA4OjQyOjEwLjAwMFoiLCIwYjZmOWMxZS01ZDJhLTRjM2UtOWYxYS03ZTJkOGM0YjZhMTAiXQ

List the deliveries of a webhook endpoint › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List the deliveries of a webhook endpoint › Responses

One page of deliveries.

​object[] · required
next_cursor
​string | null · required

Pass it as cursor to get the next page. null on the last page.


Send a test event

POST
https://api.shipping.nc
/v1/aggregator/webhook-endpoints/{id}/test

Sends a signed webhook.test event now, tried once, and answers with the outcome. The endpoint must be enabled. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

Send a test event › path Parameters

id
​string · uuid · required

The webhook endpoint id.

Send a test event › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Send a test event › Responses

The delivery of the test event.

id
​string · required
endpoint_id
​string · required
event_id
​string · required

The id of the event sent. A replay sends the same event id again.

event_type
​string · enum · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
webhook.test
status
​string · enum · required

pending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.

Enum values:
pending
succeeded
failed
attempts
​integer · min: 0 · max: 9007199254740991 · required
next_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_status_code
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required

The HTTP status of the last answer, if any.

last_error
​string | null · required

Why the last attempt failed.

Example: The endpoint answered 503
replay_of
​string | null · required

The delivery this one replays, if any.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
delivered_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Replay a delivery

POST
https://api.shipping.nc
/v1/aggregator/webhook-endpoints/{id}/deliveries/{deliveryId}/replay

Sends the event of a delivery again now, under the same event id, as a new delivery with its own retries. The endpoint must be enabled. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.

Replay a delivery › path Parameters

id
​string · uuid · required

The webhook endpoint id.

deliveryId
​string · uuid · required

The delivery id.

Replay a delivery › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Replay a delivery › Responses

The new delivery.

id
​string · required
endpoint_id
​string · required
event_id
​string · required

The id of the event sent. A replay sends the same event id again.

event_type
​string · enum · required
Enum values:
shipment.created
shipment.status_changed
shipment.delivered
shipment.delivery_failed
incident.opened
incident.resolved
webhook.test
status
​string · enum · required

pending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.

Enum values:
pending
succeeded
failed
attempts
​integer · min: 0 · max: 9007199254740991 · required
next_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_attempt_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_status_code
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required

The HTTP status of the last answer, if any.

last_error
​string | null · required

Why the last attempt failed.

Example: The endpoint answered 503
replay_of
​string | null · required

The delivery this one replays, if any.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
delivered_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required