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 number | Response |
|---|---|
ZZZZ0000000 | A complete, healthy shipment from Le Havre to Rotterdam, with its full event history. |
ZZZZ0000001 | A provider error: the shipping line could not be autodetected (AUTO_CANT_DETECT_SEALINE). |
ZZZZ0000002 | A 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 number | Scenario |
|---|---|
ZZZZ100000 | Full nominal lifecycle: PLANNED, then IN_TRANSIT, then DELIVERED, then a reset to a new voyage. |
ZZZZ200000 | A voyage with provider errors injected at some stages, such as SEALINE_HASNT_PROVIDE_INFO and SEALINE_UNDER_MAINTENANCE. |
ZZZZ300000 | A 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.
ZZZZ1000001always returns stage 1.ZZZZ1000004always returns stage 4.ZZZZ1000007always 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 |