Publieke API
Editie 2026 · boekingen, zendingen en voorraad koppelen aan je eigen systeem
Inhoud
Wat is de publieke API
4
Toegang en API sleutels
7
Token ophalen
11
Endpoints en statussen
14
Boekingen aanmaken en bijwerken
18
Zendingen en voorraad
22
Fouten en opnieuw proberen
26
Testen in Swagger en veelgestelde vragen
30
1
Wat is depublieke API
1. Wat is de publieke API
API handleiding4
!
De publieke API is live vanaf eind november 2026. Tot die tijd kun je met deze handleiding je koppeling alvast voorbereiden. De adressen, velden en werking in deze handleiding zijn de definitieve versie 1. Je hoeft niets aan te vragen: vanaf eind november 2026 staat de API automatisch in je eigen account onder het kopje Automation, waar je zelf je sleutels aanmaakt.
Je eigen systeem praat rechtstreeks met Import4You
Met de publieke API doet je eigen software rechtstreeks verzoeken aan het Import4You platform. Je kunt boekingen en zendingen aanmaken en je kunt boekingen, zendingen, voorraad en statustijdlijnen van je eigen bedrijf uitlezen. Je ziet alleen gegevens van je eigen bedrijf.
Boekingen
Aanmaken, bijwerken, volgen
Nieuwe import uit China boeken, handelsfactuur meesturen, producten wijzigen en de statustijdlijn uitlezen.
Voorraad
Uitlezen
Wat er van jou in ons magazijn in Hapert staat, per product en per pallet, met de verzendhistorie.
Zendingen
Aanmaken, volgen
Een zending uit je voorraad naar een eigen adres, een LVB locatie, een fulfilment center of ons magazijn, met status en leverdatum.
Dit heb je nodig
- ✓ Een bedrijfsaccount in het Import4You platform
- ✓ Vanaf eind november 2026 staat de API automatisch aan in je account, onder het kopje Automation
- ✓ Een API sleutel (client_id en client_secret) uit het platform
- ✓ Software die HTTPS verzoeken kan doen en JSON kan lezen
Goed om te weten
- i Versie 1, REST met JSON. Verzoeken met bestanden gaan als multipart.
- i Een testsleutel leest echte data maar slaat nooit iets op.
- i Statuswijzigingen van boekingen kun je ook als push ontvangen, zie de webhook handleiding.
- i Een Engelstalige technische gids en Swagger staan op de API server zelf.
1. Wat is de publieke API
API handleiding5
De adressen
Alle adressen staan op https://api.import4you.nl. De paden in deze handleiding zijn relatief aan de basis /public-api/v1.
Waarvoor
Adres
Swagger (interactieve documentatie)
https://api.import4you.nl/public-api/documentation
OpenAPI JSON (importeren in een REST client)
https://api.import4you.nl/public-api/openapi
Basis van alle endpoints
https://api.import4you.nl/public-api/v1
Token ophalen
POST https://api.import4you.nl/public-api/v1/oauth/token
Zo verloopt een koppeling
1
Sleutel maken
In het platform, met de rechten die je nodig hebt
2
Token ophalen
client_id en client_secret inwisselen, 15 minuten geldig
3
Verzoek doen
Met de token als Bearer in de Authorization header
4
Antwoord verwerken
JSON met data, paginering en een X-Request-ID
Openbare documentatie, geen openbare data
Iedereen kan Swagger openen, maar je ziet pas gegevens na het inloggen met een sleutel van je eigen bedrijf. Je ziet nooit gegevens van een ander bedrijf.
Tijden en datums
Velden die eindigen op _at zijn tijdstippen in UTC, bijvoorbeeld 2026-06-30T09:22:22Z. Velden die eindigen op _date zijn kalenderdatums, bijvoorbeeld 2026-07-02. Verschuif die niet naar een andere tijdzone.
2
Toegang enAPI sleutels
2. Toegang en API sleutels
API handleiding7
Toegang aanvragen en een sleutel maken
- Open Automation in je account. Vanaf eind november 2026 staat de publieke API automatisch aan voor elk bedrijfsaccount. Je hoeft niets aan te vragen. Log in op het platform en ga naar Instellingen → Automation.
- Maak een testsleutel. Ga naar Public API Keys. Kies een naam, een vervaldatum en de rechten (scopes) die je nodig hebt. Begin altijd met een testsleutel.
- Bewaar client_id en client_secret meteen. Het secret zie je maar één keer. Zet het in je wachtwoordkluis of secret store, nooit in een ticket, mail of schermafbeelding.
- Maak een livesleutel als je klaar bent. Pas als je koppeling werkt met de testsleutel, maak je een livesleutel met dezelfde rechten voor echte boekingen en zendingen.
testSleutel begint met i4y_test_
Leest de echte gegevens van je bedrijf. Alles wat schrijft (boeking aanmaken, bijwerken, zending aanmaken) draait als dry run: het verzoek wordt volledig gecontroleerd, maar er wordt niets opgeslagen, geen bestand bewaard en geen voorraad gereserveerd. In het antwoord staat dry_run: true.
liveSleutel begint met i4y_live_
Voert alles echt uit. Een boeking die je aanmaakt, komt bij ons in behandeling. Een parameter in je verzoek kan dit gedrag niet veranderen: het type sleutel bepaalt of het echt is.
Een sleutel die verloopt, wordt ingetrokken of een nieuw secret krijgt, maakt alle tokens van die sleutel direct ongeldig.
2. Toegang en API sleutels
API handleiding8
Rechten per sleutel
Bij het maken van een sleutel kies je welke rechten hij krijgt. Lezen en schrijven zijn losse rechten: een schrijfrecht geeft niet automatisch leesrecht. Verander je de rechten van een sleutel, dan gelden die pas voor nieuwe tokens.
Recht
Wat je ermee mag
Endpoints
bookings:read
Boekingen lezen
GET /bookings, /bookings/{uuid}, /bookings/{uuid}/events
bookings:write
Boekingen aanmaken en bijwerken
POST /bookings, POST /bookings/{uuid}/update
shipments:read
Zendingen lezen
GET /shipments, /shipments/{id}, /shipments/{id}/events
shipments:write
Zendingen aanmaken
POST /shipments
stock:read
Voorraad lezen
GET /stock, /stock/{id}
Voorbeeld: zending vanuit voorraad
Je wilt voorraad bekijken, daaruit een zending maken en die zending daarna volgen. Dan heeft je sleutel stock:read, shipments:write en shipments:read nodig.
Voorbeeld: alleen lezen
Wil je alleen boekingen opvragen en hun tijdlijn volgen, dan is bookings:read genoeg. Een leessleutel kan niets aanmaken of wijzigen.
2. Toegang en API sleutels
API handleiding9
IP beperking: welk adres vul je in
Per sleutel kun je een lijst met IP adressen opgeven die de sleutel mogen gebruiken. Een lege lijst betekent: elk adres mag, inloggen met de sleutel blijft natuurlijk verplicht. Vul je wel adressen in, gebruik dan het publieke adres van het systeem dat de verzoeken doet.
Je test vanaf je laptop
Gebruik het publieke IP van je internetverbinding. Bij het maken van een sleutel vult het platform dat adres al voor je in; je kunt het aanpassen of weghalen.
Je koppeling draait op een server
Vraag je hostingpartij of beheerder naar het uitgaande publieke IP van de server, inclusief een eventuele NAT gateway. Het IP van je laptop helpt hier niet.
Je gebruikt een externe koppelingsdienst
Vraag de dienst naar zijn uitgaande adressen en voeg elk adres apart toe als de verzoeken van meer dan één adres kunnen komen.
Spelregels
- ✓ Losse adressen, gescheiden door komma's, zonder poort of haakjes
- ✓ IPv4 en IPv6 zijn allebei mogelijk; gebruikt je systeem beide, voeg beide toe
- ✕ Reeksen (CIDR, zoals /24) worden niet ondersteund
- ✕ Een intern adres zoals 192.168.1.10 werkt niet, dat ziet Import4You nooit
Foutmelding client.ip_not_allowed
Controleer het uitgaande publieke IP van het systeem dat het verzoek doet, inclusief VPN, proxy of IPv6. Pas de lijst van de sleutel aan in het platform, sla op en probeer opnieuw. Let op: VPN, mobiel internet of een andere wifi verandert je publieke IP.
3
Tokenophalen
3. Token ophalen
API handleiding11
Wissel je sleutel in voor een token
Je sleutel gebruik je nooit rechtstreeks bij een endpoint. Je wisselt hem in voor een Bearer token (OAuth 2.0 client credentials). Die token stuur je mee in de Authorization header van elk verzoek.
Verzoek
POST /public-api/v1/oauth/token HTTP/1.1 Host: api.import4you.nl Accept: application/json Content-Type: application/x-www-form-urlencoded X-Request-ID: koppeling-auth-001 grant_type=client_credentials &client_id=<CLIENT_ID> &client_secret=<CLIENT_SECRET>
De drie velden gaan als formuliervelden (x-www-form-urlencoded) en moeten URL gecodeerd zijn. Een REST client doet dat voor je als je de velden los invult. HTTP Basic authenticatie met client_id en client_secret werkt ook.
Antwoord
{ "token_type": "Bearer", "expires_in": 900, "access_token": "<ACCESS_TOKEN>" }
Daarna bij elk verzoek
GET /public-api/v1/bookings?per_page=20 HTTP/1.1 Host: api.import4you.nl Authorization: Bearer <ACCESS_TOKEN> Accept: application/json
15min
Geldig
Een token verloopt na 900 seconden. Er is geen refresh token: vraag gewoon een nieuwe aan.
1sleutel
Rechten staan vast
De token krijgt de rechten die op de sleutel staan. Een scope in je verzoek wordt genegeerd.
0×
Portaal login
Een inlogtoken van het platform werkt niet op de API. Alleen een API sleutel.
3. Token ophalen
API handleiding12
Zo houd je het netjes
Hergebruik de token
Vraag niet voor elk verzoek een nieuwe token. Bewaar hem in het geheugen en vraag een nieuwe zodra hij bijna verloopt of je een 401 krijgt.
Stuur een X-Request-ID mee
Een eigen kenmerk per verzoek, bijvoorbeeld boeking-2026-11-10-0001. Je krijgt hem terug in het antwoord. Noem hem bij vragen aan support, dan vinden wij je verzoek direct terug.
Bij een 401
Controleer of de token verlopen is, of de sleutel nog geldig is en of API toegang voor je bedrijf aanstaat. Een verkeerd of oud secret geeft bij het token endpoint invalid_client.
Voorbeeld in Node.js
const basis = "https://api.import4you.nl/public-api/v1"; let token = null, sc-camel-verloopt-op = 0; async function haalToken() { const body = new URLSearchParams({ grant_type: "client_credentials", client_id: process.env.I4Y_CLIENT_ID, client_secret: process.env.I4Y_CLIENT_SECRET, }); const res = await fetch(basis + "/oauth/token", { method: "POST", headers: { Accept: "application/json" }, body, }); if (!res.ok) throw new Error("token " + res.status); const data = await res.json(); token = data.access_token; sc-camel-verloopt-op = Date.now() + (data.expires_in - 60) * 1000; } async function api(pad, opties = {}) { if (!token || Date.now() > verlooptOp) await haalToken(); return fetch(basis + pad, { ...opties, headers: { Authorization: "Bearer " + token, Accept: "application/json", ...(opties.headers || {}) }, }); }
4
Endpoints enstatussen
4. Endpoints en statussen
API handleiding14
Alle endpoints van versie 1
Relatief aan https://api.import4you.nl/public-api/v1. GET leest, POST maakt aan of wijzigt.
Endpoint
Recht
Succes
Wat het doet
POST /oauth/token
geen
200
Token ophalen met client_id en client_secret
GET /bookings
bookings:read
200
Lijst van je boekingen, met paginering en filters op status en aanmaakdatum
POST /bookings
bookings:write
201
Boeking aanmaken (multipart met handelsfactuur)
GET /bookings/{uuid}
bookings:read
200
Eén boeking met producten, datums, levering en facturen
POST /bookings/{uuid}/update
bookings:write
200
Boeking bijwerken: factuurgegevens, documenten en eventueel producten
GET /bookings/{uuid}/events
bookings:read
200
Statustijdlijn van een boeking, met cursor
GET /shipments
shipments:read
200
Lijst van zendingen uit je voorraad
POST /shipments
shipments:write
201
Zending aanmaken uit voorraad (JSON, of multipart met bestanden)
GET /shipments/{id}
shipments:read
200
Eén zending
GET /shipments/{id}/events
shipments:read
200
Statustijdlijn van een zending
GET /stock
stock:read
200
Je huidige voorraad in ons magazijn, met zoekfilters
GET /stock/{id}
stock:read
200
Eén voorraadregel met verzendhistorie
4. Endpoints en statussen
API handleiding15
Lijsten, paginering en tijdlijnen
Lijsten
Een lijst geeft data en meta.pagination (page, per_page, total, total_pages). Standaard: pagina 1, 50 per pagina (maximaal 100), nieuwste eerst.
Filters
- ✓ Boekingen: filter[status], filter[created_from], filter[created_to]
- ✓ Zendingen: filter[status], filter[created_from], filter[created_to]
- ✓ Voorraad: filter[search], filter[personal_ref], filter[booking_uuid], filter[ean_code] (bevat, letterlijk)
Voorbeeld lijst
GET /bookings?page=1&per_page=20 &filter[status]=in_transit &filter[created_from]=2026-11-01T00:00:00Z { "data": [ { "id": "SI4Y-000123", "status": "in_transit", ... } ], "meta": { "pagination": { "page": 1, "per_page": 20, "total": 3, "total_pages": 1 } } }
Voorbeeld tijdlijn
GET /bookings/SI4Y-000123/events?per_page=50 { "data": [ { "event_code": "created", "status": null, "occurred_at": "2026-07-01T08:00:00Z", "recorded_at": "2026-07-01T08:00:02Z", "source": "client_api" }, { "event_code": "status_changed", "status": "in_transit", "occurred_at": "2026-07-25T08:12:00Z", "recorded_at": "2026-07-25T08:12:03Z", "source": "carrier" } ], "meta": { "next_cursor": "..." } }
Welk ID gebruik je waar
- ✓ Boeking: het publieke nummer zoals SI4Y-000123. Producten en subproducten hebben eigen UUID's.
- ✓ Voorraad: UUID's. Die gebruik je als stock_item_id en stock_sub_id bij een zending.
- ✓ Zending: een UUID. Een WI4Y- nummer werkt hier niet.
Tijdlijnen lees je met een cursor
Geef bij de volgende aanvraag after=<meta.next_cursor> mee. Bewaar de laatste cursor die niet null was en vraag daarmee periodiek verder; null betekent dat er nu niets nieuws is. Gebeurtenissen staan in de volgorde van vastleggen, dus een latere regel kan een eerdere occurred_at hebben. Filteren kan met event_code[]=status_changed.
4. Endpoints en statussen
API handleiding16
Statussen
De API gebruikt vaste Engelse statuscodes. Die blijven in versie 1 gelijk, ook als de naam in het platform verandert.
Boeking
Status
Betekenis
Status
Betekenis
registered
Boeking ontvangen
out_for_delivery
Onderweg naar je adres
collecting
Wordt opgehaald of aangeleverd in China
delivered
Afgeleverd
goods_received
Goederen binnen bij onze agent
stored_in_warehouse
Opgeslagen in ons magazijn
ready_to_ship
Klaar voor vertrek
in_storage
In opslag
in_transit
Onderweg naar Nederland
payment
Wacht op betaling
arrived_at_destination
Aangekomen in de haven, hub of luchthaven
completed
Afgerond
customs_clearance
Bij de douane
declined
Afgewezen
Zending uit voorraad
registered (aangemaakt) → prepared (klaargezet in het magazijn) → in_delivery (onderweg) → delivered (afgeleverd).
Voorraad
available (beschikbaar om te verzenden) of unavailable. Een voorraadregel toont ook boxes_count, pallets, dozen per pallet en de volledige verzendhistorie, nieuwste eerst.
De webhook stuurt de statusnaam zoals het platform die toont (bijvoorbeeld "Collection"), niet deze API code. Wil je de API code, haal dan na een webhook de boeking op via GET /bookings/{uuid}.
5
Boekingenaanmaken
5. Boekingen aanmaken en bijwerken
API handleiding18
Een boeking aanmaken
POST /bookings met Content-Type: multipart/form-data, want de handelsfactuur gaat als bestand mee. Geneste velden schrijf je met haakjes, zoals products[0][description]. Laat je HTTP client de multipart boundary zelf zetten.
Veld
Waarde
transport_type *
sea, rail of air
incoterm *
Bijvoorbeeld FCA, EXW of FOB
personal_ref *
Je eigen kenmerk, komt terug in elk antwoord
invoice_number *
Nummer van de handelsfactuur
warehouse_ref
Naam van onze agent in China, bijvoorbeeld Shenzhen. Of custom_warehouse met een vrije naam
supplier[...] *
name, email, phone (7 tot 30 cijfers, zonder +), address[street], [house_number], [place], [postcode]
delivery[...] *
type (bijvoorbeeld lvb of custom_address), address[...], location_ref, dhl, dhl_insurance, receiver_name
documents[commercial_invoice] *
[reference] (een UUID die je zelf kiest) en [file] (pdf, maximaal 15 MiB). Optioneel: packing_list, msds_file
products[n][...] *
description, hs_code, total_value, quantity_boxes, gross_weight, cbm; optioneel ean_code, items_per_boxes, box_size, subs
Overig
is_dangerous, note, invoice_value, invoice_date, container_type, is_fiscal_representation (alleen bij België)
* verplicht. Bedragen, gewicht en CBM stuur je als tekst met punt, zoals "500.00" en "1.5", zodat er niets afrondt.
Verplichte headers
Authorization: Bearer <ACCESS_TOKEN> Idempotency-Key: boeking-2026-11-10-0001 X-Request-ID: verzoek-2026-11-10-0001
Formuliervelden, ingekort
transport_type=sea incoterm=FCA personal_ref=REF-4471 invoice_number=INV-2026-118 supplier[name]=Supplier Ltd supplier[email]=sales@supplier.cn supplier[phone]=8675512345678 supplier[address][street]=Supplier St supplier[address][house_number]=10 supplier[address][place]=Shenzhen supplier[address][postcode]=518000 delivery[type]=custom_address delivery[address][street]=Dock Road delivery[address][house_number]=5 delivery[address][postcode]=3011AA delivery[address][place]=Rotterdam delivery[address][country]=NL documents[commercial_invoice][reference]= 11111111-1111-4111-8111-111111111111 documents[commercial_invoice][file]=@factuur.pdf products[0][description]=Widget products[0][hs_code]=8501100000 products[0][total_value]=500.00 products[0][quantity_boxes]=10 products[0][gross_weight]=25.5 products[0][cbm]=1.5
5. Boekingen aanmaken en bijwerken
API handleiding19
Het antwoord
Bij succes krijg je 201 met de boeking zoals wij hem hebben opgeslagen: het publieke nummer, de status, alle producten met hun UUID's, de datums en later ook de facturen.
{ "data": { "id": "SI4Y-000123", "status": "registered", "personal_ref": "REF-4471", "transport_type": "sea", "incoterm": "FCA", "is_paid": false, "is_open": true, "dates": { "created_at": "2026-11-10T09:22:22Z", "estimated_departure_date": null, "estimated_arrival_date": null, "planned_delivery_date": null }, "products": [ { "id": "6f5e8f7a-3d4c-4b2a-9e1f-0a6b7c8d9e10", "description": "Widget", "hs_code": "8501100000", "total_value": "500.00", "quantity_boxes": 10, "gross_weight": "25.50000", "cbm": "1.50000", "subs": [] } ], "invoices": [] } }
Met een testsleutel: dry run
Je krijgt ook 201, maar met "dry_run": true en ID's die beginnen met dryrun_. Die ID's zijn stabiel voor dezelfde inhoud, maar je kunt ze nooit gebruiken als echte verwijzing. Er wordt niets opgeslagen en geen bestand bewaard.
Datums vullen zich later
Vertrek, aankomst en leverdatum zijn bij het aanmaken nog leeg. Ze komen in dates zodra wij ze weten. Volg ze via GET /bookings/{uuid}, de tijdlijn of de webhook.
Facturen in het antwoord
Zodra wij factureren, staat de factuur in invoices: type (booking of fcl_additional_costs), bedrag, vervaldatum, status (pending_payment, paid, draft) en een downloadlink naar de pdf. Zie ook de handleiding Betalingen en facturen.
Levering in België
Zet is_fiscal_representation=true als je onze fiscale vertegenwoordiging wilt. Het veld doet alleen iets als het leverland België is.
5. Boekingen aanmaken en bijwerken
API handleiding20
Een boeking bijwerken
POST /bookings/{uuid}/update, ook multipart en ook met een Idempotency-Key. Je kunt factuurgegevens, documenten en de producten aanpassen. Let goed op de drie regels hieronder, ze bepalen wat er met de bestaande gegevens gebeurt.
1. Handelsfactuur altijd opnieuw
Stuur documents[commercial_invoice] bij elke update opnieuw mee. Een documenttype dat je niet meestuurt (bijvoorbeeld de paklijst) wordt verwijderd.
2. Producten vervangen de hele lijst
Laat je products weg, dan blijven de producten zoals ze zijn. Stuur je products mee, ook als lege lijst, dan vervangt dat de volledige productlijst: producten die ontbreken, worden verwijderd.
3. Eerst testen
Doe dezelfde update eerst met je testsleutel. Je krijgt dan 200 met de huidige boeking terug zonder dat er iets verandert, maar wel met alle controles op je verzoek.
Voorbeeld: alleen factuurnummer en factuur vervangen
POST /public-api/v1/bookings/SI4Y-000123/update Authorization: Bearer <ACCESS_TOKEN> Idempotency-Key: update-SI4Y-000123-02 Content-Type: multipart/form-data invoice_number=INV-2026-118B documents[commercial_invoice][reference]= 22222222-2222-4222-8222-222222222222 documents[commercial_invoice][file]=@factuur-v2.pdf
Geen products meegestuurd, dus de producten blijven staan.
Antwoorden
- 200 Bijgewerkt, je krijgt de volledige boeking terug
- 404 Geen boeking met dit nummer bij jouw bedrijf
- 409 Idempotency-Key al gebruikt met andere inhoud, of de vorige poging loopt nog
- 422 Validatie mislukt, onbekende verwijzing, of de boeking kan in deze status niet meer gewijzigd worden
Leveradres
Bij delivery[type]=custom_address telt alleen delivery[address]. Een meegestuurde location_ref wordt dan genegeerd, ook bij de controle. Het adres zelf moet wel compleet en geldig zijn.
6
Zendingenen voorraad
6. Zendingen en voorraad
API handleiding22
Voorraad uitlezen
GET /stock geeft alles wat van jou in ons magazijn in Hapert staat en beschikbaar is: per product, met subproducten, pallets en de verzendhistorie. De ID's uit dit antwoord heb je nodig om een zending te maken.
GET /public-api/v1/stock?filter[search]=Widget&per_page=50 { "data": [ { "id": "6f5e8f7a-3d4c-4b2a-9e1f-0a6b7c8d9e10", "status": "available", "booking_uuid": "SI4Y-000123", "personal_ref": "REF-4471", "received_date": "2026-07-01", "boxes_count": 8, "start_boxes": 10, "pallets": 2, "boxes_per_pallet": 4, "items_per_boxes": 10, "box_size": { "length": 40, "width": 20, "height": 30 }, "sub_products": [ { "id": "07a76692-3f9a-4f01-8e6f-b24c56e713af", "description": "Widget A", "ean_code": "12345678", "warehouse_boxes": 8 } ], "shipments": [ { "id": "11c9e90a-7b44-4e89-9b8d-2d72b7993a41", "boxes_count": 2, "created_at": "2026-07-10T09:00:00Z" } ] } ], "meta": { "pagination": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1 } } }
Wat je ziet
- ✓ boxes_count: dozen die er nu staan, start_boxes: dozen bij binnenkomst
- ✓ pallets en boxes_per_pallet: hoe het staat opgeslagen
- ✓ sub_products: varianten binnen een product, elk met eigen ID en aantal
- ✓ shipments: alles wat al uit deze voorraad is verzonden, nieuwste eerst
Zoeken
Filters zoeken op "bevat", letterlijk: filter[search] (omschrijving), filter[personal_ref], filter[booking_uuid] en filter[ean_code]. Meerdere filters samen betekent "en".
Niet zichtbaar
Voorraad die nog niet is geaccepteerd, op nul staat of geblokkeerd is, staat niet in de lijst. Een onbekend of andermans ID geeft altijd dezelfde 404.
6. Zendingen en voorraad
API handleiding23
Een zending aanmaken uit voorraad
POST /shipments met JSON, of multipart als je bestanden meestuurt (zoals een LVB leverlijst of paklijst). Ook hier is een Idempotency-Key verplicht.
POST /public-api/v1/shipments Authorization: Bearer <ACCESS_TOKEN> Idempotency-Key: zending-2026-11-10-0007 Content-Type: application/json { "personal_ref": "REF-88213", "delivery": { "type": "custom_address", "planned_delivery_date": "2026-11-14", "address": { "street": "Dock Road", "house_number": "5", "postcode": "3011AA", "place": "Rotterdam", "country": "NL" }, "receiver_name": "Jane Doe", "is_need_call": true, "comment": "Eerst bellen" }, "products": [ { "stock_item_id": "6f5e8f7a-3d4c-4b2a-9e1f-0a6b7c8d9e10", "boxes_count": 0, "subs": [ { "stock_sub_id": "07a76692-3f9a-4f01-8e6f-b24c56e713af", "boxes": 2 } ] } ] }
Veld
Waarde
delivery.type *
custom_address (eigen adres), lvb, fulfillment_center of i4y_warehouse
delivery.planned_delivery_date *
Gewenste leverdatum, jjjj-mm-dd
delivery.location_ref
Verplicht bij lvb en fulfillment_center: het ID van een locatie uit je platform. Bij een eigen adres wordt het genegeerd
delivery.address
street, house_number, postcode, place, country, optioneel addition, truck_size, warehouse_name
products[].stock_item_id *
Het id uit /stock, uniek binnen het verzoek
products[].boxes_count *
Aantal dozen. Met subs: 0 (dan is het de som van de subs) of precies die som
products[].subs[]
stock_sub_id uit sub_products[].id plus boxes
document_references[]
reference (UUID) en file, bijvoorbeeld een LVB leverlijst, maximaal 15 MiB per bestand
6. Zendingen en voorraad
API handleiding24
Een zending volgen
GET /shipments/{id} geeft de actuele stand, GET /shipments/{id}/events de tijdlijn met dezelfde cursor als bij boekingen.
GET /public-api/v1/shipments/11c9e90a-7b44-4e89-9b8d-2d72b7993a41 { "data": { "id": "11c9e90a-7b44-4e89-9b8d-2d72b7993a41", "status": "in_delivery", "personal_ref": "REF-88213", "created_at": "2026-11-10T09:00:00Z", "status_updated_at": "2026-11-13T07:30:00Z", "prepare_status_updated_at": "2026-11-12T15:10:00Z", "delivered_at": null, "is_stockitup": false, "delivery": { ... }, "products": [ { "id": "6f5e8f7a-3d4c-4b2a-9e1f-0a6b7c8d9e10", "description": "Widget", "shipped_boxes": 2, "subs": [ { "id": "07a76692-3f9a-4f01-8e6f-b24c56e713af", "description": "Widget A", "shipped_boxes": 2 } ] } ] } }
1
registered
Zending aangemaakt
2
prepared
Klaargezet in Hapert
3
in_delivery
Onderweg
4
delivered
Afgeleverd
Tijdlijn uitlezen
Vraag /shipments/{id}/events?after=<laatste cursor> op om nieuwe gebeurtenissen te krijgen. Elke statuswijziging staat er precies één keer in. Voor zendingen is er geen webhook, dus dit is de enige manier om de status te volgen.
Voorraad na een zending
Na een echte zending toont /stock het lagere boxes_count en een nieuwe regel in shipments voor die voorraad.
Het antwoord bij aanmaken
201 met de zending: een UUID als id, status registered, de leverafspraak en de producten met shipped_boxes. Met een testsleutel: dry_run: true, een nieuw dryrun_ ID per aanroep en geen reservering van voorraad. Een geslaagde dry run garandeert niet dat de voorraad er bij het echte verzoek nog is.
7
Fouten enopnieuwproberen
7. Fouten en opnieuw proberen
API handleiding26
Veilig opnieuw proberen met een Idempotency-Key
Boeking aanmaken, boeking bijwerken en zending aanmaken vragen altijd een Idempotency-Key header, ook bij een dry run. Daarmee kun je na een time-out of netwerkfout hetzelfde verzoek gerust nog een keer sturen zonder dat er een dubbele boeking ontstaat.
Hoe het werkt
- ✓ Kies per bewerking een unieke sleutel, bijvoorbeeld je ordernummer plus een volgnummer
- ✓ 1 tot 128 tekens: letters, cijfers, punt, underscore, dubbele punt en koppelteken. Hoofdlettergevoelig
- ✓ Geslaagde antwoorden bewaren we 24 uur. Stuur je dezelfde sleutel met dezelfde inhoud opnieuw, dan krijg je dat antwoord terug zonder dat er iets opnieuw gebeurt
- ✓ De sleutel geldt per bedrijf en per bewerking, over al je API clients heen. Bij een update hoort ook het boekingsnummer bij de identiteit
Na een time-out
Herhaal exact hetzelfde verzoek met dezelfde sleutel en dezelfde inhoud. Krijg je 409 idempotency.in_progress, dan loopt de eerste poging nog: wacht even en probeer dezelfde sleutel opnieuw. Gebruik nooit een nieuwe sleutel na een onbekende uitkomst, dan kun je een dubbele aanmaken.
409 idempotency.conflict
Dezelfde sleutel, maar andere velden of andere bestandsbytes. Dat weigeren we. Alleen de document referentie UUID's mogen verschillen. Na 24 uur kan dezelfde sleutel weer een nieuwe bewerking starten.
Dry run onthoudt niets
Met een testsleutel bewaren we geen antwoorden en controleren we niet op conflicten. De header is wel verplicht, zodat je code gelijk is aan live.
Voorbeeld van een foutantwoord
HTTP/1.1 422 Unprocessable Content X-Request-ID: req_01HZXABC123 { "status": 422, "request_id": "req_01HZXABC123", "errors": [ { "code": "validation.failed", "message": "The given data was invalid.", "details": { "products.0.hs_code": ["verplicht"] }, "retryable": false } ] }
7. Fouten en opnieuw proberen
API handleiding27
Foutcodes en wat je doet
Elke fout heeft status, request_id en een lijst errors met code, message, details en retryable. Fouten bij het token endpoint gebruiken error en error_description.
Antwoord
Controleer of doe dit
401 invalid_client (token endpoint)
Client_id of secret klopt niet, de sleutel is verlopen of ingetrokken, of API toegang voor je bedrijf staat uit.
401 request.unauthenticated
Geen of een verlopen Bearer token. Vraag een nieuwe token aan.
403 request.forbidden
Je sleutel mist het recht voor dit endpoint. Pas de rechten aan en vraag een nieuwe token.
403 company.disabled
API toegang voor je bedrijf staat uit. Neem contact op met Import4You als dit na november 2026 nog gebeurt.
403 client.ip_not_allowed
Het uitgaande IP staat niet op de lijst van de sleutel. Zie hoofdstuk 2.
404 request.not_found
Onbekend ID, of het hoort bij een ander bedrijf.
409 idempotency.conflict / idempotency.in_progress
Zie de vorige pagina. Kijk naar retryable.
422 validation.failed / reference.unknown
Kijk in details welk veld. Een verwijzing (locatie, voorraad, productindeling) moet van je eigen bedrijf zijn.
422 company.not_ready
Je bedrijfsgegevens zijn nog niet compleet, zoals adres of KvK uittreksel. Vul ze aan in het platform of mail ons.
422 stock.insufficient / stock.boltrics_blocked
Te weinig dozen, of de voorraad is tijdelijk geblokkeerd in het magazijnsysteem. De tweede heeft retryable: true: probeer later opnieuw.
429 rate_limit.exceeded
Te veel verzoeken. Verlaag de frequentie; de limiet geldt per sleutel én per bedrijf.
503 public_api.disabled
De API staat op deze omgeving uit. Neem contact op met Import4You.
Vragen aan support? Noem de X-Request-ID, het endpoint, het tijdstip en de HTTP status. Stuur nooit je secret, token of documenten mee.
7. Fouten en opnieuw proberen
API handleiding28
Checklist voordat je live gaat
Techniek
- ✓ Token wordt hergebruikt en vernieuwd bij een 401 of vlak voor het verlopen
- ✓ Elke schrijfactie heeft een unieke, herleidbare Idempotency-Key
- ✓ Bij time-outs herhaal je met dezelfde sleutel, met oplopende wachttijd
- ✓ Bedragen, gewicht en CBM gaan als tekst met punt, niet als getal
- ✓ De X-Request-ID wordt gelogd bij elk verzoek
- ✓ Fouten met retryable: true worden later opnieuw geprobeerd, de rest komt bij een mens terecht
Proces
- ✓ Alles is eerst met de testsleutel gedaan, inclusief een update van een boeking
- ✓ De livesleutel heeft precies de rechten die nodig zijn, niet meer
- ✓ Het secret staat alleen in je secret store
- ✓ Je weet wie bij jullie de sleutel beheert en wanneer hij verloopt
- ✓ Wil je statuswijzigingen van boekingen als push ontvangen, dan is de webhook ingesteld (zie de webhook handleiding)
- ✓ Het IP van je server staat op de lijst, of de lijst is bewust leeg
!
Live vanaf eind november 2026. Bouw en test je koppeling nu alvast tegen de documentatie. Vanaf dat moment staat de API automatisch in je account onder Automation en maak je daar je testsleutel.
8
Testen envragen
8. Testen in Swagger
API handleiding30
Zelf proberen in Swagger, zonder code
Swagger is de interactieve documentatie op https://api.import4you.nl/public-api/documentation. Je kunt er elk endpoint uitproberen met je eigen sleutel. De verzoeken zijn echt: met een livesleutel maak je dus echt een boeking aan.
- Open Swagger en klik rechtsboven op Authorize.
- Kies PublicApiOAuth2 (clientCredentials). Vul client_id en client_secret in en vink de rechten aan die op je sleutel staan. Extra vinkjes geven geen extra rechten.
- Klik Authorize. Swagger haalt een token op en zet die automatisch bij elk verzoek.
- Open GET /bookings of GET /stock, klik Try it out en daarna Execute. Bekijk de status, het antwoord en de X-Request-ID.
- Na 15 minuten opnieuw autoriseren. Klaar? Klik Logout in het Authorize venster.
Bestanden in Swagger
Geneste bestanden zoals documents[commercial_invoice][file] kan Swagger niet altijd goed verpakken. Lukt het niet, gebruik dan een REST client of je eigen code met dezelfde veldnamen.
OpenAPI importeren
Importeer https://api.import4you.nl/public-api/openapi in je REST client, dan heb je alle endpoints, velden en voorbeelden meteen klaarstaan.
Het token endpoint zelf uitvoeren
Dat toont alleen het antwoord. De token wordt dan niet bij andere endpoints gebruikt; daarvoor gebruik je altijd het Authorize venster.
8. Veelgestelde vragen
API handleiding31
Veelgestelde vragen
Wanneer kan ik beginnen?
De publieke API gaat eind november 2026 live. Je koppeling kun je nu al bouwen op basis van deze handleiding en de OpenAPI specificatie. Aanvragen is niet nodig: na november 2026 staat de API automatisch in je eigen account onder het kopje Automation.
Hoe krijg ik direct bericht bij een statuswijziging?
Via de boeking webhook. Die stuurt een ondertekend POST verzoek naar jouw adres zodra de status of de verwachte leverdatum van een boeking verandert. Dat is een losse koppeling met eigen inloggegevens, zie de webhook handleiding.
Wat als ik mijn secret kwijt ben?
Maak in het platform een nieuw secret aan voor de sleutel (roteren) of maak een nieuwe sleutel. Het oude secret en alle tokens ervan werken dan direct niet meer.
Zie ik ook FCL boekingen en hun extra kosten?
Ja, boekingen van elk type staan in de API. Bij FCL kan er een tweede factuur zijn met type fcl_additional_costs; die staat los van de boekingsfactuur in invoices.
Waar kan ik terecht met vragen?
Mail support@import4you.nl met je X-Request-ID, het endpoint en het tijdstip, of gebruik de contactpagina . De Engelstalige technische gids staat in Swagger onder "Public API integration guide".
