Skip to content
Documentation sections

Sandbox and test shipments

The Container Tracking API provides test shipments that cost nothing to query, to test an integration before tracking real shipments. Their numbers start with ZZZZ. Every endpoint and parameter behaves as in production, and every response has its dates shifted to the current date, so the tracking data always looks recent.

Use a test shipment

Send the test shipment number as shipmentNumber in a request to the endpoint GET /shipment:

curl "https://api.sinay.ai/container-tracking/api/v2/shipment?shipmentNumber=ZZZZ0000000" \
  -H "API_KEY: $SAFECUBE_API_KEY"

Static test shipments

Static test shipments return fixed data that never changes over time. Use them to test consistent, predictable responses.

Shipment numberResponse
ZZZZ0000000A complete, healthy shipment from Le Havre to Rotterdam, with its full event history.
ZZZZ0000001A provider error: the shipping line could not be autodetected (AUTO_CANT_DETECT_SEALINE).
ZZZZ0000002A provider error: the shipping line returned no information (SEALINE_HASNT_PROVIDE_INFO).

The Error codes page explains each error code.

Dynamic test shipments

Dynamic test shipments simulate real-world scenarios, with tracking data that evolves: position updates, status changes and new events. Each one covers a different situation.

Shipment numberScenario
ZZZZ100000Full nominal lifecycle: PLANNED, then IN_TRANSIT, then DELIVERED, then a reset to a new voyage.
ZZZZ200000A voyage with provider errors injected at some stages, such as SEALINE_HASNT_PROVIDE_INFO and SEALINE_UNDER_MAINTENANCE.
ZZZZ300000A nominal voyage with a transhipment: Le Havre, then Antwerp, then Rotterdam.

Each dynamic test shipment goes through 7 stages. It can be queried two ways.

Automatic daily evolution

Query the base number, 10 characters long, such as ZZZZ100000. The stage returned matches the current day of the week — Monday is stage 1, Sunday is stage 7 — so it changes automatically every day and cycles every week. Use it for live demos that progress on their own.

Pinned stage

Append a digit from 1 to 7 to the base number, 11 characters in all, to freeze a stage whatever the date. Use it for deterministic, reproducible automated tests.

  • ZZZZ1000001 always returns stage 1.
  • ZZZZ1000004 always returns stage 4.
  • ZZZZ1000007 always returns stage 7.

A suffix digit greater than 7 returns 400 Bad Request.

Stages of ZZZZ100000

Stage (day)Status
1 (Monday)PLANNED
2 to 5 (Tuesday to Friday)IN_TRANSIT
6 (Saturday)DELIVERED
7 (Sunday)PLANNED, new voyage