Sandbox Mode
Test your integration without shipping anything
Sandbox mode lets you build and test an integration against the real Kvikk API without creating real shipments. Requests are validated and priced exactly like live ones, but no courier is contacted, no pickup is ordered and nothing is billed.
Getting a sandbox API key
- Log in to developer.kvikk.hu.
- Open the Kvikk API menu.
- Under Sandbox API kulcsok, click Új sandbox kulcs.
Sandbox keys start with kvikk_sandbox_. Use them exactly like a live key: same https://api.kvikk.hu/v1 base URL, same X-API-KEY header. You don't need a separate URL or a separate account, and you can create sandbox keys before your account is fully activated, so you can start building right away.
Your account still needs at least one sender address: use its ID as the senderID, like in live mode. You can find it with Account Information.
What's the same and what's different
| Live key | Sandbox key | |
|---|---|---|
| Request validation and error codes | ✓ | ✓ Same rules |
| Shipping prices and COD fees in the response | ✓ | ✓ Same prices |
| Couriers you can use | The ones activated on your account | Every courier Kvikk supports |
| Label | The courier's real label | A sample label with the courier's name, marked as not shippable |
| Courier API call | ✓ | ✗ No courier is contacted |
| Delivery note | The courier's delivery note | A sample delivery note, stamped MINTA – SANDBOX |
Courier pickup (pickupFor) | Ordered from the courier | Never ordered |
| Billing | Appears on your statement | Never billed |
| Tracking | Updated from the courier | You set the status yourself, see below |
| Shipments in app.kvikk.hu | ✓ | ✗ Only on developer.kvikk.hu |
Sandbox and live data are fully separated. A sandbox key only sees sandbox shipments, a live key only sees live ones, even if you use the same tracking number.
The create shipment response has an extra "sandbox": true field, so you can double-check which mode you are in.
Supported endpoints
Sandbox keys work with:
- Create Shipment, Get Shipment, Delete Shipment, Get Shipment Label
GET /v1/shipmentsandGET /v1/tracking/{trackingNumber}- Create Delivery Note
- Delivery Points and Account Information
- Set Sandbox Shipment Status, sandbox keys only
The Returns endpoints don't support sandbox keys yet. Calling them, or any other endpoint that only works with live data, returns:
{
"status": "fail",
"code": "sandbox_not_supported",
"message": "This endpoint is not available with a sandbox API key."
}
Testing error handling
Courier-side errors can be triggered on purpose with these postcodes. Both pass Kvikk's own postcode validation, so the request reaches the (fake) courier step:
postcode | Result |
|---|---|
0000 | 400 with the invalid_postcode code, like a courier rejecting the address |
0001 | 400 with the api_error code, like the courier's API being unavailable |
Every other validation error (missing fields, wrong weight, invalid delivery point and so on) works exactly like in live mode.
Testing webhooks and tracking
Sandbox shipments have no real courier tracking, so their status only changes when you change it. There are two ways to do that:
- By hand: open the Sandbox csomagok menu on developer.kvikk.hu and pick a new status for the shipment. The same page lets you download the label, view the full API response and delete sandbox shipments.
- From your tests: call Set Sandbox Shipment Status with your sandbox key.
Either way, if the new status has a webhook event (sent, ready_for_pickup, delivered, returned), your active webhooks subscribed to it are called right away. The payload is the same as for a live shipment, with an extra field:
{
"trackingNumber": "G931319195917",
"tracking": { ... },
...
"sandbox": true
}
Sandbox and live events go to the same webhook URLs, so check the sandbox field if your endpoint should handle them differently. Unlike live shipments, a sandbox webhook fires every time you set the status, not just the first time, so you can repeat a test as often as you like.
Going live
Once your integration works, create a live key in the same menu and swap it in. Nothing else changes: the URLs, the request and response formats and the webhook payloads are the same.