Bloxs & Huurprijscheck.app integratie
API documentatie Huurprijscheck.app
Inhoudsopgave
1). Omschrijving API-koppeling
4). Configuratie in Huurprijscheck.app
1). Omschrijving API-koppeling
Met deze koppeling worden de volgende gegevens tussen Bloxs en Huurprijscheck.app uitgewisseld:
Uitgaande data: Inkomende data:
# Objecten (gebouwen en units) # Objecten (puntentelling)
# Relaties (personen)
Met deze integratie importeer je eenvoudig gebouwen en units vanuit Bloxs naar Huurprijscheck.app. Hierdoor kun je direct huurprijschecks aanmaken en uitvoeren. Na afronding van een check worden het puntentotaal, de huurprijs, het tijdvak en het rapport, automatisch gesynchroniseerd in jouw omgeving in Bloxs. In deze handleiding lees je hoe je de integratie activeert, gebouwen en units importeert vanuit Bloxs naar Huurprijscheck.app en eventueel koppelt met bestaande objecten die al zijn aangemaakt. Ook leggen we uit hoe je checks aanmaakt en synchroniseert.
2). Randvoorwaarden
Als voorbereiding op het opzetten van een API-koppeling dienen de volgende stappen uitgevoerd te worden door je applicatiebeheerder:
Activeren API
Activeren functionaliteit ‘Serviceaccounts'
Activeren van API en het aanzetten van de Serviceaccounts functionaliteit.
2.1). API-activatie
Op de Admin-pagina ga je naar het menu aan de linkerzijde en selecteer je:
Koppelingen > API
Op de API Admin-pagina activeer je de API’s
2.2). Serviceaccounts functionaliteit
Daarnaast is het nodig om op de API Admin-pagina ook de Serviceaccounts functionaliteit te activeren. Let op: dit is op dit moment nog BETA-functionaliteit.
Dit betekent dat deze optie alleen door de Bloxs helpdesk geactiveerd kan worden.
3). API-inrichting in Bloxs
De functionaliteit voor geactiveerde serviceaccounts omvat het aanmaken van een serviceaccount rol en het aanmaken van een serviceaccount. Voordat een serviceaccount ten behoeve van een API-koppeling kan worden ingericht, moet eerst een bijbehorende serviceaccount rol worden aangemaakt.
3.1). Serviceaccounts rollen
Ga naar Admin > Toegangsbeheer > > Rollen serviceaccounts
Klik op de knop: “+ Servicerol”
3.2). API-opties op serviceaccount rol
Als je die serviceaccount rol selecteert, kom je op de pagina waar je de gewenste API-permissies voor de koppeling kunt aanvinken onder de knop: "API" waarin verschillende acties (lezen, bewerken en aanmaken) per API-permissie mogelijk zijn.
Voor de koppeling met Huurprijscheck.app zijn de volgende permissies vereist:
# Objecten API
Gebouwen lezen
Gebouwen bewerken
Gebouwen aanmaken
Gebouwen BAG-gegevens lezen
Units lezen
Units bewerken
Units aanmaken
Units BAG-gegevens lezen
Puntentelling lezen
Puntentelling aanmaken
# Verkoopcontracten API
Huurcontracten wonen lezen
Huurcontracten wonen (concept) lezen
Huurcontracten wonen (concept) bewerken
Huurcontracten wonen (concept) aanmaken
3.3). Leverancier als serviceaccount
In het boven menu selecteer je menu: “Relaties”. Daarna kies je het linkerzijmenu: “Leveranciers”.
Als klant maak je een nieuwe leverancier aan voor de Huurprijscheck.app via de knop: “+Leverancier”. Dit is het serviceaccount waaraan je de serviceaccount rol koppelt die je eerder aangemaakt hebt.
Dan wordt de nieuwe leverancier als een nieuwe regel toegevoegd op de leverancierspagina.
Als je leverancier Huurprijscheck.app aanklikt kom je op terecht op het Details scherm.
3.4). Leveranciersportaal
Open de nieuw aangemaakte Huurprijscheck leverancier en ga naar het tabblad Portaal.
Op het tabblad: “Portaal” geef je de desbetreffende leverancier (Huurprijscheck.app) toegang geven tot het leveranciersportaal via de actieknop: “Toegang verschaffen”.
Daarna creëer je een E-mail via de knop: “Maak e-mail”.
Zet de optie: “API toegang” van inactief naar actief op het tabblad: “Portaal”.
Daarna kies je de optie: "Toevoegen API” aan de rechterzijde.
Nu vul je een naam voor de API-toegang in en selecteer je de gewenste serviceaccount rol.
Het API-toegang scherm verschijnt, waarop je de optie: “Zelf genereren?” op actief instelt zodat een klant de API- keys kan genereren in het Leveranciersportaal.
Daarna sla je de API-toegang op via de knop: “Toevoegen” en je serviceaccount is gereed.
Onder de kolom: “Primary API-key” kan je de API-key genereren.
Daarna opent zich een pop-upscherm waarin de API credentials (API URL; API key en API secret) getoond worden.
Via de kopieerknop aan de rechterkant van elke API credential regel kan je de desbetreffende API credential kopeieren en plakken in de corresponderende API credential velden in de klantomgeving van Huurprijscheck.app.
Ook is het mogelijk om een json-bestand , dat de API credentials (API-url, API-secret en API-key) bevat, te downloaden via de knop: “Download”.
Voorbeeld van json-bestandsinhoud met geanonimiseeerde API credentials.
Deze gegevens kan Huurprijscheck kopiëren naar de API-configuratie van de desbetreffende Huurprijscheck.app klantomgeving.
Nadat de primary API-key voor het eerst aangemaakt is, kan die ook opnieuw aangemaakt worden.
In het geval dat deze API-key verlopen is na een bepaalde tijd dan kan je de secundary API-key genereren.
4). Configuratie in Huurprijscheck.app
De volgende stappen zijn noodzakelijk voor de configuratie in Huurprijscheck.app:
4.1). Integratie activeren
Ga in Huurprijscheck.app naar Instellingen → Integraties
Klik bij de Bloxs integratie op Beheren
Ga naar het tabblad Instellingen
Vul de volgende velden in van onderdeel 1:
API-url
API-key
API-secret
Zet het Status schuifje op actief.
Klik op Opslaan
Stapsgewijs:
Stappen 1 en 2
Stap 3
Stappen 4 en 5
Stap 6
4.2). Objecten importeren
Ga naar het tabblad Objecten
Klik op Objecten importeren
Bevestig de pop-up
Via de optie: Objecten importeren worden alle objecten, behalve de gearchiveerde objecten (bij verkoop) vanuit Bloxs geïmporteerd. In principe wordt deze import eenmalig uitgevoerd. In geval van nieuwe objecten dient een nieuwe import plaats te vinden
Als je op een later moment nieuwe objecten in Bloxs toevoegt, dan zul je deze nieuwe objecten opnieuw dienen te importeren, zodat de nieuwe objecten ook beschikbaar worden.
De geïmporteerde objecten worden zichtbaar in de lijst. Je gebruikt geen credits voor het importeren van objecten.
1 objecten importeren knop
2 objecten importeren
3. objecten aan het laden
4.3). Objecten matchen
Na de import van de objecten zijn er 2 verschillende manieren om te matchen:
Automatische koppeling is mogelijk, eerst op het niveau van de Verblijfsobject-ID/ VBO-ID (via de Kadaster koppeling of handmatig ingevuld op tabblad: Details) en daarna op het niveau van adres (straat, huisnummer, postcode, plaats).
Geen koppeling als er geen match is. In dat geval bestaan er 2 matchopties:
Handmatige koppelen aan een bestaand object.
Kiezen voor 'Aanmaken als nieuw object'’
Opmerkingen:
In Bloxs heb je een veld om handmatig een BAG-ID in te vullen.
Match hier de objecten die niet automatisch gekoppeld zijn maar wel al bestaan in Huurprijscheck.app
klik op de knop "objecten matchen"
voorbeeld van matchen
overzicht van de objecten die gematcht zijn
4.4). Huurprijscheck aanmaken
Wanneer alle gebouwen en units vanuit Bloxs zijn geïmporteerd in Huurprijscheck.app als object kun je van start gaan.
Klik op Check invullen bij een object
Selecteer of het gaat om een:
Zelfstandige woning
Onzelfstandige woning
Klik op Check aanmaken
Vul de volledige check in zoals gebruikelijk.
⚠️ Let op: Zorg ervoor dat je voldoende credits hebt in je Huurprijscheck.app account om de checks aan te kunnen maken. Mocht je onvoldoende credits hebben dan kun je altijd extra credits aanschaffen. Neem hiervoor contact op met Huurprijscheck.app (zie onderdeel 9)
Check invullen
Kiezen zelfstandig of onzelfstandig
4.5). Synchronisatie
Na afronding van een check worden het puntentotaal; de huurprijs; het tijdvak en het rapport, automatisch gesynchroniseerd met het gebouw of de unit in Bloxs. De puntentelling in Bloxs is terug te vinden in het tabblad: Puntentelling van een gebouw of unit.
Als er voor een bestaand gebouw of unit al een actieve puntentelling beschikbaar is in Bloxs dan wordt die gearchiveerd. In het geval dat er een nieuwe puntentelling voor datzelfde object wordt geïmporteerd is de nieuwe puntentelling actief.
Op het tabblad: Puntentelling worden de resultaten (puntentelling; huurprijs; tijdvak en rapport) getoond. Met de knop: 'Downloaden' is het mogelijk om het rapport te exporteren als PFD-bestand.
Daarnaast komt op diezelfde pagina het rapport beschikbaar onder het tabblad: 'Bestanden'. (Huurprijscheck.app genereert alleen rapporten in het Nederlands.)
Je kunt de check ook handmatig synchroniseren naar Bloxs:
Ga in Huurprijscheck.app naar Instellingen → Integraties → Bloxs → Objecten
Klik op Synchroniseer bij het object
Hier kun je ook zien wanneer de check voor het laatst gesynchroniseerd is.
Om Huurprijscheck.app te laten integreren met een Bloxs klantomgeving moeten de volgende stappen worden uitgevoerd. Voordat een melding aangemaakt kan worden voor een object in een specifieke Bloxs klantomgeving moet je ervoor zorgen dat de object id’s in beide systemen gelijk zijn.
Bloxs
Huurprijscheck.app
5). Beheer API-koppeling
De Bloxs koppeling met de Huurprijscheck.app wordt op de volgende manier beheerd:
5.1). Beveiliging van Huurprijscheck.app
Huurprijscheck.app maakt gebruik van beveiligde verbindingen (SSL/TLS) voor alle dataverkeer. Toegang tot de applicatie en API is beveiligd met authenticatie en autorisatie op gebruikers- en organisatieniveau. Gegevens worden versleuteld opgeslagen en back-ups worden dagelijks gemaakt en versleuteld bewaard.
5.2). Serverlocatie
De servers van Huurprijscheck.app zijn ondergebracht in een streng beveiligd datacenter in Nederland (Eemshaven). Hierdoor blijven alle gegevens binnen de EU en voldoet de hosting aan de AVG-richtlijnen (GDPR).
6). Ondersteuning
Heb je hulp nodig? Neem contact op met ons supportteam!
E-mail: [email protected]
Vermeld je bedrijfsnaam, beschrijving van het probleem en een eventueel screenshot.
Of neem telefonisch contact met ons op:
+31 (0) 10 700 97 33
Last updated