# 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

```json
{
  "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](/gebeurtenissen/#velden-voor-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](/aanvragen-opbouwen/#tijd-omzetten-naar-unix-seconden) 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](/gebeurtenissen/), 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](/gebeurtenissen/). 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 `""`.

```json
{"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](/adressen/). |

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](/assets/parcel-fields.json) of de [OpenAPI-specificatie](/assets/openapi.json).