shipping.nc API

Shipment imports

Server

Create many shipments at once from a spreadsheet export, checked row by row before anything is created.


Upload a CSV file of shipments

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

Reads the file (UTF-8, comma or semicolon, header row first, at most 1,000 rows), maps each column from its header or from the mapping saved for the shipper, and checks every row. Nothing is created yet. Allowed to carrier admins and dispatchers, and to shipper users, whose imports are always billed to their account.

Upload a CSV file of shipments › Headers

x-correlation-id
​string · maxLength: 128

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

Upload a CSV file of shipments › Request Body

file_name
​string · minLength: 1 · maxLength: 200 · required
content
​string · minLength: 1 · maxLength: 1000000 · required

The CSV text, UTF-8, header row first; commas or semicolons.

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

The account billed; null for counter customers.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67
Default: null

Upload a CSV file of shipments › Responses

The import, its columns and its row problems.

id
​string · required
file_name
​string · required
delimiter
​string · enum · required
Enum values:
,
;
row_count
​integer · min: 0 · max: 9007199254740991 · required

Data rows, header excluded.

Example: 48
created_by_name
​string · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
shipper_account_id
​string | null · required
status
​string · enum · required

draft until shipments are created, creating while some remain, then completed.

Enum values:
draft
creating
completed
​object[] · required
ready_count
​integer · min: 0 · max: 9007199254740991 · required
​object[] · required

One entry per problem; a row with errors is skipped unless corrected.

estimated_total_xpf
​integer · min: 0 · max: 9007199254740991 · required

Ready rows, TGC included.

Example: 52300
created_count
​integer · min: 0 · max: 9007199254740991 · required

Shipments created so far.

​object[] · required

The shipments created, by file line.


Get an import

GET
https://api.shipping.nc
/v1/shipments/imports/{importId}

Its columns, its row problems and the shipments created so far. Allowed to carrier admins and dispatchers, and to shipper users, whose imports are always billed to their account.

Get an import › path Parameters

importId
​string · uuid · required

The import id.

Get an import › Headers

x-correlation-id
​string · maxLength: 128

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

Get an import › Responses

The import.

id
​string · required
file_name
​string · required
delimiter
​string · enum · required
Enum values:
,
;
row_count
​integer · min: 0 · max: 9007199254740991 · required

Data rows, header excluded.

Example: 48
created_by_name
​string · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
shipper_account_id
​string | null · required
status
​string · enum · required

draft until shipments are created, creating while some remain, then completed.

Enum values:
draft
creating
completed
​object[] · required
ready_count
​integer · min: 0 · max: 9007199254740991 · required
​object[] · required

One entry per problem; a row with errors is skipped unless corrected.

estimated_total_xpf
​integer · min: 0 · max: 9007199254740991 · required

Ready rows, TGC included.

Example: 52300
created_count
​integer · min: 0 · max: 9007199254740991 · required

Shipments created so far.

​object[] · required

The shipments created, by file line.


Change the mapping or correct rows

PATCH
https://api.shipping.nc
/v1/shipments/imports/{importId}

Changes the field of each column, the account billed, or the value of a cell, and checks the rows again. A new mapping is saved as the template of the shipper account. Refused once shipments were created. Allowed to carrier admins and dispatchers, and to shipper users, whose imports are always billed to their account.

Change the mapping or correct rows › path Parameters

importId
​string · uuid · required

The import id.

Change the mapping or correct rows › Headers

x-correlation-id
​string · maxLength: 128

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

Change the mapping or correct rows › Request Body

mapping
​string[]

The field of each column, in file order.

Enum values:
recipient_name
recipient_phone
recipient_email
address_line_1
address_line_2
commune
landmark
weight_grams
​object[] · maxItems: 1000
shipper_account_id
​string | null · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Change the mapping or correct rows › Responses

The import, checked again.

id
​string · required
file_name
​string · required
delimiter
​string · enum · required
Enum values:
,
;
row_count
​integer · min: 0 · max: 9007199254740991 · required

Data rows, header excluded.

Example: 48
created_by_name
​string · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
shipper_account_id
​string | null · required
status
​string · enum · required

draft until shipments are created, creating while some remain, then completed.

Enum values:
draft
creating
completed
​object[] · required
ready_count
​integer · min: 0 · max: 9007199254740991 · required
​object[] · required

One entry per problem; a row with errors is skipped unless corrected.

estimated_total_xpf
​integer · min: 0 · max: 9007199254740991 · required

Ready rows, TGC included.

Example: 52300
created_count
​integer · min: 0 · max: 9007199254740991 · required

Shipments created so far.

​object[] · required

The shipments created, by file line.


Create the shipments of an import

POST
https://api.shipping.nc
/v1/shipments/imports/{importId}/shipments

Creates the shipments of the next 25 ready rows; call again until status is completed. Rows with problems are skipped. Safe to retry: a row never creates two shipments. Allowed to carrier admins and dispatchers, and to shipper users, whose imports are always billed to their account.

Create the shipments of an import › path Parameters

importId
​string · uuid · required

The import id.

Create the shipments of an import › Headers

x-correlation-id
​string · maxLength: 128

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

Create the shipments of an import › Responses

The import, with the shipments created so far.

id
​string · required
file_name
​string · required
delimiter
​string · enum · required
Enum values:
,
;
row_count
​integer · min: 0 · max: 9007199254740991 · required

Data rows, header excluded.

Example: 48
created_by_name
​string · required
created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
shipper_account_id
​string | null · required
status
​string · enum · required

draft until shipments are created, creating while some remain, then completed.

Enum values:
draft
creating
completed
​object[] · required
ready_count
​integer · min: 0 · max: 9007199254740991 · required
​object[] · required

One entry per problem; a row with errors is skipped unless corrected.

estimated_total_xpf
​integer · min: 0 · max: 9007199254740991 · required

Ready rows, TGC included.

Example: 52300
created_count
​integer · min: 0 · max: 9007199254740991 · required

Shipments created so far.

​object[] · required

The shipments created, by file line.