Documentatie
Een sleutel verkrijgen
- Een beheerder van uw organisatie vraagt hierboven een sleutel aan, met een naam en het beoogde gebruik.
- Atlas beoordeelt elke aanvraag en keurt ze goed of weigert ze, met een motivering. De beslissing verschijnt hier.
- Na goedkeuring toont de aanvrager de sleutel ÉÉN keer en bewaart hem in een geheimenkluis.
- De sleutel is gekoppeld aan uw organisatie ÉN aan het account dat hem aanvroeg: verlaat dat account de organisatie of wordt het geblokkeerd, dan werkt de sleutel niet meer.
Authenticatie
Elk verzoek draagt de sleutel in de Authorization-header: „Authorization: Bearer <uw sleutel>”. Nooit in het adres (URL): een adres belandt in logs, geschiedenissen en proxy’s.
De API is bedoeld voor aanroepen van SERVER NAAR SERVER. Een verzoek met een Origin-header (dus vanuit een browser) wordt geweigerd (403 browser_origin_refused): een sleutel hoort nooit in code die bij uw bezoekers draait.
Een gelekte sleutel trekt u hierboven meteen in; „Vernieuwen” levert een nieuwe en schakelt de oude onmiddellijk uit.
Authorization: Bearer <key>Basisadres
https://api.astro.atlascontrole.be/api/client/v1Alle routes zijn relatief ten opzichte van dit adres, uitsluitend via HTTPS. Antwoorden zijn JSON (UTF-8), datums in ISO 8601.
Routes
| Route | Wat ze teruggeeft | Parameters |
|---|---|---|
GET /me | De gebruikte sleutel, uw organisatie, uw limieten en het verbruik van vandaag. | — |
GET /inspections | Uw keuringen, gesorteerd op oplopende wijzigingsdatum (ideaal om te synchroniseren). | status, from, to, updated_since, limit, cursor |
GET /inspections/{ref} | Eén keuring, via haar referentie. | — |
GET /orders | Uw bestellingen en offertes. | status, limit, cursor |
GET /invoices | Uw facturen, per pagina van 20. Alleen voor sleutels van een beheerder van de organisatie. | status, year, cursor |
GET /sites | Uw panden (adressen) en de installaties die er staan, per pagina van 20. | cursor |
GET /catalog | Wat u kunt bestellen, zoals het klantenportaal het u toont: diensten, opties, uw prijzen. Om de lijnen (lines) van POST /orders samen te stellen. | — |
GET /openapi.json | De OpenAPI-beschrijving van de API. Zonder sleutel. | — |
Rechten van een sleutel
Een sleutel kan altijd lezen. Hij schrijft enkel voor de rechten die bij de aanvraag (of later, met “Rechten wijzigen”) gevraagd EN door Atlas één voor één toegekend zijn. Een sleutel van vóór oktober 2026 blijft alleen-lezen tot een nieuwe goedkeuring. GET /me geeft de rechten van de sleutel (scopes) en die welke nog op goedkeuring door Atlas wachten (pendingScopes).
read- Lezen: keuringen, bestellingen, facturen, panden. Altijd inbegrepen.
documents:write- Documenten (schema’s en plannen) indienen bij een bestelling of keuring.
messages:write- Berichten schrijven bij een bestelling of keuring.
orders:write- Prijs berekenen, bestellen, een offerte aanvragen, een bestelling herroepen, teruggebeld worden.
quotes:sign- Een offerte ondertekenen en bevestigen. Een apart recht, afzonderlijk toegekend door Atlas: het zit niet in orders:write.
appointments:write- Vragen om een geplande keuring te verplaatsen of te annuleren.
complaints:write- Een klacht indienen en erop antwoorden.
payments- De online betaallink van een factuur opvragen — de enige betaalhandeling van de API: geen kaartbetaling, geen betaling van een bestelling.
sites:write- Een pand toevoegen of archiveren.
organization:write- Leden uitnodigen, hun rol wijzigen of verwijderen; over een lidmaatschapsaanvraag beslissen; facturatieadres.
directory:write- Uw klanten- en aannemersfiches beheren.
sharing:write- Toegang van een aannemer tot uw bestellingen geven of intrekken.
Schrijven: de regels
Elke schrijfopdracht is een handeling van het klantenportaal, beoordeeld DOOR het klantenportaal met de rechten van de persoon die de sleutel aanvroeg: dezelfde controles, prijzen, regels voor momenten en e-mails. Wat het klantenportaal die persoon weigert, weigert de API ook, met dezelfde reden (error.code).
Bestanden worden als JSON verstuurd: { "name", "mimeType", "dataBase64" }, maximaal 5 per verzoek, pdf tot 15 MB, afbeelding tot 5 MB, 30 MB in totaal. Het type wordt op de inhoud gecontroleerd: een bestand dat niet is wat het aankondigt, wordt geweigerd (attachment_type).
Een geslaagd verzoek geeft { "data": { … } } (201 bij een aanmaak); data bevat wat het klantenportaal voor die handeling antwoordt.
Schrijfopdrachten hebben hun eigen dagquotum: 600 schrijfopdrachten per sleutel per dag (teruggegeven door GET /me), bovenop de algemene limieten.
Voorlopig niet via de API: het delen van de link van een verslag, het indienen van foto’s van herstellingen, het groepsgewijs ondertekenen van offertes en de export van uw persoonsgegevens (AVG). Doe dat in het klantenportaal.
Het herroepen van een bestelling volgt precies de regel van het klantenportaal: de API laat het toe wanneer het klantenportaal het toelaat.
| Route | Wat ze doet | Recht |
|---|---|---|
POST /orders/{id}/documents | Schema’s en plannen indienen bij een bestelling (annexDocType: unifilaire, position of other; taskRefs voor bepaalde keuringen). | documents:write |
POST /inspections/{ref}/documents | Schema’s en plannen indienen bij een keuring. | documents:write |
POST /orders/{id}/messages | Een bericht schrijven bij een bestelling (foto’s en pdf toegelaten). | messages:write |
POST /inspections/{ref}/messages | Een bericht schrijven bij een keuring. | messages:write |
POST /orders/{id}/complaints | Een klacht indienen over een bestelling (dossier PL-…, ontvangstbevestiging per e-mail). | complaints:write |
POST /inspections/{ref}/complaints | Een klacht indienen over een keuring. | complaints:write |
POST /complaints/{reference}/messages | Antwoorden in een klachtendossier. | complaints:write |
POST /orders/pricing | Een winkelmand berekenen, zoals het klantenportaal (schrijft niets). | orders:write |
POST /orders/slots | Keuringsmomenten voorstellen (schrijft niets): een slotToken voor POST /orders. | orders:write |
POST /orders | Bestellen: dezelfde prijzen, momenten en bevestiging per e-mail als het klantenportaal. | orders:write |
POST /quotes | Een offerte aanvragen (Atlas berekent ze; er wordt niets besteld). | orders:write |
POST /quotes/{reference}/cancel | Een offerteaanvraag annuleren. | orders:write |
POST /orders/{id}/sign | Een offerte ondertekenen en bevestigen. | quotes:sign |
POST /orders/{id}/withdrawal | Een bestelling herroepen, wanneer het klantenportaal dat toelaat. | orders:write |
POST /requests | Vragen om teruggebeld te worden voor een dienst. | orders:write |
POST /inspections/{ref}/visit-change | Vragen om een keuring te verplaatsen (reschedule) of te annuleren (cancel). | appointments:write |
POST /invoices/{id}/payment-link | De online betaallink van een factuur (beheerders). | payments |
POST /sites | Een pand toevoegen (adres gecontroleerd bij bpost). | sites:write |
POST /sites/archive | Een pand zonder geschiedenis archiveren. | sites:write |
POST /organization/invitations | Iemand uitnodigen (die de uitnodiging per e-mail ontvangt). | organization:write |
POST /organization/invitations/revoke | Een openstaande uitnodiging intrekken. | organization:write |
POST /organization/members/role | De rol van een lid wijzigen. | organization:write |
POST /organization/members/remove | Een lid verwijderen. | organization:write |
POST /organization/join-requests/decide | Een lidmaatschapsaanvraag aanvaarden of weigeren. | organization:write |
POST /organization/billing | E-mailadres voor facturen. | organization:write |
POST /clients, /clients/update, /clients/archive | Uw klantenfiches. | directory:write |
POST /contractors, /contractors/update, /contractors/archive, /contractors/merge | Uw aannemersfiches. | directory:write |
POST /contractor-links, /contractor-links/{id}/revoke, /contractor-links/{id}/grants/{grantId}/revoke | Toegang van een aannemer tot uw bestellingen geven of intrekken. | sharing:write |
Idempotency-Key: nooit twee keer dezelfde handeling
Elke schrijfopdracht draagt een unieke Idempotency-Key-header (8 tot 255 tekens, bijvoorbeeld een UUID). Zonder: 400 idempotency_key_required.
Gaat het antwoord verloren (onderbreking, time-out), stuur dan HETZELFDE verzoek met DEZELFDE sleutel: de API speelt het eerste antwoord opnieuw af (header Idempotent-Replayed: true) in plaats van de handeling te herhalen — een bestelling wordt nooit twee keer geplaatst. De sleutel wordt 24 uur bewaard.
Dezelfde sleutel voor een ander verzoek wordt geweigerd (422 idempotency_key_reused). Na een 429 of een 5xx-fout wordt niets bewaard: probeer opnieuw met dezelfde sleutel.
POST /orders/pricing en POST /orders/slots schrijven niets en vragen er geen.
Een keuring, veld per veld
ref, state, completion (status: done / cancelled / not-done; doneIn), scheduledStart, scheduledEnd, type en subtype (fr / nl), title, address (fr / nl), inspectorName, order (id, reference, clientReference, paymentStatus), report (status, conclusion, issuedConclusion, held, pdf fr / nl, portalUrl), nextDueDate, updatedAt. report.status is platform, held, awaiting-payment, pending, unavailable, unverified of null; de links in report.pdf zijn ondertekend en openen zonder sleutel.
Een pand: key, address en installations (id, reference, type fr / nl, lastInspectionRef, lastInspectionAt, nextDueDate, conclusion).
Voorbeelden
De sleutel controleren en uw limieten lezen:
curl -sS --compressed \
-H "Authorization: Bearer $ATLAS_API_KEY" \
https://api.astro.atlascontrole.be/api/client/v1/meDe afgewerkte keuringen sinds 1 oktober lezen, per pagina van 100:
curl -sS --compressed \
-H "Authorization: Bearer $ATLAS_API_KEY" \
"https://api.astro.atlascontrole.be/api/client/v1/inspections?status=done&from=2026-10-01&limit=100"Volgende pagina: hetzelfde verzoek opnieuw, met de cursor uit het vorige antwoord.
curl -sS --compressed \
-H "Authorization: Bearer $ATLAS_API_KEY" \
"https://api.astro.atlascontrole.be/api/client/v1/inspections?status=done&from=2026-10-01&limit=100&cursor=<nextCursor>"Bestellen (een moment voorgesteld door POST /orders/slots):
curl -sS --compressed -X POST \
-H "Authorization: Bearer $ATLAS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"lines":[{"service":"<service>","qty":1}],"address":{"street":"Rue de la Loi 16","zip":"1000","city":"Bruxelles"},"phone":"+32 2 000 00 00","slotToken":"<slotToken>"}' \
https://api.astro.atlascontrole.be/api/client/v1/ordersEen eendraadsschema indienen bij een keuring:
{
"annexDocType": "unifilaire",
"attachments": [
{ "name": "unifilaire.pdf", "mimeType": "application/pdf", "dataBase64": "JVBERi0xLjcK…" }
]
}curl -sS --compressed -X POST \
-H "Authorization: Bearer $ATLAS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @document.json \
https://api.astro.atlascontrole.be/api/client/v1/inspections/DOM-2026-ABC123/documentsPaginering met een cursor
Lijsten geven { "data": [...], "nextCursor": "…" } terug. Zolang nextCursor niet null is, geeft u hem ongewijzigd door in de parameter cursor voor de volgende pagina.
De cursor is ondoorzichtig: niet ontcijferen, niet zelf samenstellen. limit loopt van 1 tot 100 (standaard 50) en geldt alleen voor /inspections en /orders: /invoices en /sites geven vaste pagina’s van 20.
Voor een incrementele synchronisatie bewaart u de recentste ontvangen updatedAt en vertrekt u de volgende keer van updated_since=<die datum>. De filter werkt op de wijzigingsdatum van het record; sommige wijzigingen op de achtergrond verschuiven die niet: voorzie daarom ook een periodieke volledige hersynchronisatie (bijvoorbeeld wekelijks).
{
"data": [ { "ref": "…", "state": "done", "updatedAt": "2026-10-02T09:14:00.000Z", … } ],
"nextCursor": "eyJ1IjoiMjAyNi0xMC0wMlQwOToxNDowMC4wMDBaIn0"
}Filters
- Keuringen — status: todo, in_progress, ready, done, cancelled; from en to: geplande datum, formaat JJJJ-MM-DD; updated_since: ISO 8601-datum.
- Bestellingen — status: quotation, order, cancelled.
- Facturen — status: paid, unpaid; year: JJJJ.
- Een onbekende of verkeerd gevormde parameter geeft 400 invalid_parameter, met de naam van de parameter in het bericht.
Cache: ETag en If-None-Match
Elk antwoord draagt een ETag-header. Stuur hem terug in If-None-Match bij de volgende aanroep: is er niets veranderd, dan antwoordt de API 304 Not Modified, zonder inhoud.
De antwoorden van /orders, /invoices en /sites worden tot 60 seconden per sleutel gecachet: een wijziging kan een minuut nodig hebben om te verschijnen.
Vraag compressie aan (Accept-Encoding: gzip, br): de antwoorden worden onderweg gecomprimeerd.
curl -sS -i --compressed \
-H "Authorization: Bearer $ATLAS_API_KEY" \
-H 'If-None-Match: "<ETag>"' \
https://api.astro.atlascontrole.be/api/client/v1/sitesSnelheidslimieten en quotum
Elke sleutel heeft een limiet per minuut en een quotum per dag (standaard 60 verzoeken per minuut en 10 000 per dag; uw exacte waarden staan hierboven en worden teruggegeven door GET /me).
Daarboven antwoordt de API 429 (rate_limited per minuut, quota_exceeded per dag) met een Retry-After-header in seconden: wacht die tijd af voordat u het opnieuw probeert.
Schrijfopdrachten: een apart dagquotum (standaard 600 per sleutel), bovenop deze limieten; daarboven 429 write_quota_exceeded.
X-RateLimit-Limit- Toegelaten verzoeken per minuut.
X-RateLimit-Remaining- Resterende verzoeken in de lopende minuut.
X-RateLimit-Reset- Seconden tot het einde van het venster van één minuut.
X-RateLimit-Limit-Day- Toegelaten verzoeken per dag.
X-RateLimit-Remaining-Day- Resterende verzoeken vandaag.
X-RateLimit-Remaining-Write-Day- Resterende schrijfopdrachten vandaag.
Fouten
Een fout heeft altijd dezelfde vorm: { "error": { "code": "…", "message": "…" } }. De code is stabiel; het bericht is voor mensen bedoeld en kan wijzigen.
{ "error": { "code": "rate_limited", "message": "…" } }| Status | Code | Betekenis |
|---|---|---|
| 400 | invalid_parameter | Onbekende of verkeerd gevormde parameter. |
| 401 | unauthorized | Sleutel ontbreekt of is onbekend. |
| 401 | key_revoked | Sleutel ingetrokken. |
| 401 | key_expired | Sleutel vervallen. |
| 401 | key_not_active | Sleutel nog niet actief (in behandeling, of nog niet getoond). |
| 403 | forbidden | Geen toegang tot deze bron. |
| 403 | browser_origin_refused | Aanroep vanuit een browser (Origin-header). |
| 403 | invoices_forbidden | De houder van de sleutel is geen beheerder van de organisatie meer. |
| 404 | not_found | Bron bestaat niet, of valt buiten uw organisatie. |
| 429 | rate_limited | Limiet per minuut bereikt (zie Retry-After). |
| 429 | quota_exceeded | Dagquotum bereikt (zie Retry-After). |
| 400 | invalid_body | Ontbrekende of verkeerd gevormde inhoud van het verzoek. |
| 400 | idempotency_key_required | Schrijfopdracht zonder Idempotency-Key-header. |
| 400 | invalid_idempotency_key | Verkeerd gevormde Idempotency-Key (8 tot 255 tekens). |
| 403 | insufficient_scope | De sleutel heeft het nodige recht niet gekregen (zie error.details.required). |
| 409 | idempotency_in_progress | Een verzoek met deze Idempotency-Key loopt nog: probeer het over enkele seconden opnieuw. |
| 413 | payload_too_large | Verzoek te groot. |
| 422 | idempotency_key_reused | Deze Idempotency-Key werd al gebruikt voor een ander verzoek. |
| 429 | write_quota_exceeded | Dagquotum voor schrijfopdrachten bereikt (zie Retry-After). |
| 500 | internal_error | Onverwachte fout aan onze kant: probeer later opnieuw. |
| 502 | upstream_unavailable | Gegevensbron tijdelijk onbereikbaar: probeer later opnieuw. |
| 503 | disabled | API tijdelijk uitgeschakeld. |
OpenAPI-beschrijving
De volledige beschrijving (schema’s, parameters, antwoorden) is gepubliceerd in OpenAPI 3, leesbaar voor de meeste tools (Postman, Insomnia, clientgeneratoren):
Versiegeschiedenis
- v1 — 2026-10
- Eerste versie, alleen-lezen.
- v1.1 — 2026-10
- Schrijven: handelingen van het klantenportaal per toegekend recht, Idempotency-Key, quotum voor schrijfopdrachten.