shipping.nc API

Pickup point counter

Server

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.


Get the signed-in counter

GET
https://api.shipping.nc
/v1/relay/counter/me

The person and the pickup point they work at.

Get the signed-in counter › Headers

x-correlation-id
​string · maxLength: 128

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

Get the signed-in counter › Responses

The person and their pickup point.

user_id
​string · required
full_name
​string · required
email
​string · required
​object · required

List the parcels of the point

GET
https://api.shipping.nc
/v1/relay/counter/parcels

Every parcel addressed to the point, newest first: expected, waiting at the counter, collected or returned.

List the parcels of the point › query Parameters

status
​string · enum

expected: addressed to the point. arrived: the driver left it at the point, which has not checked it in yet. held: checked in, waiting for the recipient. collected: handed over to the recipient. returned: given back to the carrier after the holding period.

Enum values:
expected
arrived
held
collected
returned

List the parcels of the point › Headers

x-correlation-id
​string · maxLength: 128

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

List the parcels of the point › Responses

The parcels.

​object[] · required

Check a parcel in

POST
https://api.shipping.nc
/v1/relay/counter/check-ins

The counter scanned or typed the tracking number of a parcel addressed to the point. The holding period starts when the parcel arrives, and the recipient is told it waits there. Checking a parcel in again changes nothing.

Check a parcel in › Headers

x-correlation-id
​string · maxLength: 128

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

Check a parcel in › Request Body

tracking_number
​string · required

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

Example: SN000000014

Check a parcel in › Responses

The parcel, now held.

id
​string · required
tracking_number
​string · required
carrier_name
​string · required
recipient_name
​string · required
status
​string · enum · required

expected: addressed to the point. arrived: the driver left it at the point, which has not checked it in yet. held: checked in, waiting for the recipient. collected: handed over to the recipient. returned: given back to the carrier after the holding period.

Enum values:
expected
arrived
held
collected
returned
expected_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
arrived_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
checked_in_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
hold_until
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
is_overdue
​boolean · required

Held past the holding period: the counter may return it.

collected_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
returned_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
code_attempts_left
​integer · min: 0 · max: 9007199254740991 · required

How many more wrong recipient codes the counter may type before the handover locks. Five from the start.

handover_locked
​boolean · required

Too many wrong codes were typed: the parcel cannot be handed over until its carrier issues a new code.


Hand a parcel over to its recipient

POST
https://api.shipping.nc
/v1/relay/counter/parcels/{id}/handover

The recipient shows the six-digit code they received by text message. A wrong code answers a 422 whose details.codes_left tells how many more the counter may type; after five wrong codes the handover of the parcel is locked (handover_locked) and answers a 409 until its carrier issues a new code.

Hand a parcel over to its recipient › path Parameters

id
​string · minLength: 1 · required

Hand a parcel over to its recipient › Headers

x-correlation-id
​string · maxLength: 128

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

Hand a parcel over to its recipient › Request Body

code
​string · pattern: ^\d{6}$ · required

The six-digit code the recipient received by text message.

Example: 482915

Hand a parcel over to its recipient › Responses

The parcel, now collected.

id
​string · required
tracking_number
​string · required
carrier_name
​string · required
recipient_name
​string · required
status
​string · enum · required

expected: addressed to the point. arrived: the driver left it at the point, which has not checked it in yet. held: checked in, waiting for the recipient. collected: handed over to the recipient. returned: given back to the carrier after the holding period.

Enum values:
expected
arrived
held
collected
returned
expected_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
arrived_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
checked_in_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
hold_until
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
is_overdue
​boolean · required

Held past the holding period: the counter may return it.

collected_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
returned_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
code_attempts_left
​integer · min: 0 · max: 9007199254740991 · required

How many more wrong recipient codes the counter may type before the handover locks. Five from the start.

handover_locked
​boolean · required

Too many wrong codes were typed: the parcel cannot be handed over until its carrier issues a new code.


Give a parcel back to its carrier

POST
https://api.shipping.nc
/v1/relay/counter/parcels/{id}/return

Only once the holding period ran out without the recipient.

Give a parcel back to its carrier › path Parameters

id
​string · minLength: 1 · required

Give a parcel back to its carrier › Headers

x-correlation-id
​string · maxLength: 128

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

Give a parcel back to its carrier › Responses

The parcel, now returned.

id
​string · required
tracking_number
​string · required
carrier_name
​string · required
recipient_name
​string · required
status
​string · enum · required

expected: addressed to the point. arrived: the driver left it at the point, which has not checked it in yet. held: checked in, waiting for the recipient. collected: handed over to the recipient. returned: given back to the carrier after the holding period.

Enum values:
expected
arrived
held
collected
returned
expected_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
arrived_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
checked_in_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
hold_until
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
is_overdue
​boolean · required

Held past the holding period: the counter may return it.

collected_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
returned_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
code_attempts_left
​integer · min: 0 · max: 9007199254740991 · required

How many more wrong recipient codes the counter may type before the handover locks. Five from the start.

handover_locked
​boolean · required

Too many wrong codes were typed: the parcel cannot be handed over until its carrier issues a new code.