shipping.nc API

Tours

Server

Plan the tours of a day, publish them to the drivers and follow them live.


List tours

GET
https://api.shipping.nc
/v1/dispatch/tours

Newest first, cursor paginated, each tour with its stops, progress and driver phone. Allowed to carrier admins and dispatchers.

List tours › 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
q
​string · minLength: 1 · maxLength: 100

Held anywhere in the tour code, the tour name or the driver name, ignoring case.

Example: 1211-02
date
​string · date · pattern: ^(?:(?:\d\d[2468][04…

A Noumea day.

Example: 2026-11-12
status
​string

Comma-separated statuses to keep.

Example: in_progress

List tours › Headers

x-correlation-id
​string · maxLength: 128

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

List tours › Responses

One page of tours.

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

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


Create a tour

POST
https://api.shipping.nc
/v1/dispatch/tours

A planned tour for a driver on a day, optionally with its first shipments. Allowed to carrier admins and dispatchers.

Create a tour › Headers

x-correlation-id
​string · maxLength: 128

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

Create a tour › Request Body

driver_membership_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required
date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
name
​string · minLength: 1 · maxLength: 80
vehicle_label
​string · minLength: 1 · maxLength: 40
shipment_ids
​string[] · minItems: 1 · maxItems: 100

Create a tour › Responses

The created tour.

id
​string · required
code
​string · required
date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
name
​string | null · required

Given by dispatch.

Example: Dumbéa et Koutio, matin
area
​string · required

Main localities of the stops.

Example: Magenta, Ouemo, Portes de Fer
status
​string · enum · required

planned: dispatch is still building it, drivers do not see it. published: on the driver phone. in_progress: the driver started it. completed: the driver closed it.

Enum values:
planned
published
in_progress
completed
cancelled
version
​integer · max: 9007199254740991 · required
​object · required
depot_name
​string · required
​object · required

A GPS position in decimal degrees (WGS 84).

vehicle_label
​string | null · required
capacity_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
load_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
distance_m
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required
​object · required
planned_start_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
planned_end_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
estimates
​string · enum · required

How times and distances are estimated. road: driving distances and times from the routing provider; a tour planned while the provider did not answer keeps straight-line figures until its next change. straight_line: straight lines at an average speed.

Enum values:
road
straight_line
published_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
started_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
completed_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
​object · required

The paired phone of the driver.

​object | null · required

From the last synced event that carried a GPS position.

​object[] · 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 tour

GET
https://api.shipping.nc
/v1/dispatch/tours/{id}

The live view of a tour: stops, progress, driver phone and last known position. Allowed to carrier admins and dispatchers.

Get a tour › path Parameters

id
​string · uuid · required

The tour id.

Get a tour › Headers

x-correlation-id
​string · maxLength: 128

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

Get a tour › Responses

The tour.

id
​string · required
code
​string · required
date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
name
​string | null · required

Given by dispatch.

Example: Dumbéa et Koutio, matin
area
​string · required

Main localities of the stops.

Example: Magenta, Ouemo, Portes de Fer
status
​string · enum · required

planned: dispatch is still building it, drivers do not see it. published: on the driver phone. in_progress: the driver started it. completed: the driver closed it.

Enum values:
planned
published
in_progress
completed
cancelled
version
​integer · max: 9007199254740991 · required
​object · required
depot_name
​string · required
​object · required

A GPS position in decimal degrees (WGS 84).

vehicle_label
​string | null · required
capacity_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
load_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
distance_m
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required
​object · required
planned_start_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
planned_end_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
estimates
​string · enum · required

How times and distances are estimated. road: driving distances and times from the routing provider; a tour planned while the provider did not answer keeps straight-line figures until its next change. straight_line: straight lines at an average speed.

Enum values:
road
straight_line
published_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
started_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
completed_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
​object · required

The paired phone of the driver.

​object | null · required

From the last synced event that carried a GPS position.

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

Add shipments to a tour

POST
https://api.shipping.nc
/v1/dispatch/tours/{id}/stops

Appends one stop per shipment, a pickup when the parcel is still at the sender. A published or started tour reaches the phone at its next sync. Allowed to carrier admins and dispatchers.

Add shipments to a tour › path Parameters

id
​string · uuid · required

The tour id.

Add shipments to a tour › Headers

x-correlation-id
​string · maxLength: 128

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

Add shipments to a tour › Request Body

shipment_ids
​string[] · minItems: 1 · maxItems: 100 · required

Add shipments to a tour › Responses

The tour.

id
​string · required
code
​string · required
date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
name
​string | null · required

Given by dispatch.

Example: Dumbéa et Koutio, matin
area
​string · required

Main localities of the stops.

Example: Magenta, Ouemo, Portes de Fer
status
​string · enum · required

planned: dispatch is still building it, drivers do not see it. published: on the driver phone. in_progress: the driver started it. completed: the driver closed it.

Enum values:
planned
published
in_progress
completed
cancelled
version
​integer · max: 9007199254740991 · required
​object · required
depot_name
​string · required
​object · required

A GPS position in decimal degrees (WGS 84).

vehicle_label
​string | null · required
capacity_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
load_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
distance_m
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required
​object · required
planned_start_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
planned_end_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
estimates
​string · enum · required

How times and distances are estimated. road: driving distances and times from the routing provider; a tour planned while the provider did not answer keeps straight-line figures until its next change. straight_line: straight lines at an average speed.

Enum values:
road
straight_line
published_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
started_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
completed_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
​object · required

The paired phone of the driver.

​object | null · required

From the last synced event that carried a GPS position.

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

Reorder the stops of a tour

PUT
https://api.shipping.nc
/v1/dispatch/tours/{id}/stops/order

Done and failed stops keep their rank. The driver gets the new order at the next sync. Allowed to carrier admins and dispatchers.

Reorder the stops of a tour › path Parameters

id
​string · uuid · required

The tour id.

Reorder the stops of a tour › Headers

x-correlation-id
​string · maxLength: 128

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

Reorder the stops of a tour › Request Body

stop_ids
​string[] · minItems: 1 · maxItems: 500 · required

Every stop of the tour, in the new order. Done and failed stops keep their rank.

Reorder the stops of a tour › Responses

The tour.

id
​string · required
code
​string · required
date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
name
​string | null · required

Given by dispatch.

Example: Dumbéa et Koutio, matin
area
​string · required

Main localities of the stops.

Example: Magenta, Ouemo, Portes de Fer
status
​string · enum · required

planned: dispatch is still building it, drivers do not see it. published: on the driver phone. in_progress: the driver started it. completed: the driver closed it.

Enum values:
planned
published
in_progress
completed
cancelled
version
​integer · max: 9007199254740991 · required
​object · required
depot_name
​string · required
​object · required

A GPS position in decimal degrees (WGS 84).

vehicle_label
​string | null · required
capacity_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
load_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
distance_m
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required
​object · required
planned_start_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
planned_end_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
estimates
​string · enum · required

How times and distances are estimated. road: driving distances and times from the routing provider; a tour planned while the provider did not answer keeps straight-line figures until its next change. straight_line: straight lines at an average speed.

Enum values:
road
straight_line
published_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
started_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
completed_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
​object · required

The paired phone of the driver.

​object | null · required

From the last synced event that carried a GPS position.

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

Give the remaining stops to another driver

POST
https://api.shipping.nc
/v1/dispatch/tours/{id}/reassign-remaining

Moves the pending stops to the open tour of that driver on the same day, or to a new planned tour. Answers with the receiving tour. Allowed to carrier admins and dispatchers.

Give the remaining stops to another driver › path Parameters

id
​string · uuid · required

The tour id.

Give the remaining stops to another driver › Headers

x-correlation-id
​string · maxLength: 128

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

Give the remaining stops to another driver › Request Body

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

The driver whose tour of the same day takes the pending stops.

Example: e18b4c27-9f3d-4a51-8c6e-0d2b7f4a9e35

Give the remaining stops to another driver › Responses

The tour that received the stops.

id
​string · required
code
​string · required
date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
name
​string | null · required

Given by dispatch.

Example: Dumbéa et Koutio, matin
area
​string · required

Main localities of the stops.

Example: Magenta, Ouemo, Portes de Fer
status
​string · enum · required

planned: dispatch is still building it, drivers do not see it. published: on the driver phone. in_progress: the driver started it. completed: the driver closed it.

Enum values:
planned
published
in_progress
completed
cancelled
version
​integer · max: 9007199254740991 · required
​object · required
depot_name
​string · required
​object · required

A GPS position in decimal degrees (WGS 84).

vehicle_label
​string | null · required
capacity_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
load_grams
​integer · min: -9007199254740991 · max: 9007199254740991 · required
distance_m
​integer | null · min: -9007199254740991 · max: 9007199254740991 · required
​object · required
planned_start_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
planned_end_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
estimates
​string · enum · required

How times and distances are estimated. road: driving distances and times from the routing provider; a tour planned while the provider did not answer keeps straight-line figures until its next change. straight_line: straight lines at an average speed.

Enum values:
road
straight_line
published_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
started_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
completed_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
​object · required

The paired phone of the driver.

​object | null · required

From the last synced event that carried a GPS position.

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

Publish the tours of a day

POST
https://api.shipping.nc
/v1/dispatch/tours/publish

Sends every planned tour of the day that has stops to the phones of its drivers. Allowed to carrier admins and dispatchers.

Publish the tours of a day › Headers

x-correlation-id
​string · maxLength: 128

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

Publish the tours of a day › Request Body

date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12

Publish the tours of a day › Responses

How many tours were published.

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

How many tours went to the driver phones.

Example: 3

Optimize the stop order of the tours of a day

POST
https://api.shipping.nc
/v1/dispatch/tours/optimize

Reorders the pending stops of every open tour of the day. No routing provider is connected yet: the order is nearest neighbour on straight lines, and stops without GPS position go last. Allowed to carrier admins and dispatchers.

Optimize the stop order of the tours of a day › Headers

x-correlation-id
​string · maxLength: 128

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

Optimize the stop order of the tours of a day › Request Body

date
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12

Optimize the stop order of the tours of a day › Responses

The tours of the day.

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

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


List shipments waiting for a tour

GET
https://api.shipping.nc
/v1/dispatch/unassigned-shipments

Shipments that can go on a tour and sit on no open tour, newest first. Allowed to carrier admins and dispatchers.

List shipments waiting for a tour › 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
zone
​string

Comma-separated destination zones to keep.

Example: grand_noumea

List shipments waiting for a tour › Headers

x-correlation-id
​string · maxLength: 128

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

List shipments waiting for a tour › Responses

One page of shipments.

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

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


List drivers

GET
https://api.shipping.nc
/v1/dispatch/drivers

Active driver members, newest first. Allowed to carrier admins and dispatchers.

List drivers › 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 drivers › Headers

x-correlation-id
​string · maxLength: 128

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

List drivers › Responses

One page of drivers.

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

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