Stap 1
De rol van een CBI
Goed dat je aansluit op het Digitaal Logboek. Voordat je begint met techniek, eerst kort wat een Conformiteits Beoordelende Instantie wel en niet doet in het logboek. Zo weet je precies welke calls voor jou bedoeld zijn.
Als keurende instantie voeg je keuringslogs toe aan installaties die al bestaan. Je maakt zelf geen installaties aan en je past bestaande installatiegegevens niet aan. De officiële afbakening staat in de rollen-documentatie.
Dit doe je wel
- Keuringslog van type ingebruikname-keuring
- Keuringslog van type modificatie-keuring
- Keuringslog van type periodieke keuring
- Per log aangeven of het resultaat goedgekeurd of afgekeurd is, met een omschrijving
Dit doe je niet
- Installaties aanmaken, dat doet de fabrikant of onderhoudspartij
- Installatiegegevens wijzigen zoals adres, identificatie of techniek
- Onderhouds-, reparatie- of storingslogs plaatsen
Stap 2
Vraag een API-key aan
API-keys worden uitgegeven door SBCL via het registratie-portaal. Vraag voor elke omgeving een aparte key aan: een voor testen, een voor productie.
Aanvragen doe je via logboek.sbcl.nl/register. De rate-limit wordt per key ingesteld bij activatie.
Test-key en productie-key zijn gescheiden. Een test-key werkt alleen tegen logboek-api-test.sbcl.nl, een productie-key alleen tegen logboek-api.sbcl.nl. De overgang van test naar productie is een wijziging van base URL plus key, geen wijziging in je code.
Stap 3
Test je authenticatie
De API verwacht je key in de HTTP-header apikey. Een goede eerste test is het
ophalen van de fabrikantenlijst: dat is een GET zonder verdere parameters, die alleen een
geldige key nodig heeft.
GET met je key
curl -i https://logboek-api-test.sbcl.nl/api/v2/manufacturers \
-H "apikey: JOUW_API_KEY"Vul je test-key in de balk bovenaan in en klik op Probeer live. De call gaat rechtstreeks vanuit je browser naar de testomgeving, je key gaat alleen mee in de header.
Wat je terugkrijgt. Een geldige key geeft 200 met de fabrikantenlijst. Ontbreekt de key, dan volgt 422. Is de key onjuist of niet actief, dan volgt 401.
Stap 4
Zoek een installatie op
Voordat je een keuringslog plaatst, heb je het SBCL-ID van de installatie nodig. Een SBCL-ID
heeft altijd de vorm SBCL-<korte UUID>. Er zijn twee manieren om een installatie te vinden.
Klik een installatie aan op de kaart of in de lijst. Het SBCL-ID wordt automatisch ingevuld in stap 4 en stap 5.
Let op: dit zijn fictieve testinstallaties op de testomgeving. Het zijn geen echte installaties.
Ken je het SBCL-ID al, dan is dit de schoonste route. Een directe lookup levert de installatiegegevens.
Ken je het SBCL-ID nog niet, zoek dan op het installatie-ID of custom-ID van de fabrikant in combinatie met de postcode. Het fabrikant-ID is optioneel en maakt de zoekopdracht preciezer. Deze route geeft je het SBCL-ID terug.
Bewaar het SBCL-ID. Sla het SBCL-ID op in je eigen systeem als unieke sleutel zodra je het hebt opgehaald. Daarna is alleen nog een directe lookup nodig en hoef je niet opnieuw te zoeken.
Stap 5 · Kern voor CBI's
Plaats een keuringslog
Dit is de schrijfactie die een CBI uitvoert. Je plaatst een keuringslog op een installatie via het SBCL-ID. Drie velden zijn verplicht: het type keuring, het tijdstip en een omschrijving.
Request preview
{}LET OP! Deze knop voert een echte schrijfactie uit op de testomgeving. Er wordt daadwerkelijk een log aangemaakt. Gebruik in deze pagina nooit een productie-key.
Stap 6
Foutafhandeling en response codes
De volledige lijst staat op response-codes. Hieronder de codes die je bij een CBI-integratie het meest tegenkomt.
| Code | Betekenis | Actie |
|---|---|---|
200 | OK | Lees de response, sla het SBCL-ID op. |
201 | Created | Log is aangemaakt. Bewaar het log-ID uit de response. |
400 | Bad Request | Validatiefout. Bekijk het error-veld in de response. |
401 | Unauthorized | Key is onjuist of niet actief. Controleer de balk bovenaan. |
403 | Forbidden | Je key heeft niet de juiste rol voor deze actie. |
404 | Not Found | Installatie of log niet gevonden. Controleer het SBCL-ID. |
422 | Unprocessable Entity | Verplichte parameter ontbreekt. Vul aan en probeer opnieuw. |
429 | Too Many Requests | Rate-limit bereikt. Wacht en probeer daarna opnieuw. |
500 | Server Error | Fout aan serverzijde. Probeer later opnieuw, meld het bij aanhouden. |
Voorkom dubbele logs. Geef elke keuringslog een eigen referenceId. Loopt een verzoek op een time-out, controleer dan eerst met een GET of de log al bestaat voordat je opnieuw verstuurt. Zo voorkom je dat dezelfde keuring tweemaal in het logboek belandt.
Stap 7
Naar productie
De overgang van test naar productie vraagt geen wijziging in je code, alleen een andere base URL en een productie-key.
- Productie-key aanvragen via logboek.sbcl.nl/register
- Base URL omzetten naar
https://logboek-api.sbcl.nl/api/v2 - Monitoring inrichten op response-codes 4xx en 5xx
- Vastleggen wie binnen je organisatie de API-key beheert en wanneer je een nieuwe key aanvraagt
- Uitgaande verzoeken en de teruggekregen log-ID's vastleggen in je eigen systeem
- Contactpersoon bij SBCL bekend maken bij je IT-team