shipping.nc API

Shipper accounts

Server

The businesses that ship with the carrier on account.


List shipper accounts

GET
https://api.shipping.nc
/v1/shipper-accounts

Newest first, cursor paginated: pass next_cursor back as cursor to get the next page. Filters combine with AND. Allowed to carrier admins and dispatchers.

List shipper accounts › 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
status
​string

Comma-separated statuses to keep.

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

Keep the accounts billed with this rate card.

created_from
​

Created at or after this instant, or from the start of this Noumea day.

created_to
​

Created before this instant, or up to the end of this Noumea day.

q
​string · minLength: 1 · maxLength: 100

Account name, RIDET or contact name.

Example: Élégance

List shipper accounts › Headers

x-correlation-id
​string · maxLength: 128

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

List shipper accounts › Responses

One page of shipper accounts.

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

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


Open a shipper account

POST
https://api.shipping.nc
/v1/shipper-accounts

A merchant who ships with the carrier and creates its own shipments. Numbered EXP-0001 onwards. Allowed to carrier admins.

Open a shipper account › Headers

x-correlation-id
​string · maxLength: 128

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

Open a shipper account › Request Body

name
​string · minLength: 1 · maxLength: 120 · required
​object · required
​object · required
activity
​string | null · minLength: 1 · maxLength: 120
ridet
​string | null · pattern: ^\d{7}\.\d{3}$

The business identifier in New Caledonia.

Example: 1234567.001
rate_card_id
​string | null · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

The rate card billed to the account; the carrier default when null.

Open a shipper account › Responses

The new shipper account.

id
​string · required
account_number
​string · required

Sequential per carrier.

Example: EXP-0042
name
​string · required
activity
​string | null · required
ridet
​string | null · required
status
​string · enum · required
Enum values:
active
suspended
​object · required

Each field is null only on an account created before contacts were recorded.

​object | null · required

Null only on an account created before pickup addresses were recorded.

​object | null · required

Null when the account is billed with the carrier default rate card.

​object · required

How the account creates its shipments besides the back-office.

shipments_last_30_days
​integer · min: 0 · max: 9007199254740991 · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Get a shipper account

GET
https://api.shipping.nc
/v1/shipper-accounts/{id}

Allowed to carrier admins and dispatchers, and to the shipper users of the account itself.

Get a shipper account › path Parameters

id
​string · uuid · required

The shipper account id.

Get a shipper account › Headers

x-correlation-id
​string · maxLength: 128

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

Get a shipper account › Responses

The shipper account.

id
​string · required
account_number
​string · required

Sequential per carrier.

Example: EXP-0042
name
​string · required
activity
​string | null · required
ridet
​string | null · required
status
​string · enum · required
Enum values:
active
suspended
​object · required

Each field is null only on an account created before contacts were recorded.

​object | null · required

Null only on an account created before pickup addresses were recorded.

​object | null · required

Null when the account is billed with the carrier default rate card.

​object · required

How the account creates its shipments besides the back-office.

shipments_last_30_days
​integer · min: 0 · max: 9007199254740991 · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Update a shipper account

PATCH
https://api.shipping.nc
/v1/shipper-accounts/{id}

Changes only the fields sent. status: suspended stops the account from shipping; active restores it. Allowed to carrier admins.

Update a shipper account › path Parameters

id
​string · uuid · required

The shipper account id.

Update a shipper account › Headers

x-correlation-id
​string · maxLength: 128

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

Update a shipper account › Request Body

name
​string · minLength: 1 · maxLength: 120
activity
​string | null · minLength: 1 · maxLength: 120
ridet
​string | null · pattern: ^\d{7}\.\d{3}$

The business identifier in New Caledonia.

Example: 1234567.001
​object
​object
rate_card_id
​string | null · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

The rate card billed to the account; the carrier default when null.

status
​string · enum
Enum values:
active
suspended

Update a shipper account › Responses

The updated shipper account.

id
​string · required
account_number
​string · required

Sequential per carrier.

Example: EXP-0042
name
​string · required
activity
​string | null · required
ridet
​string | null · required
status
​string · enum · required
Enum values:
active
suspended
​object · required

Each field is null only on an account created before contacts were recorded.

​object | null · required

Null only on an account created before pickup addresses were recorded.

​object | null · required

Null when the account is billed with the carrier default rate card.

​object · required

How the account creates its shipments besides the back-office.

shipments_last_30_days
​integer · min: 0 · max: 9007199254740991 · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Get the shipping activity of an account

GET
https://api.shipping.nc
/v1/shipper-accounts/{id}/activity

Shipments per Noumea week (last 8) or month (last 12), the share delivered at the first attempt and the amount billed, TGC included. Allowed to carrier admins and dispatchers, and to the shipper users of the account.

Get the shipping activity of an account › path Parameters

id
​string · uuid · required

The shipper account id.

Get the shipping activity of an account › query Parameters

period
​string · enum

The last 8 ISO weeks or the last 12 months, the current one included.

Enum values:
8w
12m
Default: 8w

Get the shipping activity of an account › Headers

x-correlation-id
​string · maxLength: 128

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

Get the shipping activity of an account › Responses

The activity over the period.

period
​string · enum · required
Enum values:
8w
12m
​object[] · required

Oldest first, the current week or month last.

shipments
​integer · min: 0 · max: 9007199254740991 · required
delivered_first_attempt_ratio
​number | null · min: 0 · max: 1 · required

Delivered without a failed attempt, among delivered shipments.

Example: 0.91
billed_xpf
​integer · min: 0 · max: 9007199254740991 · required

Total of the shipments, TGC included.

Example: 948650

Get the rate card of an account

GET
https://api.shipping.nc
/v1/shipper-accounts/{id}/rate-card

Its own rate card, or the carrier rate card in force when it has none. Allowed to carrier admins and dispatchers, and to the shipper users of the account.

Get the rate card of an account › path Parameters

id
​string · uuid · required

The shipper account id.

Get the rate card of an account › Headers

x-correlation-id
​string · maxLength: 128

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

Get the rate card of an account › Responses

The rate card and its prices.

id
​string · required
name
​string · required
valid_from
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required
is_carrier_default
​boolean · required

True when the account has no rate card of its own and is billed with the default one.

tgc_rate_basis_points
​integer · min: -9007199254740991 · max: 9007199254740991 · required

TGC rate in basis points (100 = 1%).

Example: 1100
​object[] · required

One price per zone, service and weight bracket; a zone without rate is not served.


List the users of a shipper account

GET
https://api.shipping.nc
/v1/shipper-accounts/{id}/members

Its members and the invitations still pending, newest first, cursor paginated. Allowed to carrier admins.

List the users of a shipper account › path Parameters

id
​string · uuid · required

The shipper account id.

List the users of a shipper account › 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 users of a shipper account › Headers

x-correlation-id
​string · maxLength: 128

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

List the users of a shipper account › Responses

One page of users.

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

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


Invite a user to a shipper account

POST
https://api.shipping.nc
/v1/shipper-accounts/{id}/members

Emails an invitation with the shipper role. Returns 200 with the pending invitation when one already exists. Allowed to carrier admins.

Invite a user to a shipper account › path Parameters

id
​string · uuid · required

The shipper account id.

Invite a user to a shipper account › Headers

x-correlation-id
​string · maxLength: 128

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

Invite a user to a shipper account › Request Body

email
​string · email · maxLength: 254 · pattern: ^(?:[A-Za-z0-9_'+\-]… · required

Invite a user to a shipper account › Responses

The pending invitation that already existed.

id
​string · required
email
​string · required
role
​string · enum · required
Enum values:
carrier_admin
dispatcher
driver
shipper
shipper_account_id
​string | null · required
expires_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
accept_url
​string · uri

The accept link, only in the response that minted the token and only on a stage that sends no invitation email (demo). Elsewhere the email is the only copy.

Example: https://app.demo.shipping.nc/invite#token=8mA2pQ3rS4tU5vW6xY7zA8bC9dE0fG1hI2jK3lM4nO5

List the API keys of a shipper account

GET
https://api.shipping.nc
/v1/shipper-accounts/{id}/api-keys

Newest first, revoked ones included, cursor paginated. Never returns a secret. Allowed to carrier admins and to the shipper users of the account.

List the API keys of a shipper account › path Parameters

id
​string · uuid · required

The shipper account id.

List the API keys of a shipper account › 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 API keys of a shipper account › Headers

x-correlation-id
​string · maxLength: 128

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

List the API keys of a shipper account › Responses

One page of API keys.

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

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


Create an API key

POST
https://api.shipping.nc
/v1/shipper-accounts/{id}/api-keys

The response carries the secret once; only its SHA-256 hash is stored. An integration sends it as Authorization: Bearer <secret> and acts as a shipper user of the account. Allowed to carrier admins and to the shipper users of the account.

Create an API key › path Parameters

id
​string · uuid · required

The shipper account id.

Create an API key › Headers

x-correlation-id
​string · maxLength: 128

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

Create an API key › Request Body

name
​string · pattern: ^[a-z0-9_-]{3,40}$ · required

Create an API key › Responses

The new key, with its secret.

id
​string · required
name
​string · required
prefix
​string · required

The first characters of the key, to recognise it.

Example: shk_7Hq2
status
​string · enum · required
Enum values:
active
revoked
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_used_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
revoked_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
secret
​string · required

The full key, shown once: only its hash is stored. Send it as Authorization: Bearer <key>.

Example: shk_7Hq2vN0cXyRk4mWb9TzL1pQe6sAfJd3uGh8iKo5

Revoke an API key

DELETE
https://api.shipping.nc
/v1/shipper-accounts/{id}/api-keys/{keyId}

The key is refused from the next request on. Revoking again changes nothing. Allowed to carrier admins and to the shipper users of the account.

Revoke an API key › path Parameters

id
​string · uuid · required

The shipper account id.

keyId
​string · uuid · required

The API key id.

Revoke an API key › Headers

x-correlation-id
​string · maxLength: 128

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

Revoke an API key › Responses

The revoked key.

id
​string · required
name
​string · required
prefix
​string · required

The first characters of the key, to recognise it.

Example: shk_7Hq2
status
​string · enum · required
Enum values:
active
revoked
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
last_used_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
revoked_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required