AdresDirect 365: handleiding

Hoe het werkt

AdresDirect 365 voegt het veld Huisnummer toe, direct na Postcode, bij klanten, leveranciers, contactpersonen, verzendadressen, bestelladressen van leveranciers, vestigingen en de bedrijfsgegevens. Typt iemand daar een Nederlandse postcode en een huisnummer, dan vraagt de app het adres op bij de BAG en vult hij de standaardvelden van Business Central in.

De aanvraag gaat rechtstreeks van uw Business Central-omgeving naar de BAG API Individuele Bevragingen van het Kadaster, met uw eigen API-sleutel. Er zit geen server van Van Oosten Software tussen. Per aanvraag gaan alleen de postcode en, als die er is, het huisnummer mee, en de app wacht maximaal vijf seconden op antwoord.

Standaard zoekt de app alleen op als iemand op een kaart typt. Adressen die via een import, een configuratiepakket, een API-koppeling of andere code binnenkomen, worden alleen opgezocht als Opzoeken bij import en API's aanstaat.

Lukt het opzoeken niet, dan blijft alles zoals het was; typt iemand zelf, dan zegt een melding waarom. Opslaan wordt nooit geblokkeerd.

Voordat u begint

Dit hebt u nodig:

• Business Central online, Essentials of Premium, versie 28 of hoger.
• Een eigen API-sleutel voor de BAG API Individuele Bevragingen. Het Kadaster geeft die gratis uit aan uw organisatie; u vraagt hem aan met het aanvraagformulier van het Kadaster, dat de actie API-sleutel aanvragen op de instellingenpagina opent. De sleutel komt per e-mail, doorgaans binnen een uur op werkdagen tijdens kantooruren. Lees ook De sleutel en de limieten van het Kadaster, hieronder.
• In een sandbox: toestemming voor uitgaande HTTP-aanvragen (zie Instellen).
• Voor wie de instellingen beheert: de machtigingenset AdresDirect 365 of een ruimere (zie Machtigingen).

De sleutel en de limieten van het Kadaster

Het Kadaster stelt voorwaarden aan het gebruik van de BAG API Individuele Bevragingen. De belangrijkste:

• Een sleutel hoort bij de organisatie waaraan hij is uitgegeven, en alleen die organisatie mag hem gebruiken. Deel hem niet met andere organisaties. Van Oosten Software levert daarom geen sleutel: elke organisatie vraagt er zelf een aan.
• Maximaal 50.000 aanvragen per dag, een teller die na middernacht opnieuw begint, en maximaal 50 aanvragen per seconde.
• De API is bedoeld om één of enkele adressen op te zoeken, niet voor bulk. Voor grote aantallen adressen biedt het Kadaster BAG Extract en BAG GeoPackage.

Daarom zoekt de app standaard alleen op als iemand typt, en staat Opzoeken bij import en API's standaard uit. Een postcode zonder huisnummer die al in de tabel Postcodes staat, kost geen aanvraag.

Vragen over uw sleutel of over de BAG zelf beantwoordt de klantenservice BAG van het Kadaster, op 088 183 34 00. Het aanvraagformulier en de richtlijnen van het Kadaster staan onderaan deze pagina, onder Bij het Kadaster.

Instellen

Zoek in Business Central naar Instellingen AdresDirect 365, of open de pagina via Handmatige instellingen. Doe dan het volgende:

1. Hebt u nog geen sleutel, kies dan API-sleutel aanvragen. Dat opent het aanvraagformulier van het Kadaster; vraag de sleutel aan op naam van uw eigen organisatie. U krijgt hem per e-mail, doorgaans binnen een uur op werkdagen tijdens kantooruren.
2. In die e-mail staat ook een basis-URL van de API. Die hoeft u nergens in te vullen, want de app kent hem al: alleen de sleutel gaat naar Business Central.
3. Plak de sleutel in het veld API-sleutel. Na het opslaan toont het veld alleen nog ********.
4. Kies Verbinding testen. De app stuurt één aanvraag naar de BAG en meldt of de sleutel is geaccepteerd.
5. Zet Ingeschakeld aan.
6. Kijk Land-/regiocode (standaard NL), Provincie invullen, Postcodes bewaren en Opzoeken bij import en API's na. De standaardwaarden passen bij de meeste bedrijven.

In een sandbox

Een sandbox laat apps standaard geen uitgaande HTTP-aanvragen doen. Open dan Extensiebeheer, kies AdresDirect 365, kies Configureren en zet HttpClient-aanvragen toestaan aan. Zonder die toestemming kan de app de BAG niet bereiken.

Dagelijks gebruik

Typ op een adreskaart de postcode en het huisnummer. Zodra u het veld verlaat, vult de app in:

• Adres: de straat en het huisnummer.
• Plaats: de woonplaats zoals de BAG die noemt.
• Provincie: de provincie van de postcode, als Provincie invullen aanstaat.
• Postcode: herschreven als 1234 AB, ook als u 1234ab typte.

De volgorde maakt niet uit: de app zoekt op zodra u de postcode of het huisnummer wijzigt, en gebruikt wat er op dat moment staat.

Typt u alleen een postcode, dan vult de app Plaats en Provincie in, maar niet de straat: één postcode kan over twee straten lopen. Staat de postcode al in de tabel Postcodes, dan komt de plaats daaruit, zonder aanvraag bij de BAG.

Huisnummers met een letter of toevoeging

Typ het huisnummer zoals u gewend bent: 12, 12a, 12 A, 12-2 of 12B bis. Eerst het nummer, dan eventueel een letter of toevoeging. Wat na het nummer komt, vergelijkt de app met huisletter en toevoeging samen, zoals de BAG ze kent. Spaties, streepjes, schuine strepen, punten en hoofdletters maken daarbij niet uit.

Alleen als iemand typt, standaard

Standaard zoekt de app alleen op als een gebruiker op een kaart typt. Komen adressen binnen via een import, een configuratiepakket, een API-koppeling of andere code, dan zoekt de app ze alleen op als Opzoeken bij import en API's aanstaat. Ook dan verschijnen er geen meldingen en geen keuzelijst: past er niets precies of lukt het opzoeken niet, dan blijft het adres zoals het binnenkwam. Laat de instelling uit bij grote imports: de BAG API is niet bedoeld voor bulk, en een grote import kan de daglimiet van uw sleutel opmaken.

Kies een adres

Past geen enkel adres precies, bijvoorbeeld als u 14 typt terwijl alleen 14A en 14B bestaan, dan opent de lijst Kies een adres met de adressen op dat nummer. Kies het juiste adres en bevestig met OK. Sluit u de lijst zonder te kiezen, dan blijven de velden zoals ze waren.

De instellingenpagina

Instellingen AdresDirect 365 heeft deze velden en acties. Alles geldt per bedrijf.

API-sleutel

Uw sleutel voor de BAG API Individuele Bevragingen. Hij wordt versleuteld opgeslagen in isolated storage van dit bedrijf en daarna niet meer getoond: het veld toont ********. Maakt u het veld leeg, dan wordt de sleutel verwijderd en gaat Ingeschakeld uit.

Ingeschakeld

Of adressen worden opgezocht. Kan pas aan als er een sleutel is opgeslagen; anders meldt de pagina Voer eerst de BAG API-sleutel in.

Land-/regiocode

De land-/regiocode van Nederland in dit bedrijf, standaard NL. Adressen met een ander land worden niet opgezocht. Een adres zonder land wordt opgezocht als het bedrijf zelf in dit land zit.

Provincie invullen

Of het veld Provincie wordt ingevuld, standaard aan. De BAG kent geen provincies; de app leidt de provincie af uit de eerste vier cijfers van de postcode.

Postcodes bewaren

Of elke gevonden postcode aan de tabel Postcodes wordt toegevoegd, standaard aan. Business Central vult de plaats van zo'n postcode daarna zelf in.

Opzoeken bij import en API's

Of ook adressen worden opgezocht die niet door een gebruiker op een kaart worden getypt, maar binnenkomen via code, een configuratiepakket of import, of een API-koppeling. Standaard uit. De sleutel van het Kadaster is niet bedoeld voor bulk: laat dit uit bij grote imports.

Verbinding testen

Actie. Stuurt één aanvraag met de opgeslagen sleutel naar de BAG en meldt of die is geaccepteerd.

API-sleutel aanvragen

Actie. Opent het aanvraagformulier van het Kadaster, waar u een gratis sleutel aanvraagt voor uw organisatie.

Als het adres niet verschijnt

Lukt het opzoeken terwijl iemand typt niet, dan blijven de velden zoals ze waren en verschijnt er een melding bovenaan de pagina. Wat de meldingen betekenen:

Gebeurt er helemaal niets, geen adres en geen melding? Kijk dan na:

• of Ingeschakeld aanstaat op Instellingen AdresDirect 365;
• of het land op het adres het land van de instellingen is (standaard NL), of leeg in een bedrijf dat zelf in dat land zit;
• of de postcode uit vier cijfers en twee letters bestaat, zoals 1234 AB. Een Nederlandse postcode begint nooit met 0;
• bij een import of koppeling: of Opzoeken bij import en API's aanstaat. Meldingen verschijnen alleen als iemand zelf typt.

De tabel Postcodes

Staat Postcodes bewaren aan (de standaard), dan zet de app elke gevonden postcode met plaats, land en provincie in de standaardtabel Postcodes van Business Central. Die tabel werkt daarna als geheugen: typt iemand een postcode die er al in staat, dan komt de plaats daaruit, zonder aanvraag bij de BAG.

De tabel bewaart geen straten en geen huisnummers. Een gebruiker die geen schrijfrechten heeft op de tabel Postcodes, krijgt het adres gewoon; alleen groeit de tabel dan niet. De postcodes horen bij Business Central, niet bij de app: ze blijven staan als u de app verwijdert.

Machtigingen

Wie adressen invoert, heeft geen extra machtigingenset nodig: het opzoeken brengt zijn eigen rechten mee. De machtigingenset AdresDirect 365 (object VOA AdresDirect 365) is voor wie Instellingen AdresDirect 365 beheert.

Meer bedrijven

Instellingen en API-sleutel gelden per bedrijf. Richt elk bedrijf waarin u adressen wilt laten opzoeken apart in: sleutel invullen, verbinding testen, inschakelen. In een bedrijf zonder instellingen verandert er niets aan hoe Business Central werkt.

Bronnen

De adressen komen uit de Basisregistratie Adressen en Gebouwen (BAG) van het Kadaster, via de BAG API Individuele Bevragingen. De BAG is open data (CC0). De provincie per postcodegebied is afgeleid van gegevens van GeoNames (geonames.org), onder de licentie Creative Commons Naamsvermelding 4.0 (CC BY 4.0): een tabel van 4.086 gebieden.

Hulp nodig?

Staat uw vraag niet in deze handleiding, mail dan naar info@van-oosten.nl. Op de pagina Ondersteuning staat wat u meestuurt.