Met API Link koppel je je eigen software aan Hertek Connect. Denk aan een service-systeem, meldkamerplatform of dashboard.
Via een gestandaardiseerde API lees je installatie- en statusinformatie uit. In v1 kun je gebeurtenissen via webhooks naar je eigen systeem laten doorzetten.
Deze handleiding helpt je op weg met API Link v1 en v2 en legt uit welke versie je wanneer kiest.
Begrippen
API Link v2
De nieuwe versie van Connect Link. Tokenbeheer loopt via Mijn instellingen in de portal. Data-endpoints komen gefaseerd beschikbaar.
Connect Link v1
De huidige legacy-versie van Connect Link. Deze versie is volledig functioneel voor inloggen, installaties, zones, elementen en webhooks.
Integrator
De gebruikersrol die toegang geeft tot API Link. Deze rol wordt toegekend op reseller-keten-, reseller-, portfolio- of installatieniveau. De rol wordt nooit toegekend op platform- of business-unitniveau.
Token
De sleutel waarmee je software zich identificeert bij Hertek Connect. Bij v2 is dit een persoonlijke API-token. Bij v1 is dit een token dat je krijgt na inloggen met gebruikersnaam en wachtwoord.
Webhook
Een URL aan jouw kant die Hertek Connect aanroept zodra er iets gebeurt op een installatie. Webhooks zijn alleen beschikbaar in v1.
Swagger UI
De interactieve API-documentatie waarmee je endpoints kunt lezen en testen vanuit je browser.
Connect-ID
Het unieke nummer van een installatie in Hertek Connect, gelijk aan de WebWayOneId.
Overzicht
Gebruik API Link in vier stappen:
- Vraag een Integrator-rol aan op het juiste niveau: installatie, portfolio, reseller of reseller-keten.
- Kies welke versie je gebruikt: API Link v2 of Connect Link v1.
- Maak een token aan en gebruik die in je eigen software.
- Test je verbinding via het ping-endpoint.
Vaste adressen
Basis-URL productie
https://api.hertekconnect.nl
Basis-URL acceptance
https://api.acceptance.hertekconnect.nl
Swagger UI productie
https://api.hertekconnect.nl/api-docs/swagger-ui/index.html
Swagger UI acceptance
https://api.acceptance.hertekconnect.nl/api-docs/swagger-ui/index.html
Algemene documentatie v1
https://www.hertekconnect.nl/api
Voorbeelden en SDK v1
https://github.com/hertekconnect/api
Gebruik per omgeving aparte accounts. Tokens en gebruikers in acceptance zijn los van productie. Maak per omgeving een eigen integratiegebruiker aan en genereer daar een eigen token. Test eerst in acceptance en ga daarna pas naar productie.
Toegang regelen
API Link is gekoppeld aan de rol Integrator. Een gebruiker krijgt deze rol op een specifiek niveau in de organisatiestructuur en ziet daarmee alleen de installaties die onder dat niveau vallen.
Op welke niveaus kan de Integrator-rol staan?
Reseller-keten
Geeft toegang tot alle installaties van alle resellers binnen de keten.
Reseller
Geeft toegang tot alle installaties die de reseller onderhoudt.
Portfolio
Geeft toegang tot alle installaties binnen het portfolio van de klant.
Installatie
Geeft toegang tot één specifieke installatie.
De Integrator-rol kan niet worden toegekend op platform- of business-unitniveau. Heb je toegang nodig over meerdere business units, dan zijn dat aparte gebruikers of aparte rolopdrachten.
In de praktijk wordt Integrator vaak gecombineerd met een andere leesrol, zodat je in de portal én via de API kunt werken met dezelfde gebruiker.
Integrator-rol aanvragen
- Bepaal op welk niveau je toegang nodig hebt. Het laagste niveau dat al je werk dekt is de juiste keuze.
- Vraag de beheerder bij de reseller, portfolio of installatie om je Integrator-rol op dat niveau toe te kennen.
- Log in op Hertek Connect met de gebruiker die de rol heeft gekregen.
De optie API token verschijnt vanaf dat moment bij Mijn instellingen.
Gebruik bij voorkeur een aparte serviceaccount. Koppel de Integrator-rol niet aan een persoonlijk account van een medewerker, maar aan een aparte gebruiker die voor de integratie wordt aangemaakt. Dan blijft de koppeling werken als die medewerker wisselt.
API Link v2: token aanmaken en gebruiken
In v2 maak je een persoonlijke API-token aan via de portal. Die token gebruik je vervolgens in elke API-aanvraag.
Token aanmaken
- Log in op Hertek Connect.
- Klik rechtsboven op het menu-icoon.
- Kies Mijn instellingen.
- Scroll naar het blok API token genereren.
- Klik op Token genereren.
- Het dialoog Token opnieuw genereren vraagt om bevestiging.
- Bevestig met Token genereren.
- De nieuwe token verschijnt eenmalig volledig in beeld, samen met de melding Token succesvol aangemaakt.
- Klik op het kopieer-icoon naast de token en sla hem veilig op in je eigen software of in een passwordmanager.
In het blok API token genereren zijn de laatste vier tekens van de huidige token zichtbaar. Daaronder staan de knoppen Token genereren en Token intrekken.
Direct na genereren is de token volledig zichtbaar. Onder het invoerveld staat: Let op: bewaar dit token veilig. Na een refresh is het niet meer volledig zichtbaar.
Ben je de token kwijt? Maak dan een nieuwe aan. Daarmee wordt de oude token meteen ongeldig.
Eén token per gebruiker
Je hebt op elk moment maximaal één geldige token per gebruikersaccount. Een nieuwe token genereren betekent dat de vorige token stopt met werken.
Token gebruiken in je software
Stuur de token in de Authorization-header van elke aanvraag. Het formaat is Bearer gevolgd door een spatie en de token.
Basis-URL
https://api.hertekconnect.nl
Header
Authorization: Bearer
Eerste test
GET https://api.hertekconnect.nl/connect-link/v2/ping
Als de token werkt, geeft dit terug:
{"status": "ok"}
Twee soorten Bearer-tokens in v2
Het beheer van de token zelf, zoals genereren, status opvragen en intrekken, loopt onder de portal-sessie van de gebruiker. Dat doet de portal automatisch.
De API-endpoints zelf, zoals ping en later de lees-endpoints, gebruiken de gegenereerde API-token.
Voor jou als integrator betekent dit: gebruik de token uit Mijn instellingen in je eigen software.
Testen vanuit Swagger UI
Wil je vanuit Swagger UI testen? Klik bovenin op Authorize.
Plak je API-token bij connectLinkBearerToken voor de data-endpoints.
Gebruik je portal JWT uit je browser-cookies van Hertek Connect bij bearerToken voor de token-management-endpoints.
De actuele lijst met endpoints en parameters vind je in Swagger UI. Selecteer daar de groep Connect Link v2.
Token vervangen of intrekken
Bij verlies, vermoeden van misbruik, vertrek van een medewerker of periodieke roulatie wissel je de token. Het intrekken zet de oude token onmiddellijk op verlopen.
- Ga naar Mijn instellingen.
- Scroll naar API token genereren.
- Klik op Token intrekken.
- Bevestig in het dialoog.
Wil je meteen verder werken met een nieuwe token? Klik daarna op Token genereren en doorloop opnieuw de stappen voor het aanmaken van een token.
Alle aanvragen met de oude token mislukken vanaf het moment van intrekken. Pas dus eerst je software aan of plan een kort onderhoudsvenster in.
Connect Link v1: zolang nog ondersteund
Connect Link v1 blijft beschikbaar omdat een aantal endpoints in v2 nog niet is opgeleverd. Dit geldt voor installatielijst, zones, elementen en webhooks.
Nieuwe integraties bouw je waar mogelijk in v2. Gebruik v1 aanvullend voor wat in v2 nog ontbreekt.
Inloggen en token ophalen in v1
v1 werkt met gebruikersnaam en wachtwoord. Je stuurt die naar het auth-endpoint en krijgt een token terug met een geldigheidsdatum.
Basis-URL
https://api.hertekconnect.nl
Endpoint
POST /api/v1/auth/request_token
Body
{"username": "...", "password": "..."}
Response
{"token": "...", "validUntil": "..."}
Gebruik daarna in elke aanvraag:
Authorization: Bearer
v1-tokens hebben een geldigheidsduur. Houd de validUntil-datum in de gaten. Vraag op tijd een nieuwe token aan met dezelfde inloggegevens om uitval te voorkomen.
Bouw in je software een automatische refresh-flow met POST /api/v1/auth/request_token op basis van de validUntil-datum.
Wat kun je opvragen in v1?
GET /api/v1/installations
Geeft de lijst van installaties waar deze gebruiker toegang toe heeft. Geeft per installatie onder andere connectId, naam, adres, gebruiksfunctie, statusCategory, connectionStatus, klant- en service-organisatie.
GET /api/v1/installations/{installationId}/zones
Geeft zones binnen een specifieke installatie, inclusief statusCategory en aantal elementen.
GET /api/v1/installations/{installationId}/zones/{zoneId}/elements
Geeft elementen binnen een zone, inclusief deviceType, status, node, loop, address en analogValue.
GET /api/v1/installations/{installationId}/alerts
Geeft alleen de elementen die op dit moment afwijken van NORMAL. Dit is handig om in één call alle openstaande storingen, uitschakelingen of alarmen op te halen.
GET /api/v1/installations/{installationId}/webhooks
Geeft webhooks die geregistreerd staan voor een installatie.
POST /api/v1/installations/{installationId}/webhooks
Registreert een nieuwe webhook.
GET /api/v1/installations/{installationId}/webhooks/{id}
Geeft het detail van een webhook plus de laatste afleverpogingen.
POST /api/v1/installations/{installationId}/webhooks/{id}/test
Stuurt een test-payload naar de webhook om de configuratie te controleren.
DELETE /api/v1/installations/{installationId}/webhooks/{id}
Verwijdert een webhook.
GET /api/v1/ping
Controleert de verbinding.
De volledige specificatie staat in Swagger UI. Selecteer daar de groep Connect Link v1. Voorbeelden en een SDK staan in github.com/hertekconnect/api.
Webhooks beheren in v1
Een webhook is een URL aan jouw kant die Hertek Connect automatisch aanroept als er iets gebeurt op een installatie, bijvoorbeeld een verbindingswijziging of een statusverandering van een element.
Webhook instellen
- Open aan jouw kant een endpoint dat berichten van Hertek Connect kan ontvangen.
- Zorg dat het endpoint bereikbaar is via HTTPS en een geldig SSL-certificaat heeft.
- Verzin een eigen geheim token. Dit is een willekeurige tekenreeks die jij zelf kiest.
- Registreer de webhook via POST /api/v1/installations/{installationId}/webhooks.
- Gebruik als body: {"endpoint": "", "token": ""}.
- Test de configuratie meteen met POST /api/v1/installations/{installationId}/webhooks/{id}/test.
- Controleer de laatste afleverpogingen via GET /api/v1/installations/{installationId}/webhooks/{id}.
Hertek Connect stuurt jouw geheime token mee bij elke webhook-aanroep, zodat jij aan jouw kant de afkomst kunt verifiëren.
Eigenschappen van webhooks
Protocol
HTTPS met geldig SSL-certificaat is verplicht.
Connect-timeout
Hertek Connect wacht maximaal twee seconden op de eerste respons van jouw endpoint.
Afleverhistorie
De laatste tien afleverpogingen worden bewaard en zijn opvraagbaar via het detail-endpoint van een webhook.
Faalgedrag
Bij herhaalde fouten gaat een circuit-breaker open en ontvangt support een melding.
User-Agent
Inkomende berichten herken je aan de User-Agent Hertek Connect Link.
Geen webhooks in v2
Het concept webhooks is in v2 nog niet beschikbaar. Heb je push-stijl meldingen nodig? Blijf dan op v1 voor het webhook-deel of overleg met je contactpersoon over een tijdslijn.
Je verbinding testen
Zowel v1 als v2 hebben een ping-endpoint waarmee je in een seconde controleert of je token en je netwerkpad werken.
v2
GET https://api.hertekconnect.nl/connect-link/v2/ping
Verwachte respons
{"status": "ok"} met HTTP 200.
v1
GET https://api.hertekconnect.nl/api/v1/ping
Verwachte respons
HTTP 200 met tekst-respons.
Werkt ping wel maar je echte endpoint niet? Dan is je token geldig, maar mist je gebruiker de juiste Integrator-rol op de installatie waar je naartoe wilt. Controleer dat eerst, daarna pas de URL.
Welke versie kies ik?
v2 is de richting van het platform. v1 blijft naast v2 draaien tot alle benodigde endpoints in v2 zijn opgeleverd.
Token-gebaseerde authenticatie zonder wachtwoord in code
Gebruik v2. v2 maakt tokens los van inloggegevens. Dat is veiliger en rouleerbaar.
Een lijst installaties of zones lezen
Gebruik tijdelijk v1. Deze endpoints zijn in v2 nog niet beschikbaar.
Element-statussen lezen
Gebruik tijdelijk v1. Dit komt later naar v2.
Push-stijl meldingen naar een eigen endpoint via webhooks
Gebruik v1. Webhooks zijn in v2 nog niet beschikbaar.
Nieuwe integratie opzetten
Gebruik v2 voor token en ping. Gebruik v1 voor wat in v2 ontbreekt. Deze combinatie is acceptabel zolang v1 nog actief is.
Bestaande v1-integratie
Blijf deze gebruiken. Plan een migratie zodra de v2-endpoints die je nodig hebt beschikbaar zijn.
Foutmeldingen en oplossingen
401 Unauthorized
De token ontbreekt, is onjuist gespeld, ingetrokken of verlopen.
Controleer de Authorization-header, kopieer de token opnieuw of genereer een nieuwe.
403 Forbidden
De token is geldig, maar de gebruiker heeft op de betreffende installatie geen Integrator-rol.
Vraag de beheerder om de Integrator-rol op het juiste niveau toe te kennen of kies een token van een gebruiker die wel toegang heeft.
404 Not Found
De Connect-ID bestaat niet of de installatie valt buiten je rol-scope.
Controleer de Connect-ID in de portal en verifieer dat je gebruiker daar toegang toe heeft.
De optie API token verschijnt niet in Mijn instellingen
De ingelogde gebruiker heeft nog geen Integrator-rol.
Vraag de beheerder om de Integrator-rol op het juiste niveau toe te kennen.
Webhook wordt niet aangeroepen
Bij v1 reageert jouw endpoint niet binnen twee seconden of klopt het SSL-certificaat niet.
Controleer bereikbaarheid en certificaat. Bekijk de laatste afleverpogingen via het detail-endpoint van de webhook.
Webhook is automatisch gestopt
Er zijn te veel opeenvolgende fouten. De circuit-breaker is geopend.
Los het probleem aan jouw kant op, registreer de webhook opnieuw of neem contact op met support.
v1-token verloopt steeds
v1-tokens hebben een geldigheidsduur.
Bouw in je software een automatische refresh-flow met POST /api/v1/auth/request_token op basis van de validUntil-datum.
Belangrijke beperkingen
v2 is nog in opbouw
Vandaag biedt v2 tokenbeheer en ping. Lees-endpoints voor installaties, zones en elementen en functionaliteit voor webhooks komen gefaseerd beschikbaar.
Tot die tijd combineer je v2 met v1 of blijf je bij v1.
Eén token per gebruiker
Een gebruiker heeft op elk moment maximaal één geldige API-token in v2. Een nieuwe token genereren betekent dat de oude token direct stopt.
Werkt een team met meerdere systemen? Gebruik dan meerdere service-accounts met elk hun eigen Integrator-rol.
Geen IP-allowlist
Hertek Connect filtert API-aanvragen niet op IP-adres.
Beveilig je token daarom als een wachtwoord: nooit in versiebeheer, niet in logs en bij voorkeur in een geheimenkluis.
Rate limits
Er staan vandaag geen harde rate limits op API Link.
Zet je een intensief afroep-patroon op, bijvoorbeeld elke seconde een installatielijst? Stem dat dan kort af met support.
Misbruik kan tot intrekking van de token leiden.
Persoonsgegevens
De API-respons bevat installatie- en statusinformatie.
Eindgebruiker- of bewonersgegevens zijn geen onderdeel van API Link.
Veelgestelde vragen
Kan ik nu al volledig op v2 over?
Alleen voor tokenbeheer en ping. Voor het lezen van installaties, zones en elementen en voor webhooks blijf je voorlopig op v1.
Wat is het verschil tussen API Link en push notifications in de portal?
Push notifications zijn voor personen in de portal of PWA. API Link is voor machine-naar-machine integratie met je eigen software. Beide bestaan naast elkaar.
Wat als mijn token uitlekt?
Trek de token direct in via Mijn instellingen. Maak daarna een nieuwe aan en werk je software bij. De oude token is meteen ongeldig.
Werkt de Integrator-rol ook op platformniveau?
Nee. De rol kan alleen worden toegekend op reseller-keten, reseller, portfolio of installatie.
Heb je dekking nodig over een hele business unit? Dan zijn dat meerdere rolopdrachten.
Krijg ik via API Link ook brandmeldingen?
Realtime brandmeldingen lopen via webhooks in v1 of via de portal-meldingen voor gebruikers.
API Link is geen vervanging voor een meldkameraansluiting en geen vervanging voor Connect Evac.
Hoeveel integraties kan ik tegelijk hebben?
Er is één token per gebruiker. Heb je meerdere onafhankelijke systemen? Gebruik dan aparte service-accounts.
Waar vind ik de actuele API-documentatie?
In de Swagger UI op https://api.hertekconnect.nl/api-docs/swagger-ui/index.html. Daar staan v1 en v2 als aparte groepen.
Voor acceptance gebruik je hetzelfde pad onder api.acceptance.hertekconnect.nl.
Voorbeelden en SDK voor v1 staan in github.com/hertekconnect/api.
Mag ik mijn productie-token in testomgevingen gebruiken?
Nee. Tokens zijn omgevingsspecifiek en gekoppeld aan de gebruiker. Gebruik per omgeving een aparte gebruiker en een aparte token.