# 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.

```sh
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.

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

## 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.