Sandbox testing

Every company has a sandbox copy alongside its live data. A key created with the sandbox environment under Settings › API Keys starts with nvl_test_ and acts on that copy: routes are created, matched, held and canceled exactly as they would be live, but nothing is ever sent to a driver.

What is different with a sandbox key

• Same base URL, same endpoints, same request and response shapes. Only the key changes.
• GET /v1/me reports "environment": "sandbox", and every route the key creates carries "environment": "sandbox".
• Nothing reaches a driver. A sandbox route never messages anyone, whatever its status.
• Sandbox routes live in the sandbox copy, apart from the routes a live key sees.

A suggested workflow

1. Create a sandbox key with the same scopes you plan to give the live key. Confirm it with GET /v1/me and check that environment is sandbox.
2. Reconcile vehicles and drivers. GET /v1/vehicles and GET /v1/drivers show what the sandbox copy knows. Compare against the unit numbers and names your TMS will send.
3. Push a real load’s data with POST /v1/routes. Check you get 201 and a draft route, and that scheduledStart round-trips into UTC the way you expect.
4. Push it again unchanged and changed. Both should return 200 and the second should reflect the change.
5. Push a load with an unknown unit number and confirm you handle the 202 / pending_mapping response, including surfacing pending.detail.
6. Send an invalid body (one stop, a missing latitude) and check that your integration logs the errors array from the 400.
7. Cancel a route with DELETE /v1/routes/{id} and confirm a re-push creates a fresh route.
8. Swap the key for the nvl_live_ one. No other change is needed.

What the sandbox cannot show you

Fuel plans are built when the truck arrives at the route’s first stop. No truck arrives anywhere in the sandbox, so do not expect a sandbox route to progress past draft on its own, or its fuelPlan to be anything but null. Test the plan-reading side of your integration against the response shapes in the API reference and the Quickstart, then confirm it on the first live route.

Keeping the two apart

• Never put a live key in a test configuration. The prefix (nvl_live_ vs nvl_test_) is visible in logs and in GET /v1/me precisely so that this is easy to check.
• If your integration stores route ids, store the environment alongside them; an id from the sandbox means nothing to a live key.