Sandbox

Sandbox lets you build the whole integration without a single real courier leaving a restaurant. Validation is identical to production; only the dispatch is simulated.

	Sandbox	Production
Secret prefix	hzl_test_	hzl_live_
Base URL	https://gw-dev.hizliyo.com/api/vendor/v1	https://gw.hizliyo.com/api/vendor/v1
Validation, errors, rate limits	identical	identical
Courier	simulated	real
Webhooks	really sent	really sent
Data retention	7 days	per policy

Sandbox data never appears in reports or invoices.

What is real and what is not

Real: authentication, rate limiting, idempotency, required-field validation, the coordinate check, store and fleet resolution, error codes, webhook delivery and signing. These run through exactly the same code as production.

Simulated: courier assignment, movement and timings.

Where sandbox lies

It cannot test a genuine shortage of couriers, real coverage boundaries, a real fleet suspension, or real-world delays. A green sandbox run does not guarantee a green first night in production — it guarantees your requests are well formed and your webhook handling works.

Test fleets

Three fleets are seeded, each with fixed behaviour:

Fleet	Behaviour	Use it to test
Sandbox Fleet A	Always available	The happy path
Sandbox Fleet B	Always at capacity	Rendering a busy fleet in your store setup UI
Sandbox Fleet C	Suspended	Handling 423 FLEET_SUSPENDED

They appear in availableFleets when you register a sandbox store.

Timeline

By default a sandbox delivery completes in one minute:

Status	Elapsed
Searching	0 s (with the 201)
Assigned	+5 s — courier "Test Kurye"
PickingUp	+15 s
PickedUp	+30 s
Delivering	+40 s
Delivered	+60 s

Each transition sends a real, signed webhook to your registered URL.

Triggering scenarios

Put a magic value anywhere in recipient.name to steer the simulation. There is no separate control endpoint — this keeps the API surface at five endpoints.

Value in recipient.name	Result
TEST_FAIL	Delivery ends in Failed
TEST_CANCEL	Cancelled at +20 s
TEST_SLOW	Realistic pace, roughly 45 minutes
TEST_NO_COURIER	Order rejected with 503 FLEET_UNAVAILABLE
TEST_OUT_OF_COVERAGE	Order rejected with 422 DROPOFF_OUT_OF_COVERAGE

Example:

{
  "recipient": { "name": "TEST_FAIL Merve Yildirim", "phone": "5339876543" }
}

Never send magic values in production

They are ignored there, which means an order named TEST_CANCEL becomes a perfectly real delivery. Strip them at the boundary of your test suite.

Suggested sequence

1. Get a token; confirm you cache it
2. Register a store without a fleet; read availableFleets
3. Attach Sandbox Fleet A; wait for store.activated
4. Send an order; watch six webhooks arrive in a minute
5. Verify a signature and prove a tampered body is rejected
6. Send TEST_NO_COURIER and TEST_OUT_OF_COVERAGE; check your error handling
7. Send TEST_SLOW, then cancel before pickup, then try again after PickedUp
8. Resend one order with the same idempotency key; confirm you get the original response

That sequence is also the launch checklist.