Sandbox

De sandbox draait dezelfde code als productie: dezelfde validatie, dezelfde state machine, dezelfde hash-keten, dezelfde gebeurtenissen en webhooks. Wat verschilt: er gaat niets naar echte providers, er wordt niets gefactureerd, en je mag simuleren.

Basis

Basis-URL	https://api.eftisandbox.app
Key-prefix	sk_test_
Console	console.eftisandbox.app
OpenAPI	https://api.eftisandbox.app/openapi.json

Test- en live-data staan volledig los. Een sk_test_-key ziet nooit live-zendingen, en omgekeerd; een id uit de ene modus bestaat niet in de andere. Een live-route aanroepen met een organisatie die daar nog niet voor is vrijgegeven, geeft live_not_enabled. Andersom geldt hetzelfde: de simulatieroutes bestaan alleen in test-mode en antwoorden met een sk_live_-key met test_mode_only.

Simuleren

In de echte wereld tekent een chauffeur op zijn telefoon en een geadresseerde aan de laadklep. In de sandbox speelt POST /v1/test/shipments/{id}/simulate die rollen voor je, zodat je je integratie kunt testen zonder iemand een link te sturen.

Actie	Body	Wat er gebeurt
sign	{ "action": "sign", "role": "carrier" }	Legt een handtekening vast voor die rol, met methode api, ondertekenaar “Sandbox <rol>” en evidence.simulated: true
deliver	{ "action": "deliver" }	Levert af, inclusief de handtekeningen die daarvoor nog nodig waren
remark	{ "action": "remark", "type": "damage" }	Voegt een voorbehoud toe
auto	{ "action": "auto" }	Loopt de hele levenscyclus af tot delivered

auto is de interessantste: hij start een achtergrondproces dat de zending uitgeeft, na een paar minuten de vervoerder laat tekenen, en daarna de geadresseerde laat tekenen met een voorbehoud — elke stap via dezelfde services als een echte zending. Je krijgt dus dezelfde gebeurtenissen, dezelfde PDF’s en dezelfde webhooks als live. GET /v1/test/shipments/{id}/simulation toont de voortgang.

Wil je dat automatisch bij elke nieuwe zending, zet dan metadata.sandbox_auto: true bij het aanmaken; auto start dan vanzelf na uitgifte.

Nog niet uitgerold

De simulatieroutes komen met M1-17 en zijn er nog niet: POST /v1/test/shipments/{id}/simulate antwoordt vandaag met 404 not_found. Het contract hierboven is wat er komt, zodat je je testcode er alvast op kunt inrichten.

Tot die tijd loop je de levenscyclus zelf na met de gewone routes — dat werkt volledig, en het is toch dichter bij wat je integratie in productie doet:

1. POST /v1/shipments en POST /v1/shipments/{id}/issue
2. POST /v1/shipments/{id}/signatures met rol carrier
3. POST /v1/shipments/{id}/signatures met rol consignee, eventueel met een voorbehoud via POST /v1/shipments/{id}/remarks

Voorbeeldzendingen

Drie corridors die elk iets anders laten zien. Ze zijn zo gekozen dat het regelregister er verschillend op reageert; zie Landvereisten.

Het eenvoudige geval — NL naar DE

Beide landen zijn partij bij het e-CMR-Protocol, dus er komt geen papier aan te pas en er zijn geen blokkerende bevindingen.

curl -X POST https://api.eftisandbox.app/v1/shipments \
  -H "Authorization: Bearer $FREIGHTAPI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "DEMO-NL-DE",
    "consignor": { "name": "Van Dijk Logistiek", "address": { "line1": "Havenweg 12", "postal_code": "3089 JH", "city": "Rotterdam", "country": "NL" } },
    "carrier":   { "name": "Sandbox Transport",  "address": { "line1": "Industrieweg 4", "postal_code": "5222 AL", "city": "s-Hertogenbosch", "country": "NL" } },
    "consignee": { "name": "Muller Handel GmbH", "address": { "line1": "Hafenstrasse 7", "postal_code": "47119", "city": "Duisburg", "country": "DE" } },
    "pickup":   { "address": { "line1": "Havenweg 12", "postal_code": "3089 JH", "city": "Rotterdam", "country": "NL" } },
    "delivery": { "address": { "line1": "Hafenstrasse 7", "postal_code": "47119", "city": "Duisburg", "country": "DE" } },
    "goods": [{ "description": "Palletized machine parts", "packages": 8, "package_type": "pallet", "gross_weight_kg": 1840 }]
  }'

Het Belgische geval — NL naar BE

België ratificeerde het e-CMR-Protocol nooit. Verander country in de geadresseerde en de afleveradres naar BE en je krijgt er een bevinding bij: de Benelux-pilot vraagt om een door de NIWO erkende provider. Laat provider weg en de routing kiest er zelf een.

Het ADR-geval — gevaarlijke goederen

Zet adr: true op een goederenregel en POST /v1/shipments/validate vraagt om het UN-nummer, de juiste vervoersnaam, de gevarenklasse en de verpakkingsgroep. Handig om je foutafhandeling te testen: je krijgt een 422 met een errors-array per veld.

curl -X POST https://api.eftisandbox.app/v1/shipments/validate \
  -H "Authorization: Bearer $FREIGHTAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goods": [{ "description": "Paint", "packages": 2, "gross_weight_kg": 40, "adr": true }] }'

Conformance-checklist

Voor je live mag, willen we zien dat je integratie de dingen aankan die in productie misgaan — niet alleen de gelukkige route. De console houdt daarom per organisatie bij welke scenario’s je in test-mode hebt aangetoond:

Scenario	Wat je aantoont
create_shipment	Een zending aanmaken
validate_with_error_handled	Een 422 ontvangen en daarna een geldige create doen
issue	Uitgeven
signature_via_link	Een handtekening via een tekenlink
delivery_with_pod	Afleveren met een ePOD
webhook_endpoint_configured	Een endpoint ingesteld
webhook_echo_verified	Een ping beantwoord met een kloppende freightapi-echo-header
webhook_delivery_succeeded	Een echte levering met een 2xx
idempotency_key_used	Idempotency-Key gebruikt op een POST
integrity_checked	De hash-keten opgevraagd
pdf_downloaded	Een PDF gedownload
auto_sandbox_run	Een zending via auto laten doorlopen

Zodra alle twaalf scenario’s zijn afgevinkt, is je organisatie ready_for_live en kun je in de console live aanvragen. Vrijgeven blijft een menselijke handeling; er gaat niets automatisch aan.

Waar je de checklist ziet

De pagina staat op console.eftisandbox.app/conformance, met de voortgang, per scenario wat je ermee aantoont, en de knop om live aan te vragen zodra alles staat. Je hoeft niets af te vinken: de evaluator leest je bestaande gebeurtenissen, request-logs en webhook-leveringen terug, elk kwartier en met „Nu controleren” ook meteen. Een scenario dat één keer geslaagd is, blijft geslaagd — ook nadat sandbox-data is opgeruimd.

Wat je in de sandbox níét test

• Echte providers. Externe eCMR-platformen worden nooit aangeroepen; de mock-provider doet alsof. Een echte koppeling met een provider test je pas in productie.
• Facturatie en limieten. De ratelimits liggen in test lager (600 per minuut tegen 1.200 live), dus een load-test in de sandbox zegt niets over live.
• Bewaartermijnen. Sandbox-data kan worden opgeruimd. Bewaar niets wat je nodig hebt.