Pakketvelden & eenheden

Deze veldgids geldt voor de JSON-body van POST /deliveries/v1/parcels. De API maakt zelf een entry_id aan. Gebruik dat ID later in het URL-pad om de levering op te vragen, te wijzigen of een gebeurtenis toe te voegen.

Zo lees je de tabellen

Op een smal scherm kun je brede tabellen zijwaarts schuiven om alle kolommen te lezen.

• Ja: verplicht bij aanmaken; een lege waarde is niet voldoende.
• Voorwaardelijk: verplicht zodra je de genoemde combinatie gebruikt.
• Nee: je mag het veld weglaten. Bij numerieke velden is weglaten meestal beter dan een onbekende waarde als 0 invullen.
• PATCH ja: dit veld mag je later wijzigen met PATCH /deliveries/v1/parcels/{id} en de actuele If-Match-header. Stuur dan alleen de wijzigingen; de complete levering wordt opnieuw gecontroleerd.

Tekst staat in JSON tussen dubbele aanhalingstekens. Getallen hebben geen aanhalingstekens, eenheid of duizendtalscheiding. number is een huisnummer als tekst: "16". parcel_weight is een gewicht als getal: 1200.

Eenheden en tekstlengtes

Invoer	Formaat	Goed voorbeeld	Veelgemaakte fout
Afmetingen	Geheel getal in millimeters, 0–32767	"parcel_length": 300 voor 30 cm	"30 cm" of 0.3
Gewicht	Geheel getal in grammen, 0–2147483647	"parcel_weight": 1200 voor 1,2 kg	1.2, "1200" of "1,2 kg"
Invoertijd	Unix-seconden UTC, geheel getal	1792137600 = 16 oktober 2026, 08:00 UTC	Milliseconden zoals 1792137600000, of een datumstring
Keuzeveld	Numerieke code uit de tabellen hieronder	"service_type": 1	"express" als waarde sturen
Tekst	Maximaal 32 UTF-8-bytes per veld; delivery_vehicle maximaal 64	"city": "Delfzijl"	Nieuwe regels, nultekens of te lange tekst

De lengtegrens is in bytes, niet alleen zichtbare tekens: een letter zonder accent gebruikt doorgaans één byte, é twee en veel emoji vier. Gebruik voor vervoerderscodes uitsluitend de toegestane kleine letters, cijfers, _ en -. Vul bij onbekende optionele gegevens geen verzonnen waarden in.

Minimale geldige invoer

{
  "courier": "demo",
  "country": "NL",
  "postal_code": "9901KB",
  "number": "16"
}

Vervang demo door een voor jouw organisatie geregistreerde code. De status wordt bij weglaten 0 (aangemeld) en het aantal pogingen wordt berekend als 0. Andere optionele numerieke velden krijgen niet automatisch een gemeten of geschatte waarde.

De volgende tabellen bevatten alle 41 invoervelden. De voorbeelden zijn illustratief; gebruik de feitelijke gegevens van je levering.

Vervoerder en basisadres

Veld	Verplicht bij aanmaken?	Voorbeeld	Invullen en grenzen	PATCH?
courier	Ja	"demo"	Geregistreerde code; 1–32 kleine letters, cijfers, underscores of koppeltekens. Begin met een letter of cijfer. Neem de code exact over.	Nee
country	Ja	"NL"	Landcode; uitsluitend NL (hoofdletters).	Ja
city	Nee	"Delfzijl"	Plaatsnaam; maximaal 32 UTF-8-bytes.	Ja
postal_code	Ja	"9901KB"	Nederlandse postcode: vier cijfers en twee letters; bijvoorbeeld 9901KB.	Ja
street	Nee	"Voorbeeldstraat"	Straatnaam; maximaal 32 UTF-8-bytes. Vervang dit voorbeeld door de echte straat.	Ja
number	Ja	"16"	Huisnummer als tekst; maximaal 32 UTF-8-bytes. Zie adrescontrole voor letters en toevoegingen.	Ja
addition	Nee	"A"	Toevoeging als tekst; maximaal 32 UTF-8-bytes. Weglaten of lege tekst als er geen toevoeging is.	Ja

Planning, pakket en status

Veld	Verplicht bij aanmaken?	Voorbeeld	Invullen en grenzen	PATCH?
time_slot_period_start	Voorwaardelijk: samen met einde	1792137600	Begin tijdvak in Unix-seconden UTC. Vanaf 1 januari 2000 tot één jaar na nu.	Ja
time_slot_period_end	Voorwaardelijk: samen met begin	1792144800	Einde tijdvak in Unix-seconden UTC; na het begin en hoogstens zeven dagen later.	Ja
time_delivered	Alleen bij delivery_status 4; dan verplicht	1792141200	Werkelijke aflevertijd in Unix-seconden UTC. Bij andere statussen weglaten.	Nee
parcel_length	Nee	300	Geheel getal in millimeters: 0–32767. Laat weg als de afmeting onbekend is.	Ja
parcel_width	Nee	200	Geheel getal in millimeters: 0–32767. Laat weg als de afmeting onbekend is.	Ja
parcel_height	Nee	150	Geheel getal in millimeters: 0–32767. Laat weg als de afmeting onbekend is.	Ja
parcel_weight	Nee	1200	Geheel getal in grammen: 0–2147483647. Laat weg als het gewicht onbekend is.	Ja
delivery_status	Nee; standaard 0	0	Bezorgstatus 0–5. Status 4 vereist time_delivered.	Nee
delivery_attempts	Nee; automatisch berekend	0	Bij aanmaken exact het aantal ingevulde pogingslots (0–3). Latere pogingen worden apart gemeld; totaal maximaal 127.	Nee
service_type	Nee	0	Servicecode 0–2; standaardservice is 0, express 1 en same-day 2.	Ja
delivery_vehicle	Nee	"bestelbus"	Vrije omschrijving van het voertuig, maximaal 64 UTF-8-bytes; geen vaste codelijst.	Ja

Gepland bezorgadres

Veld	Verplicht bij aanmaken?	Voorbeeld	Invullen en grenzen	PATCH?
planned_country	Voorwaardelijk: samen met land, postcode en nummer van deze groep	"NL"	Landcode; uitsluitend NL (hoofdletters).	Ja
planned_city	Nee	"Delfzijl"	Plaatsnaam; maximaal 32 UTF-8-bytes.	Ja
planned_postal_code	Voorwaardelijk: samen met land, postcode en nummer van deze groep	"9901KB"	Nederlandse postcode: vier cijfers en twee letters; bijvoorbeeld 9901KB.	Ja
planned_street	Nee	"Voorbeeldstraat"	Straatnaam; maximaal 32 UTF-8-bytes. Vervang dit voorbeeld door de echte straat.	Ja
planned_number	Voorwaardelijk: samen met land, postcode en nummer van deze groep	"16"	Huisnummer als tekst; maximaal 32 UTF-8-bytes. Zie adrescontrole voor letters en toevoegingen.	Ja
planned_addition	Nee	"A"	Toevoeging als tekst; maximaal 32 UTF-8-bytes. Weglaten of lege tekst als er geen toevoeging is.	Ja
planned_location_type	Nee	0	Locatiecode 0–6; zie de codetabel hieronder. Weglaten als onbekend.	Ja

Werkelijk afleveradres

Veld	Verplicht bij aanmaken?	Voorbeeld	Invullen en grenzen	PATCH?
delivered_country	Voorwaardelijk: samen met land, postcode en nummer van deze groep	"NL"	Landcode; uitsluitend NL (hoofdletters).	Nee
delivered_city	Nee	"Delfzijl"	Plaatsnaam; maximaal 32 UTF-8-bytes.	Nee
delivered_postal_code	Voorwaardelijk: samen met land, postcode en nummer van deze groep	"9901KB"	Nederlandse postcode: vier cijfers en twee letters; bijvoorbeeld 9901KB.	Nee
delivered_street	Nee	"Voorbeeldstraat"	Straatnaam; maximaal 32 UTF-8-bytes. Vervang dit voorbeeld door de echte straat.	Nee
delivered_number	Voorwaardelijk: samen met land, postcode en nummer van deze groep	"16"	Huisnummer als tekst; maximaal 32 UTF-8-bytes. Zie adrescontrole voor letters en toevoegingen.	Nee
delivered_addition	Nee	"A"	Toevoeging als tekst; maximaal 32 UTF-8-bytes. Weglaten of lege tekst als er geen toevoeging is.	Nee
delivered_location_type	Nee	0	Locatiecode 0–6; zie de codetabel hieronder. Weglaten als onbekend.	Nee

Historische bezorgpogingen

Veld	Verplicht bij aanmaken?	Voorbeeld	Invullen en grenzen	PATCH?
time_attempt_1	Voorwaardelijk: samen met uitkomst	1792137600	Tijd van poging 1, Unix-seconden UTC. Gebruik de werkelijke waarnemingstijd; slots beginnen bij 1.	Nee
attempt_1_outcome	Voorwaardelijk: samen met tijd	1	Uitkomst 0–4 van poging 1. Zie de uitkomsttabel bij gebeurtenissen en pogingen.	Nee
attempt_1_reason	Nee; alleen bij ingevulde poging	1	Reden 0–10 van poging 1. Bij weglaten geldt 0 (geen aanvullende reden).	Nee
time_attempt_2	Voorwaardelijk: samen met uitkomst	1792138200	Tijd van poging 2, Unix-seconden UTC. Gebruik de werkelijke waarnemingstijd; slots beginnen bij 1.	Nee
attempt_2_outcome	Voorwaardelijk: samen met tijd	1	Uitkomst 0–4 van poging 2. Zie de uitkomsttabel bij gebeurtenissen en pogingen.	Nee
attempt_2_reason	Nee; alleen bij ingevulde poging	1	Reden 0–10 van poging 2. Bij weglaten geldt 0 (geen aanvullende reden).	Nee
time_attempt_3	Voorwaardelijk: samen met uitkomst	1792138800	Tijd van poging 3, Unix-seconden UTC. Gebruik de werkelijke waarnemingstijd; slots beginnen bij 1.	Nee
attempt_3_outcome	Voorwaardelijk: samen met tijd	1	Uitkomst 0–4 van poging 3. Zie de uitkomsttabel bij gebeurtenissen en pogingen.	Nee
attempt_3_reason	Nee; alleen bij ingevulde poging	1	Reden 0–10 van poging 3. Bij weglaten geldt 0 (geen aanvullende reden).	Nee

Adresgroepen correct combineren

Het basisadres vereist altijd country, postal_code en number. country moet exact "NL" zijn. Gebruik een postcode als "9901KB": vier cijfers (de eerste niet nul) en twee letters. Voor de adrescontrole worden spaties en kleine letters genormaliseerd. Straat en plaats zijn optioneel; ze vervangen postcode en huisnummer niet.

Voor het geplande adres en afgeleverde adres gelden dezelfde groepsregels: zodra je land, postcode of nummer uit die groep opgeeft, moeten alle drie aanwezig zijn. Vul bij een echte adresgroep daarom altijd die drie velden samen in. Alleen een plaatsnaam of locatietype vormt geen bruikbaar volledig adres.

planned_* beschrijft het geplande bezorgadres; delivered_* het daadwerkelijk gebruikte afleveradres. Laat een onbekende groep weg. Je hoeft niet op voorhand een afgeleverd adres te verzinnen. Bij het later melden van aflevering gebruik je het delivered-object van een bezorgpoging.

Tijdvak, aflevertijd en status

Een tijdvak bestaat altijd uit time_slot_period_start en time_slot_period_end. Het einde moet groter zijn dan het begin; het verschil is maximaal 604800 seconden (zeven dagen). Het begin ligt tussen 1 januari 2000, 00:00 UTC (946684800) en één jaar na het moment van aanvragen.

Bij status 4 (afgeleverd) is time_delivered verplicht. Bij iedere andere status laat je time_delivered weg. Het tijdstip moet vanaf 1 januari 2000 liggen en mag niet meer dan vijf minuten in de toekomst liggen. Gebruik de echte aflevertijd; de tolerantie is voor een kleine klokafwijking.

Historische bezorgpogingen en gebeurtenistijden hebben dezelfde grens van 1 januari 2000 tot maximaal vijf minuten in de toekomst. Zie Aanvragen opbouwen voor tijdconversie.

Bezorgstatussen

Code	Naam	Betekenis
0	pending	Aangemeld; standaard bij een nieuwe levering.
1	collected	Opgehaald.
2	in_transit	Onderweg.
3	out_for_delivery	In bezorging.
4	delivered	Afgeleverd; bij registratie is time_delivered verplicht.
5	failed	Bezorging mislukt.

Bij aanmaken kun je de actuele status 0–5 meegeven, bijvoorbeeld bij import van een bestaande levering. Latere statuswijzigingen gaan via gebeurtenissen of pogingen, zodat de historie behouden blijft.

Service- en locatiecodes

service_type	Betekenis
0	standard — standaardservice.
1	express — expressservice.
2	same_day — bezorging dezelfde dag.

planned_location_type / delivered_location_type	Betekenis
0	recipient_door — deur van de ontvanger.
1	neighbour — buren.
2	pickup_point — afhaalpunt.
3	parcel_locker — pakketkluis.
4	safe_place — afgesproken veilige plek.
5	reception — receptie.
6	depot — depot.

Een ontbrekende service- of locatiecode betekent dat je hem niet hebt opgegeven. Geef expliciet 0 mee als je standaardservice of deur van de ontvanger bedoelt. De actuele codereeksen kun je ook opvragen via GET /deliveries/v1/reference met deliveries:read.

Historische pogingen bij aanmaken

Bij registratie zijn maximaal drie pogingslots beschikbaar. Begin met slot 1; slot 2 kan alleen na 1 en slot 3 alleen na 1 en 2. Binnen elk slot horen tijd en uitkomst bij elkaar. De reden is optioneel en wordt bij weglaten 0 (geen aanvullende reden). Een losse reden zonder bijbehorende poging is ongeldig.

delivery_attempts wordt uit de ingevulde slots berekend. Laat het bij voorkeur weg. Geef je het toch mee, dan moet het bij aanmaken exact gelijk zijn aan het aantal ingevulde slots: 0, 1, 2 of 3. Bijvoorbeeld twee ingevulde slots vereisen delivery_attempts: 2, niet 3 of 10.

De uitkomsten en redenen staan bij Gebeurtenissen & pogingen. Het importeren van pogingslots berekent niet automatisch je actuele status uit de laatste poging: geef delivery_status en, bij aflevering, time_delivered passend bij je brongegevens mee. Latere pogingen meld je via het pogingenendpoint. In totaal zijn maximaal 127 pogingen per levering mogelijk.

Wijzigen of een waarde leegmaken

Bij PATCH behouden weggelaten velden hun bestaande waarde. Een optioneel numeriek veld zoals parcel_weight kun je leegmaken met null. Een optioneel tekstveld zoals addition maak je leeg met "".

{"parcel_weight": null, "addition": ""}

Maak een tijdvak altijd als paar leeg: {"time_slot_period_start": null, "time_slot_period_end": null}. Bij het verwijderen van een gepland adres maak je alle bijbehorende tekstvelden leeg en zet je het locatietype op null. Het verplichte basisadres mag nooit onvolledig worden.

courier, delivery_status, delivery_attempts, time_delivered, alle delivered_*-velden en alle historische pogingslots zijn niet met PATCH te wijzigen. Ook niet met een lege waarde. Gebruik de juiste gebeurtenis- of pogingenaanvraag voor nieuwe waarnemingen; vraag hulp bij een foutief geregistreerde vervoerder.

Velden die je terugkrijgt

Veld in het antwoord	Betekenis	Zelf meesturen?
entry_id	Door vlows gegenereerde UUID van de levering.	Alleen gebruiken in het URL-pad van vervolgaanvragen.
version	Actuele versie voor wijzigingscontrole.	Gebruik de bijbehorende ETag als If-Match-header.
created_at, updated_at	Serverdatum als RFC 3339-string, bijvoorbeeld 2026-10-16T08:00:00Z.	Nee.
address, planned_address, delivered_address	Uitkomst van de BAG-adrescontrole bij een detailantwoord.	Nee; zie Adrescontrole.

Deze antwoordvelden zijn geen invoervelden. De API accepteert geen parcel_id, retourvelden, parcel_flags, shipping_cost of pickup_point_id. Download het veldcontract als JSON of de OpenAPI-specificatie.