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 adresdienst: standaard de PDOK Locatieserver, de open dienst van het Kadaster, zonder sleutel. Kiest u de BAG API Individuele Bevragingen, dan gaat de aanvraag met uw eigen API-sleutel naar het Kadaster. 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.
• Geen sleutel: standaard gebruikt de app de PDOK Locatieserver. Alleen als u de BAG API Individuele Bevragingen wilt gebruiken, vraagt u bij het Kadaster een eigen, gratis API-sleutel aan. Zie Twee adresdiensten, 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).

Twee adresdiensten

Beide diensten leveren de adressen uit de BAG van het Kadaster. U kiest er per bedrijf één in het veld Adresdienst op Instellingen AdresDirect 365.

Kies de BAG API als nieuwe adressen al op de dag van registratie moeten verschijnen, of als uw organisatie een eigen sleutel en eigen afspraken met het Kadaster wil. De app stapt nooit vanzelf over naar de andere dienst: een storing of een geweigerde sleutel blijft zichtbaar in de melding.

De sleutel en de limieten van het Kadaster

Alleen voor wie de BAG API kiest. 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. Dat geldt ook voor PDOK, dat de Locatieserver een zoekdienst noemt en voor grote aantallen naar downloads verwijst. 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

Na de installatie staat de opzoeking aan, met de PDOK Locatieserver: u hoeft niets in te stellen. Wilt u iets nakijken of wijzigen, zoek dan in Business Central naar Instellingen AdresDirect 365, of open de pagina via Handmatige instellingen.

1. Kies Verbinding testen. De app stuurt één aanvraag naar de gekozen adresdienst en meldt of die antwoordde.
2. Kijk Land-/regiocode (standaard NL), Provincie invullen, Postcodes bewaren en Opzoeken bij import en API's na. De standaardwaarden passen bij de meeste bedrijven.

De BAG API gebruiken

1. Kies bij Adresdienst de BAG API Individuele Bevragingen. Is er nog geen sleutel opgeslagen, dan gaat Ingeschakeld uit.
2. 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.
3. 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.
4. Plak de sleutel in het veld API-sleutel. Na het opslaan toont het veld alleen nog ********.
5. Kies Verbinding testen. De app meldt of de BAG de sleutel accepteert.
6. Zet Ingeschakeld aan.

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 PDOK en 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 nieuwe aanvraag.

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: beide adresdiensten zijn niet bedoeld voor bulk, en met de BAG API kan een grote import 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.

Adresdienst

Waar adressen worden opgezocht: PDOK Locatieserver (standaard, zonder sleutel) of BAG API Individuele Bevragingen (met uw eigen API-sleutel). Kiest u de BAG API terwijl er geen sleutel is opgeslagen, dan gaat Ingeschakeld uit.

API-sleutel

Alleen bij de BAG API. 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, standaard aan. Met de BAG API kan het 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. Beide adresdiensten zijn niet bedoeld voor bulk: laat dit uit bij grote imports.

Verbinding testen

Actie. Stuurt één aanvraag naar de gekozen adresdienst en meldt of die antwoordde; met de BAG API ook of de sleutel is geaccepteerd.

API-sleutel aanvragen

Actie, alleen bij de BAG API. 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 nieuwe aanvraag.

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

De instellingen, en bij de BAG API de sleutel, gelden per bedrijf. Na een nieuwe installatie staat de opzoeking in elk bedrijf aan met de PDOK Locatieserver, ook in een bedrijf dat u later aanmaakt. Wilt u de BAG API, richt dan elk bedrijf apart in: adresdienst kiezen, sleutel invullen, verbinding testen, inschakelen.

Bronnen

De adressen komen uit de Basisregistratie Adressen en Gebouwen (BAG) van het Kadaster, standaard via de PDOK Locatieserver en desgewenst 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.