Met API Link koppel je je eigen software aan Hertek Connect en lees je installatie- en statusinformatie uit. Er zijn twee versies: v2 (de standaard) en v1 (legacy).
Let op: API v1 wordt per 31 maart 2027 uitgefaseerd. Hoe je v1 en v2 tijdens de migratieperiode combineert en overstapt naar v2 lees je in het migratie-artikel.
Twee platformen, twee logins: v1 hoort bij je bestaande Connect Beheren-account, v2 bij je account op het nieuwe platform, app.hertekconnect.nl. Inloggen op het nieuwe platform kan pas nadat je onderhoudsorganisatie is gemigreerd en je een uitnodiging hebt ontvangen. Is je onderhoudsorganisatie nog niet gemigreerd, dan gebruik je je Connect Beheren-login en v1; er is dan nog niets te doen op het nieuwe platform. Voorbereiden kan wel: controleer je integratie alvast tegen de v2-specificatie in Swagger om de impact van de overstap te bepalen.
Basis-URL productie: https://api.hertekconnect.nl. Acceptance: https://api.acceptance.hertekconnect.nl.
Nieuwe integratie?
Bouw volledig op v2. Alle endpoints zijn in v2 beschikbaar en v1 wordt per 31 maart 2027 uitgefaseerd. v1 is alleen nog nodig als je installaties bedient onder onderhoudsorganisaties die nog niet naar het nieuwe Hertek Connect zijn gemigreerd; zie het migratie-artikel.
De volledige specificatie (endpoints, schema's, voorbeelden) staat in de Swagger UI:
Voor acceptance: hetzelfde pad onder api.acceptance.hertekconnect.nl. Een uitgebreide toelichting en voorbeelden vind je in de wiki op GitHub.
Toegang
API Link is gekoppeld aan de rol Integrator. Je ziet alleen de installaties die onder je toewijzing vallen.
- v2: je wordt toegewezen op reseller-keten-, reseller-, portfolio- of installatieniveau.
- v1: de integrator wordt toegevoegd op een installatie of klantorganisatie.
Gebruik een apart serviceaccount per integratie en per omgeving (acceptance en productie zijn gescheiden), niet het persoonlijke account van een medewerker.
Authenticatie v2
v2 hoort bij je account op het nieuwe platform: app.hertekconnect.nl. Maak je API-token aan via Mijn instellingen in de portal (zichtbaar zodra je account de Integrator-rol heeft). De token wordt eenmalig volledig getoond; kopieer hem meteen en bewaar hem als een wachtwoord. Eén actieve token per account; meerdere systemen betekent meerdere serviceaccounts.
Opnieuw genereren of intrekken doe je op dezelfde pagina en gaat direct in. Token uitgelekt? Direct intrekken en een nieuwe aanmaken.
Stuur bij elke call: Authorization: Bearer <token>
Authenticatie v1
v1 hoort bij je Connect Beheren-account (het legacy platform). Vraag een token aan via POST /api/v1/auth/request_token met de gebruikersnaam en het wachtwoord van dat account. De token verloopt; bouw een refresh op basis van de validUntil in de response.
Verbinding testen
v2: GET /connect-link/v2/ping
v1: GET /api/v1/ping
Werkt ping wel maar een data-endpoint niet? Dan is je token geldig maar mist je toewijzing op die installatie.
Webhooks
Webhooks zijn beschikbaar in v1 en v2; de endpoints staan in Swagger. Geef bij registratie je eigen geheime token mee; Hertek Connect stuurt dit bij elke aanroep mee, zodat je de afkomst kunt verifiëren. Je endpoint moet via HTTPS bereikbaar zijn en binnen twee seconden reageren; bij herhaalde fouten stopt de aflevering automatisch. Registreer je v1-webhooks uiterlijk 31 maart 2027 opnieuw op v2.
Foutcodes
-
401: token ontbreekt, is ongeldig of ingetrokken. -
403: geen Integrator-rol, of Connect Link niet actief op een installatie binnen je toewijzing -
404: installatie bestaat niet of valt buiten je toewijzing.
Zie je de optie API token niet in Mijn instellingen? Dan heeft je account nog geen Integrator-rol.