Adrescontrole met de BAG

Met adrescontrole zoek je een Nederlands adres op aan de hand van postcode, huisnummer en eventuele toevoeging. De uitkomst helpt je invoer controleren. Een gevonden adres bewijst niet dat een pakket daadwerkelijk is afgeleverd.

Invoervelden

Aanvraag: POST /deliveries/v1/address/validate, met scope deliveries:write. Gebruik Authorization: Bearer <key> en Content-Type: application/json. Een Idempotency-Key is voor deze losse controle niet nodig.

Bodyveld	Nodig voor een volledige controle?	Formaat en invullen	Voorbeeld
postal_code	Ja	Nederlandse postcode als tekst. Gebruik vier cijfers en twee letters. Spaties en kleine letters worden voor het zoeken genormaliseerd.	"9901KB"
number	Ja	Huisnummer als tekst. Het numerieke deel is 1–5 cijfers en moet groter dan nul zijn. Een letter of toevoeging kan onderdeel van dit veld zijn; zie hieronder.	"16"
addition	Nee	Tekst met de afzonderlijke huisnummertoevoeging. Laat weg of gebruik "" als die er niet is.	"A"

Dit endpoint vraagt geen country, street, city, courier of levering-ID. Onbekende velden worden geweigerd. De landcode NL is wél verplicht in het basisadres bij het aanmaken van een levering.

curl --fail-with-body --silent --show-error \
  -X POST 'https://api.vlows.io/deliveries/v1/address/validate' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"postal_code":"9901KB","number":"16","addition":""}'

Vervang de voorbeeldwaarden door het adres dat je wilt controleren. Een losse controle slaat geen levering op.

Huisnummer, letter en toevoeging

Je kunt nummer en toevoeging gescheiden aanleveren of een ondersteunde combinatie in number gebruiken. Lever dezelfde letter of toevoeging niet twee keer aan.

number	addition	Hoe wordt dit gelezen?
"16"	Weggelaten of ""	Huisnummer 16 zonder toevoeging.
"16A"	Weggelaten	Nummer 16, huisletter A.
"16-1"	Weggelaten	Nummer 16, toevoeging 1.
"16"	"A"	Losse A kan in BAG een letter of toevoeging zijn; beide mogelijkheden worden onderzocht.
"16A"	"A"	Dubbele invoer; resultaat ambiguous.
"zestien"	Weggelaten	Geen ondersteund numeriek huisnummer; resultaat invalid.

Bij gecombineerde invoer ondersteunt number een nummer van 1–5 cijfers, optioneel één letter en een toevoeging van 1–4 letters/cijfers. Bij een complex of dubbelzinnig adres: vergelijk de geregistreerde BAG-notatie en stuur de onderdelen bewust gescheiden. Verwijder niet zomaar een toevoeging om alsnog een resultaat te krijgen; dat kan een ander adres opleveren.

Antwoord en status lezen

De HTTP-aanvraag kan slagen met status 200 terwijl het adres niet is gevonden. Lees daarom altijd data.status. Binnen het resultaat staat een tweede veld data met de gevonden adressen.

{
  "data": {
    "status": "not_found",
    "data": []
  },
  "error": null
}

Je leest de adreslijst dus via antwoord.data.data. Bij matched bevat die precies één adres. Bij controles die in een levering zijn opgenomen staan dezelfde objecten onder address, planned_address en delivered_address.

data.status	Betekenis	Vervolg
matched	Eén eenduidig BAG-adres gevonden.	Gebruik het gevonden adres als controle-uitkomst.
not_found	Geen exact adres gevonden.	Controleer postcode, nummer, huisletter en toevoeging.
ambiguous	Meerdere mogelijkheden of dubbelzinnige nummerinvoer.	Verduidelijk de invoer; kies niet automatisch het eerste resultaat.
invalid	Huisnummer niet in een ondersteund formaat.	Gebruik bijvoorbeeld "16", "16A" of "16-1".
pending	De controle kon tijdelijk niet betrouwbaar worden afgerond.	Probeer later opnieuw of wacht op hercontrole van een opgeslagen levering.
not_provided	Postcode en nummer zijn beide niet ingevuld.	Vul ze in als je een adres wilt controleren.

Postcode en nummer zijn inhoudelijk nodig voor een bruikbare controle. Dit endpoint rapporteert ontbrekende of onbruikbare adresinvoer via deze resultaatstatussen; verwacht niet altijd een HTTP 422. Ongeldige JSON of onbekende velden geven wel een foutantwoord.

Velden van een gevonden adres

Antwoordveld	Type	Betekenis
bag_id	Tekst	BAG-identificatie. Bewaar als tekst, ook als die alleen cijfers bevat.
postcode	Tekst	Genormaliseerde postcode.
huisnummer	Geheel getal	Numerieke deel van het huisnummer. Let op: dit is een antwoordgetal; de invoer number blijft tekst.
huisletter	Tekst	Huisletter of lege tekst.
toevoeging	Tekst	Toevoeging of lege tekst.
straat	Tekst	Gevonden straatnaam.
woonplaats	Tekst	Gevonden woonplaats.

Adressen in een levering

Een levering heeft een basisadres (country, postal_code, number), optioneel een gepland adres (planned_*) en optioneel een werkelijk afleveradres (delivered_*). Zodra je land, postcode of nummer in een optionele groep opgeeft, moet die groep alle drie bevatten en landcode NL gebruiken.

Straat en plaats zijn aanvullende invoer en vervangen postcode en huisnummer niet. De API geeft de controle-uitkomsten afzonderlijk terug; lees ze voordat je het adres als gecontroleerd beschouwt. De volledige velden en lengtegrenzen staan in Pakketvelden & eenheden.

Automatische hercontrole

Voor opgeslagen leveringen met een tijdelijke BAG-storing wordt de controle later opnieuw geprobeerd. Dit kan de leveringsversie veranderen. Lees vóór een PATCH daarom opnieuw de levering en gebruik de actuele ETag.

De losse adrescontrole bewaart geen levering en plant geen blijvende hercontrole. Krijg je daar pending, vraag de controle later zelf opnieuw aan.