shipping.nc API

Driver devices

Server

Issue a pairing code for a driver

POST
https://api.shipping.nc
/v1/auth/pairing-codes

Carrier admins and dispatchers. The code is valid 10 minutes, works once, and replaces any code of the same driver still waiting. Only its hash is stored: show it now, it cannot be read again.

Issue a pairing code for a driver › Headers

x-correlation-id
​string · maxLength: 128

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

Issue a pairing code for a driver › Request Body

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

The driver membership the phone will act for.

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

Issue a pairing code for a driver › Responses

The code to show, as text and as a QR code of pairing_uri.

code
​string · required

Show it as is, and as a QR code of pairing_uri.

Example: K7QM-4XWD
pairing_uri
​string · required
membership_id
​string · required
expires_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Pair a driver phone

POST
https://api.shipping.nc
/v1/auth/devices/pair

Public, called by the driver app with the code it scanned or the driver typed. Registers the phone and returns its Cognito tokens; the app then refreshes them with the refresh token alone. An unknown, used or expired code gives invalid_pairing_code. The route is rate limited.

Pair a driver phone › Headers

x-correlation-id
​string · maxLength: 128

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

Pair a driver phone › Request Body

code
​string · maxLength: 32 · required

8 characters shown as XXXX-XXXX. Case, spaces and dashes are ignored; O, I and L read as 0, 1, 1.

Example: K7QM-4XWD
​object · required

Pair a driver phone › Responses

The paired device and its tokens.

device_id
​string · required
carrier_id
​string · required
driver_name
​string · required

The driver the phone acts for, to greet them.

Example: Kevin Martin
​object · required

Cognito tokens of the device. Keep the refresh token in the secure storage of the phone.


List driver phones

GET
https://api.shipping.nc
/v1/auth/devices

Carrier admins and dispatchers. Newest pairing first, cursor paginated.

List driver phones › 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
membership_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Keep the phones of one driver membership.

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

List driver phones › Headers

x-correlation-id
​string · maxLength: 128

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

List driver phones › Responses

One page of devices.

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

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

​object · required

The driver app releases each phone is compared with.


Report that a driver phone is alive

POST
https://api.shipping.nc
/v1/auth/devices/heartbeat

Sent by the driver app with a device token. Updates its last sync time, app version and printer.

Report that a driver phone is alive › Headers

x-correlation-id
​string · maxLength: 128

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

Report that a driver phone is alive › Request Body

app_version
​string · minLength: 1 · maxLength: 40 · required
printer_name
​string | null · minLength: 1 · maxLength: 120 · required

The label printer paired with the phone, or null.

Example: Zebra ZQ220
pending_event_count
​integer · min: 0 · max: 100000

Tracking events saved on the phone and not sent yet. Dispatch sees it on the tour.

Example: 2
Default: 0

Report that a driver phone is alive › Responses

Recorded.

No data returned

Revoke a driver phone

POST
https://api.shipping.nc
/v1/auth/devices/{id}/revoke

Carrier admins and dispatchers. The API refuses the phone at once and it can no longer refresh its tokens. Revoking a revoked phone returns it unchanged.

Revoke a driver phone › path Parameters

id
​string · uuid · required

The device id.

Revoke a driver phone › Headers

x-correlation-id
​string · maxLength: 128

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

Revoke a driver phone › Responses

The revoked device.

id
​string · required
membership_id
​string · required
driver_name
​string · required
model
​string · required
os
​string · required
app_version
​string · required
app_version_status
​string · enum · required

up_to_date: the latest driver app. update_available: an older one the API still serves. unsupported: below the minimum version.

Enum values:
up_to_date
update_available
unsupported
printer_name
​string | null · required
pending_event_count
​integer · min: 0 · max: 9007199254740991 · required

Tracking events saved on the phone and not sent yet, as of its last heartbeat.

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

Remove a revoked driver phone

DELETE
https://api.shipping.nc
/v1/auth/devices/{id}

Carrier admins and dispatchers. Takes a revoked phone off the list; what it synced stays. A phone still active is refused with a 409: revoke it first. Removing it again changes nothing.

Remove a revoked driver phone › path Parameters

id
​string · uuid · required

The device id.

Remove a revoked driver phone › Headers

x-correlation-id
​string · maxLength: 128

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

Remove a revoked driver phone › Responses

The phone is off the list.

No data returned