Naar de inhoud
Beveiliging X

Voor ontwikkelaars

Open API en webhooks

Elk ander systeem, of het nu HR, salaris, toegangscontrole of een eigen dashboard is, leest de planning en operatie van Beveiliging X en plant diensten langs dezelfde planregels als het planbord. Webhooks melden wat er gebeurt, ondertekend en met herkansing. Alles staat hieronder, met de volledige specificatie als OpenAPI 3.1.

Aansluiten Download de specificatie

Aansluiten en aanmelden

Het adres van de API is https://api.beveiligingx.nl/api/v1/beveiliging. Elk verzoek draagt een toegangssleutel in de kop Authorization: Bearer. Een sleutel maakt de eigenaar of directie in de backoffice onder Integraties en keten, API en webhooks. Het geheim staat een keer in beeld; Beveiliging X bewaart alleen de hash.

De sleutel bepaalt de organisatie: u geeft nooit zelf een organisatie mee. Hij werkt namens de kantoorgebruiker die hem uitgaf en kan nooit meer dan die. Verliest die gebruiker een recht of gaat hij uit dienst, dan verliest de sleutel het ook. Intrekken werkt meteen.

curl -s "https://api.beveiligingx.nl/api/v1/beveiliging/diensten?van=2026-06-01&tot=2026-06-07" \
  -H "Authorization: Bearer tlk_uw_sleutel" \
  -H "Accept: application/json"

Elk antwoord draagt X-BeveiligingX-Api-Versie: v1. Per sleutel gaan er 120 verzoeken per minuut door; daarboven volgt 429 met Retry-After. Tijden zijn ISO 8601 met de verschuiving, datums JJJJ-MM-DD in de tijdzone van de organisatie.

Wat er nooit naar buiten gaat: een BSN, IBAN, adres, geboortedatum of document van een beveiliger, iets uit de sleutelkluis van een object, de handtekening bij het afmelden en de plek waar iemand zich aan- of afmeldde. Een foto bij een bevinding komt alleen via een getekende link van vijf minuten, met een eigen scope.

Scopes

Een sleutel krijgt een of meer scopes. Lezen zit er altijd in. Wie een sleutel uitgeeft, kan geen scope geven waarvan hij zelf het recht in de backoffice mist.

ScopeNaamWat
beveiliging.lezenPlanning en operatie lezenOpdrachtgevers, objecten met normen, teams, beveiligers, diensten, verlof, beschikbaarheid, bevindingen zonder foto en rondes.
beveiliging.planning.schrijvenPlanning schrijvenConceptdiensten maken, wijzigen en laten vervallen, beveiligers toewijzen en beschikbaarheid zetten. Alles langs de planregels.
beveiliging.verlof.schrijvenVerlof aanvragenEen verlofaanvraag indienen namens een beveiliger; beoordelen doet kantoor.
beveiliging.uren.lezenUren en toeslagen lezenGewerkte diensten met minuten, meerwerk en de regels uit de loonspecificatie.
beveiliging.dossier.lezenKwalificaties lezenDe kwalificaties van beveiligers met hun vervaldatum. Nooit een BSN, IBAN of document.
beveiliging.bevindingen.fotoFoto bij een bevindingEen getekende link van vijf minuten naar de foto bij een bevinding.

Bladeren, synchroniseren en formaten

Een lijst geeft standaard 100 rijen (per_pagina tot 500). De volgende pagina staat in links.volgende; neem die letterlijk over. De cursor is de plek van de laatste rij, dus een rij die er tussendoor bijkomt verschuift niets. Is links.volgende leeg, dan bent u klaar.

Voor een incrementele synchronisatie geeft u gewijzigd_sinds mee (ISO 8601). De volgorde is dan gewijzigd_op en id, en elke rij die op of na dat moment wijzigde telt mee. Bewaar de hoogste gewijzigd_op die u zag en geef die de volgende keer mee: u mist niets en krijgt hooguit een rij twee keer, die u op id herkent.

{
    "data": [
        "..."
    ],
    "links": {
        "self": "https://api.beveiligingx.nl/api/v1/beveiliging/diensten?gewijzigd_sinds=2026-06-01T00:00:00%2B02:00",
        "volgende": "https://api.beveiligingx.nl/api/v1/beveiliging/diensten?gewijzigd_sinds=2026-06-01T00:00:00%2B02:00&cursor=WyIyMDI2LTA2LTAxIDA4OjEyOjAwIiwiNDEiXQ"
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 100,
        "volgende_cursor": "WyIyMDI2LTA2LTAxIDA4OjEyOjAwIiwiNDEiXQ"
    }
}

Filters per lijst staan bij de routes: van en tot, object, team, beveiliger, status en meer.

CSV en XML

Diensten, uren en verlof zijn er ook als CSV (komma, kopregel, UTF-8) en XML: ?formaat=csv of ?formaat=xml, of de kop Accept: text/csv of Accept: application/xml. Een pagina mag dan tot 5000 rijen hebben; de volgende staat in de kop Link (rel="next") en in X-Volgende-Cursor. Een cel die met =, +, - of @ begint en geen getal is, krijgt een apostrof ervoor, zodat een rekenblad hem niet als formule leest.

curl -s "https://api.beveiligingx.nl/api/v1/beveiliging/uren?van=2026-06-01&tot=2026-06-30&formaat=csv" \
  -H "Authorization: Bearer tlk_uw_sleutel" -o uren-juni.csv

Fouten

Elke weigering heeft dezelfde vorm: message is de zin voor een mens, fout.code de vaste code voor uw programma. Bij validatie staan de zinnen per veld in fout.velden, bij de planregels de bevindingen in fout.bevindingen.

{
    "message": "Kies een dienstsoort.",
    "fout": {
        "code": "validatie",
        "status": 422,
        "velden": {
            "dienstsoort": [
                "Kies een dienstsoort."
            ]
        }
    }
}
StatusCodeWanneer
400cursor_ongeldig, idempotentie_sleutel_ongeldigDe cursor of Idempotency-Key klopt niet.
401niet_aangemeldGeen sleutel, of een onbekende of ingetrokken sleutel.
402organisatie_geschorstDe organisatie is geschorst of haar abonnement is niet actief.
403scope_ontbreekt, module_uit, namens_inactief, recht_ingetrokken, link_ongeldigDe sleutel mag dit niet (meer).
404niet_gevonden, geen_fotoBestaat niet, of hoort bij een andere organisatie.
406formaat_niet_beschikbaarDit formaat is er niet voor deze lijst.
409geen_concept, niet_planbaar, periode_vast, verzoek_looptDe toestand laat het niet toe.
422validatie, planregels_blokkade, planregels_waarschuwing, idempotentie_conflictHet verzoek klopt niet of de planregels weigeren.
429te_veel_verzoekenTe veel verzoeken; wacht Retry-After seconden.
5xxserverfoutAan onze kant ging iets mis; probeer het later opnieuw.

Schrijven langs de planregels

Een dienst neerzetten, wijzigen, laten vervallen, een beveiliger toewijzen of vrijgeven, verlof aanvragen en beschikbaarheid zetten: het loopt door dezelfde diensten als het planbord en de app. De regelmotor oordeelt over elke toewijzing: rusttijden, arbeidstijden, WPBR-kwalificaties, overlap, beschikbaarheid, het contract van het object en de objectinstructie.

  • Een blokkade (wet, cao of Wpbr) weigert altijd met 422 planregels_blokkade, ook met force.
  • Een waarschuwing weigert met 422 planregels_waarschuwing tot u "force": true meestuurt. Dan gaat het door en staan de waarschuwingen in het antwoord en op het planbord.
  • Wijzigen en laten vervallen kan alleen bij een conceptdienst; toewijzen ook bij een gepubliceerde dienst. Een vastgezette periode is 409 periode_vast.
  • Geef elk schrijfverzoek een eigen Idempotency-Key. Komt hetzelfde verzoek nog eens (een time-out, een herstart), dan krijgt u het eerste antwoord terug met Idempotent-Replayed: true en gebeurt er niets dubbel. 24 uur geldig.
curl -s -X POST "https://api.beveiligingx.nl/api/v1/beveiliging/diensten" \
  -H "Authorization: Bearer tlk_uw_sleutel" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rooster-2026-06-01-dco-dag-1" \
  -d '{"object_id": 12, "dienstsoort": "dag", "datum": "2026-06-01", "beveiliger_id": 31}'
{
    "message": "Overlapt met de dagdienst op Distributiecentrum Oost.",
    "fout": {
        "code": "planregels_blokkade",
        "status": 422,
        "bevindingen": [
            {
                "regel": "beveiliging.overlap",
                "ernst": "blok",
                "melding": "Overlapt met de dagdienst op Distributiecentrum Oost.",
                "gegevens": {
                    "shift_id": 40
                }
            }
        ]
    }
}

Routes

Alle paden zijn ten opzichte van https://api.beveiligingx.nl/api/v1/beveiliging. De volledige schema's staan in de specificatie.

Stamgegevens

Opdrachtgevers, objecten met coördinaten en normen, teams en beveiligers.

GET /opdrachtgevers

Opdrachtgevers

Scope beveiliging.lezen

ParameterWaarBetekenis
actiefqueryAlleen actieve (true) of inactieve (false). Verwijderde staan erin met verwijderd_op.

Antwoord

{
    "data": [
        {
            "id": 7,
            "naam": "Havenbedrijf Zuid",
            "soort": "direct",
            "contactpersoon": "A. de Vries",
            "email": "beveiliging@havenzuid.example",
            "actief": true,
            "factuuradres": {
                "adres": "Kade 12",
                "postcode": "3011 AA",
                "plaats": "Rotterdam"
            },
            "btw_nummer": "NL000000000B01",
            "betaaltermijn_dagen": 30,
            "aangemaakt_op": "2026-01-05T09:12:00+01:00",
            "gewijzigd_op": "2026-05-30T14:02:11+02:00",
            "verwijderd_op": null
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

GET /opdrachtgevers/{id}

Een opdrachtgever

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 7,
        "naam": "Havenbedrijf Zuid",
        "soort": "direct",
        "contactpersoon": "A. de Vries",
        "email": "beveiliging@havenzuid.example",
        "actief": true,
        "factuuradres": {
            "adres": "Kade 12",
            "postcode": "3011 AA",
            "plaats": "Rotterdam"
        },
        "btw_nummer": "NL000000000B01",
        "betaaltermijn_dagen": 30,
        "aangemaakt_op": "2026-01-05T09:12:00+01:00",
        "gewijzigd_op": "2026-05-30T14:02:11+02:00",
        "verwijderd_op": null
    }
}

GET /objecten

Objecten met coördinaten, bezettingsnormen en teams

Scope beveiliging.lezen

ParameterWaarBetekenis
actiefquerytrue is open, false is gesloten.
opdrachtgeverqueryHet id van de opdrachtgever.
teamqueryObjecten die dit team vandaag draait.

Antwoord

{
    "data": [
        {
            "id": 12,
            "naam": "Distributiecentrum Oost",
            "adres": "Logistiekweg 4, Utrecht",
            "opdrachtgever_id": 7,
            "opdrachtgever_label": null,
            "coordinaten": {
                "lat": 52.0907,
                "lng": 5.1214
            },
            "geofence_meters": 150,
            "rondes_per_dienst": 2,
            "actief": true,
            "gesloten_op": null,
            "normen": [
                {
                    "id": 3,
                    "weekdag": null,
                    "dienstsoort": "dag",
                    "minimum": 2,
                    "gewenst": null,
                    "ernst": "waarschuwing",
                    "alleen_toegestaan": false,
                    "geldig_van": "2026-01-01",
                    "geldig_tot": null
                }
            ],
            "teams": [
                {
                    "team_id": 4,
                    "van": "2026-01-01",
                    "tot": null
                }
            ],
            "aangemaakt_op": "2026-01-05T09:20:00+01:00",
            "gewijzigd_op": "2026-03-02T11:00:00+01:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

GET /objecten/{id}

Een object

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 12,
        "naam": "Distributiecentrum Oost",
        "adres": "Logistiekweg 4, Utrecht",
        "opdrachtgever_id": 7,
        "opdrachtgever_label": null,
        "coordinaten": {
            "lat": 52.0907,
            "lng": 5.1214
        },
        "geofence_meters": 150,
        "rondes_per_dienst": 2,
        "actief": true,
        "gesloten_op": null,
        "normen": [
            {
                "id": 3,
                "weekdag": null,
                "dienstsoort": "dag",
                "minimum": 2,
                "gewenst": null,
                "ernst": "waarschuwing",
                "alleen_toegestaan": false,
                "geldig_van": "2026-01-01",
                "geldig_tot": null
            }
        ],
        "teams": [
            {
                "team_id": 4,
                "van": "2026-01-01",
                "tot": null
            }
        ],
        "aangemaakt_op": "2026-01-05T09:20:00+01:00",
        "gewijzigd_op": "2026-03-02T11:00:00+01:00"
    }
}

GET /teams

Teams met leden en objecten

Scope beveiliging.lezen

ParameterWaarBetekenis
actiefqueryAlleen actieve of inactieve teams.

Antwoord

{
    "data": [
        {
            "id": 4,
            "naam": "Ploeg Noord",
            "soort": "ploeg",
            "actief": true,
            "planningscyclus": "weeks",
            "cyclus_weken": 4,
            "leden": [
                {
                    "beveiliger_id": 31,
                    "rol": "lid",
                    "van": "2026-01-01",
                    "tot": null
                }
            ],
            "objecten": [
                {
                    "object_id": 12,
                    "van": "2026-01-01",
                    "tot": null
                }
            ],
            "aangemaakt_op": "2026-01-02T08:00:00+01:00",
            "gewijzigd_op": "2026-04-14T10:30:00+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

GET /teams/{id}

Een team

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 4,
        "naam": "Ploeg Noord",
        "soort": "ploeg",
        "actief": true,
        "planningscyclus": "weeks",
        "cyclus_weken": 4,
        "leden": [
            {
                "beveiliger_id": 31,
                "rol": "lid",
                "van": "2026-01-01",
                "tot": null
            }
        ],
        "objecten": [
            {
                "object_id": 12,
                "van": "2026-01-01",
                "tot": null
            }
        ],
        "aangemaakt_op": "2026-01-02T08:00:00+01:00",
        "gewijzigd_op": "2026-04-14T10:30:00+02:00"
    }
}

GET /beveiligers

Beveiligers (zonder BSN, IBAN, adres of documenten)

Scope beveiliging.lezen

ParameterWaarBetekenis
actiefqueryAlleen actieve of inactieve beveiligers.
teamqueryWie vandaag in dit team zit.

Antwoord

{
    "data": [
        {
            "id": 31,
            "naam": "Mo Yilmaz",
            "email": "mo.yilmaz@voorbeeld.example",
            "personeelsnummer": "B-0031",
            "contractsoort": "vast",
            "zzp": false,
            "uren_per_week": 38,
            "in_dienst_sinds": "2024-03-01",
            "actief": true,
            "teams": [
                4
            ],
            "aangemaakt_op": "2024-02-20T10:00:00+01:00",
            "gewijzigd_op": "2026-05-01T09:00:00+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

GET /beveiligers/{id}

Een beveiliger

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 31,
        "naam": "Mo Yilmaz",
        "email": "mo.yilmaz@voorbeeld.example",
        "personeelsnummer": "B-0031",
        "contractsoort": "vast",
        "zzp": false,
        "uren_per_week": 38,
        "in_dienst_sinds": "2024-03-01",
        "actief": true,
        "teams": [
            4
        ],
        "aangemaakt_op": "2024-02-20T10:00:00+01:00",
        "gewijzigd_op": "2026-05-01T09:00:00+02:00"
    }
}

Diensten

Het rooster en de uitvoering; schrijven langs de planregels.

GET /diensten

Diensten: gepland, gepubliceerd en vervallen, met aan- en afmelden

Scope beveiliging.lezen. Ook als CSV of XML: ?formaat=csv|xml of Accept: text/csv / application/xml; de volgende pagina staat dan in de kop Link.

Scope beveiliging.lezen

ParameterWaarBetekenis
vanqueryVanaf deze dag (JJJJ-MM-DD), in de tijdzone van de organisatie.
totqueryTot en met deze dag (JJJJ-MM-DD).
objectqueryHet id van het object.
teamqueryHet id van het team.
beveiligerqueryHet id van de beveiliger.
planstatusqueryconcept, gepubliceerd of vervallen.
uitvoeringquerygepland, aangemeld of afgerond.
formaatqueryjson (standaard), csv of xml. Accept: text/csv of application/xml werkt ook.

Antwoord

{
    "data": [
        {
            "id": 41,
            "object_id": 12,
            "team_id": 4,
            "beveiliger_id": 31,
            "contract_id": 6,
            "planperiode_id": 20,
            "dienstsoort": "dag",
            "begint_op": "2026-06-01T07:00:00+02:00",
            "eindigt_op": "2026-06-01T15:00:00+02:00",
            "geplande_minuten": 480,
            "planstatus": "gepubliceerd",
            "uitvoering": "afgerond",
            "bron": "handmatig",
            "vervanging": null,
            "aangemeld_op": "2026-06-01T06:54:00+02:00",
            "aanmeldmethode": "geofence",
            "geofence": "inside",
            "afgemeld_op": "2026-06-01T15:20:00+02:00",
            "afmelding_ontbreekt_sinds": null,
            "gewerkte_minuten": 506,
            "meerwerk": {
                "minuten": 26,
                "gevraagd_door": "Teamleider opdrachtgever",
                "reden": "Laatste vrachtwagen te laat",
                "geregistreerd_op": "2026-06-01T14:50:00+02:00"
            },
            "notities": null,
            "aangemaakt_op": "2026-05-20T10:00:00+02:00",
            "gewijzigd_op": "2026-06-01T15:20:02+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

POST /diensten

Een conceptdienst neerzetten

Zoals op het planbord. Met beveiliger_id oordeelt de regelmotor over de toewijzing: een blokkade weigert (422 planregels_blokkade), een waarschuwing weigert tot u force: true meestuurt (422 planregels_waarschuwing). Een dienst in een vastgezette periode kan niet (409 periode_vast).

Scope beveiliging.planning.schrijven

ParameterWaarBetekenis
Idempotency-KeykopEen eigen sleutel (1 tot 120 tekens) per schrijfverzoek. Hetzelfde verzoek met dezelfde sleutel binnen 24 uur krijgt het eerste antwoord terug (met Idempotent-Replayed: true) en doet niets opnieuw. Dezelfde sleutel met een ander verzoek is 422 idempotentie_conflict.

Verzoek

{
    "object_id": 12,
    "dienstsoort": "dag",
    "datum": "2026-06-01",
    "begint": "07:00",
    "eindigt": "15:00",
    "beveiliger_id": 31
}

GET /diensten/{id}

Een dienst

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 41,
        "object_id": 12,
        "team_id": 4,
        "beveiliger_id": 31,
        "contract_id": 6,
        "planperiode_id": 20,
        "dienstsoort": "dag",
        "begint_op": "2026-06-01T07:00:00+02:00",
        "eindigt_op": "2026-06-01T15:00:00+02:00",
        "geplande_minuten": 480,
        "planstatus": "gepubliceerd",
        "uitvoering": "afgerond",
        "bron": "handmatig",
        "vervanging": null,
        "aangemeld_op": "2026-06-01T06:54:00+02:00",
        "aanmeldmethode": "geofence",
        "geofence": "inside",
        "afgemeld_op": "2026-06-01T15:20:00+02:00",
        "afmelding_ontbreekt_sinds": null,
        "gewerkte_minuten": 506,
        "meerwerk": {
            "minuten": 26,
            "gevraagd_door": "Teamleider opdrachtgever",
            "reden": "Laatste vrachtwagen te laat",
            "geregistreerd_op": "2026-06-01T14:50:00+02:00"
        },
        "notities": null,
        "aangemaakt_op": "2026-05-20T10:00:00+02:00",
        "gewijzigd_op": "2026-06-01T15:20:02+02:00"
    }
}

PATCH /diensten/{id}

Een conceptdienst wijzigen

Alleen een conceptdienst die nog niet loopt (anders 409 geen_concept). Wat u niet meestuurt blijft staan. Een andere tijd, dag, soort, object of beveiliger gaat langs de regelmotor.

Scope beveiliging.planning.schrijven

ParameterWaarBetekenis
idpadHet id.
Idempotency-KeykopEen eigen sleutel (1 tot 120 tekens) per schrijfverzoek. Hetzelfde verzoek met dezelfde sleutel binnen 24 uur krijgt het eerste antwoord terug (met Idempotent-Replayed: true) en doet niets opnieuw. Dezelfde sleutel met een ander verzoek is 422 idempotentie_conflict.

Verzoek

{
    "begint": "08:00",
    "eindigt": "16:00"
}

POST /diensten/{id}/toewijzen

Een beveiliger toewijzen

Langs de regelmotor, net als slepen op het planbord. Ook op een gepubliceerde dienst, zolang hij niet vervallen of gedraaid is en de periode niet vaststaat.

Scope beveiliging.planning.schrijven

ParameterWaarBetekenis
idpadHet id.
Idempotency-KeykopEen eigen sleutel (1 tot 120 tekens) per schrijfverzoek. Hetzelfde verzoek met dezelfde sleutel binnen 24 uur krijgt het eerste antwoord terug (met Idempotent-Replayed: true) en doet niets opnieuw. Dezelfde sleutel met een ander verzoek is 422 idempotentie_conflict.

Verzoek

{
    "beveiliger_id": 31
}

POST /diensten/{id}/vrijgeven

De beveiliger van een dienst halen (open dienst)

De dienst blijft staan zonder beveiliger: een gat dat de planner nog vult.

Scope beveiliging.planning.schrijven

ParameterWaarBetekenis
idpadHet id.
Idempotency-KeykopEen eigen sleutel (1 tot 120 tekens) per schrijfverzoek. Hetzelfde verzoek met dezelfde sleutel binnen 24 uur krijgt het eerste antwoord terug (met Idempotent-Replayed: true) en doet niets opnieuw. Dezelfde sleutel met een ander verzoek is 422 idempotentie_conflict.

Verzoek

{
    "force": false
}

POST /diensten/{id}/vervallen

Een conceptdienst laten vervallen

Vervallen, niet verwijderen: de geschiedenis van de dienst blijft staan. Alleen een conceptdienst.

Scope beveiliging.planning.schrijven

ParameterWaarBetekenis
idpadHet id.
Idempotency-KeykopEen eigen sleutel (1 tot 120 tekens) per schrijfverzoek. Hetzelfde verzoek met dezelfde sleutel binnen 24 uur krijgt het eerste antwoord terug (met Idempotent-Replayed: true) en doet niets opnieuw. Dezelfde sleutel met een ander verzoek is 422 idempotentie_conflict.

Verzoek

{
    "reden": "Opdrachtgever zegde de avond af."
}

Uren

Gewerkte diensten met toeslagregels uit de loonspecificatie.

GET /uren

Gewerkte diensten met minuten, meerwerk en toeslagregels

Scope beveiliging.uren.lezen. Ook als CSV of XML: ?formaat=csv|xml of Accept: text/csv / application/xml; de volgende pagina staat dan in de kop Link.

Scope beveiliging.uren.lezen

ParameterWaarBetekenis
vanqueryVanaf deze dag (JJJJ-MM-DD), in de tijdzone van de organisatie.
totqueryTot en met deze dag (JJJJ-MM-DD).
objectqueryHet id van het object.
teamqueryHet id van het team.
beveiligerqueryHet id van de beveiliger.
formaatqueryjson (standaard), csv of xml. Accept: text/csv of application/xml werkt ook.

Antwoord

{
    "data": [
        {
            "dienst_id": 41,
            "beveiliger_id": 31,
            "object_id": 12,
            "team_id": 4,
            "datum": "2026-06-01",
            "dienstsoort": "nacht",
            "begint_op": "2026-06-01T23:00:00+02:00",
            "eindigt_op": "2026-06-02T07:00:00+02:00",
            "aangemeld_op": "2026-06-01T22:56:00+02:00",
            "afgemeld_op": "2026-06-02T07:30:00+02:00",
            "geplande_minuten": 480,
            "gewerkte_minuten": 514,
            "meerwerk_minuten": 34,
            "eindtijd_bevestigd_door_kantoor": false,
            "specificatie": {
                "id": 9,
                "maand": "2026-06",
                "versie": 1,
                "status": "final"
            },
            "regels": [
                {
                    "soort": "basis",
                    "omschrijving": "Basisuren",
                    "minuten": 480,
                    "uurloon_cent": 1650,
                    "percentage": null,
                    "bedrag_cent": 13200,
                    "regel": "cao art. 13",
                    "datum": "2026-06-01"
                },
                {
                    "soort": "toeslag",
                    "omschrijving": "Nachttoeslag",
                    "minuten": 420,
                    "uurloon_cent": 1650,
                    "percentage": 30,
                    "bedrag_cent": 3465,
                    "regel": "cao art. 21",
                    "datum": "2026-06-01"
                }
            ],
            "gewijzigd_op": "2026-06-02T07:30:05+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

Verlof en beschikbaarheid

Verlof en afwezigheid, en wanneer een beveiliger kan.

PUT /beveiligers/{id}/beschikbaarheid

Beschikbaarheid zetten

Per weekdag (0 is zondag) en per datum. Werkt zoals in de app van de beveiliger: niveau no is niet beschikbaar; een datum vervangt wat er voor die datum stond.

Scope beveiliging.planning.schrijven

ParameterWaarBetekenis
idpadHet id.
Idempotency-KeykopEen eigen sleutel (1 tot 120 tekens) per schrijfverzoek. Hetzelfde verzoek met dezelfde sleutel binnen 24 uur krijgt het eerste antwoord terug (met Idempotent-Replayed: true) en doet niets opnieuw. Dezelfde sleutel met een ander verzoek is 422 idempotentie_conflict.

Verzoek

{
    "weekdagen": [
        {
            "weekdag": 0,
            "beschikbaar": false,
            "niveau": "no"
        }
    ],
    "uitzonderingen": [
        {
            "datum": "2026-06-12",
            "beschikbaar": false,
            "notitie": "Bruiloft"
        }
    ]
}

GET /verlof

Verlof en afwezigheid

Scope beveiliging.lezen. Ook als CSV of XML: ?formaat=csv|xml of Accept: text/csv / application/xml; de volgende pagina staat dan in de kop Link.

Scope beveiliging.lezen

ParameterWaarBetekenis
vanqueryVanaf deze dag (JJJJ-MM-DD), in de tijdzone van de organisatie.
totqueryTot en met deze dag (JJJJ-MM-DD).
beveiligerqueryHet id van de beveiliger.
statusquerypending, approved, rejected, active (lopende ziekte), withdrawn, cancelled of revoked.
soortqueryvacation, unpaid, special of sick.
formaatqueryjson (standaard), csv of xml. Accept: text/csv of application/xml werkt ook.

Antwoord

{
    "data": [
        {
            "id": 55,
            "beveiliger_id": 31,
            "soort": "vacation",
            "van": "2026-07-13",
            "tot": "2026-07-24",
            "status": "approved",
            "reden": "Zomervakantie",
            "beoordeeld_op": "2026-05-02T10:11:00+02:00",
            "aangemaakt_op": "2026-04-28T19:40:00+02:00",
            "gewijzigd_op": "2026-05-02T10:11:00+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

POST /verlof

Verlof aanvragen namens een beveiliger

Dezelfde toets op overlap als in de app. Kantoor beoordeelt; dat komt terug als verlof.goedgekeurd of verlof.afgewezen.

Scope beveiliging.verlof.schrijven

ParameterWaarBetekenis
Idempotency-KeykopEen eigen sleutel (1 tot 120 tekens) per schrijfverzoek. Hetzelfde verzoek met dezelfde sleutel binnen 24 uur krijgt het eerste antwoord terug (met Idempotent-Replayed: true) en doet niets opnieuw. Dezelfde sleutel met een ander verzoek is 422 idempotentie_conflict.

Verzoek

{
    "beveiliger_id": 31,
    "soort": "vacation",
    "van": "2026-07-13",
    "tot": "2026-07-24",
    "reden": "Zomervakantie"
}

GET /verlof/{id}

Een verlofaanvraag

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 55,
        "beveiliger_id": 31,
        "soort": "vacation",
        "van": "2026-07-13",
        "tot": "2026-07-24",
        "status": "approved",
        "reden": "Zomervakantie",
        "beoordeeld_op": "2026-05-02T10:11:00+02:00",
        "aangemaakt_op": "2026-04-28T19:40:00+02:00",
        "gewijzigd_op": "2026-05-02T10:11:00+02:00"
    }
}

GET /beschikbaarheid

Beschikbaarheid per weekdag en per datum

Scope beveiliging.lezen

ParameterWaarBetekenis
vanqueryVanaf deze dag (JJJJ-MM-DD), in de tijdzone van de organisatie.
totqueryTot en met deze dag (JJJJ-MM-DD).
beveiligerqueryHet id van de beveiliger.

Antwoord

{
    "data": [
        {
            "id": 301,
            "beveiliger_id": 31,
            "weekdag": 6,
            "datum": null,
            "beschikbaar": false,
            "niveau": "no",
            "notitie": null,
            "reistijd_minuten": null,
            "gewijzigd_op": "2026-05-10T12:00:00+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

Operatie

Bevindingen en rondes.

GET /bevindingen

Bevindingen (zonder foto)

Scope beveiliging.lezen

ParameterWaarBetekenis
vanqueryVanaf deze dag (JJJJ-MM-DD), in de tijdzone van de organisatie.
totqueryTot en met deze dag (JJJJ-MM-DD).
objectqueryHet id van het object.
dienstqueryHet id van de dienst.
statusqueryDe stand van de bevinding.
risicoqueryHet risico van de bevinding.

Antwoord

{
    "data": [
        {
            "id": 501,
            "dienst_id": 41,
            "object_id": 12,
            "beveiliger_id": 31,
            "ronde_id": 77,
            "controlepunt_id": 9,
            "categorie": "deur",
            "plaats": "Nooduitgang hal B",
            "risico": "midden",
            "politie_nodig": false,
            "omschrijving": "Nooduitgang stond open, gesloten en gemeld.",
            "status": "open",
            "locatie": {
                "lat": 52.0911,
                "lng": 5.122
            },
            "gemeld_op": "2026-06-02T02:14:00+02:00",
            "geescaleerd_op": null,
            "escalatie_reden": null,
            "reactie": null,
            "beantwoord_op": null,
            "afgesloten_op": null,
            "heeft_foto": true,
            "gewijzigd_op": "2026-06-02T02:14:00+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

GET /bevindingen/{id}

Een bevinding

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 501,
        "dienst_id": 41,
        "object_id": 12,
        "beveiliger_id": 31,
        "ronde_id": 77,
        "controlepunt_id": 9,
        "categorie": "deur",
        "plaats": "Nooduitgang hal B",
        "risico": "midden",
        "politie_nodig": false,
        "omschrijving": "Nooduitgang stond open, gesloten en gemeld.",
        "status": "open",
        "locatie": {
            "lat": 52.0911,
            "lng": 5.122
        },
        "gemeld_op": "2026-06-02T02:14:00+02:00",
        "geescaleerd_op": null,
        "escalatie_reden": null,
        "reactie": null,
        "beantwoord_op": null,
        "afgesloten_op": null,
        "heeft_foto": true,
        "gewijzigd_op": "2026-06-02T02:14:00+02:00"
    }
}

GET /bevindingen/{id}/foto

Een getekende link naar de foto (vijf minuten)

Scope beveiliging.bevindingen.foto

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "url": "https://api.beveiligingx.nl/api/v1/beveiliging/bevindingen/501/foto/bestand?organisatie=3&expires=1780363200&signature=6b1d...",
        "verloopt_op": "2026-06-02T09:05:00+02:00",
        "geldig_minuten": 5
    }
}

GET /bevindingen/{id}/foto/bestand

De foto achter een getekende link

Geen sleutel: de handtekening in de link is de toegang en verloopt na vijf minuten. Neem de link letterlijk over uit GET /bevindingen/{id}/foto.

Zonder sleutel

ParameterWaarBetekenis
idpadHet id.
organisatiequeryStaat in de getekende link.
expiresqueryStaat in de getekende link.
signaturequeryStaat in de getekende link.

GET /rondes

Rondes met de scans van de controlepunten

Scope beveiliging.lezen

ParameterWaarBetekenis
vanqueryVanaf deze dag (JJJJ-MM-DD), in de tijdzone van de organisatie.
totqueryTot en met deze dag (JJJJ-MM-DD).
dienstqueryHet id van de dienst.
objectqueryHet id van het object.
statusquerypending, active, interrupted of completed.

Antwoord

{
    "data": [
        {
            "id": 77,
            "dienst_id": 41,
            "volgnummer": 1,
            "status": "completed",
            "gepland_op": null,
            "gestart_op": "2026-06-02T01:00:00+02:00",
            "onderbroken_op": null,
            "onderbreking_reden": null,
            "hervat_op": null,
            "afgerond_op": "2026-06-02T01:42:00+02:00",
            "scans": [
                {
                    "id": 900,
                    "controlepunt_id": 9,
                    "controlepunt": "Hal B noord",
                    "status": "ok",
                    "gescand_op": "2026-06-02T01:12:00+02:00",
                    "storing": null,
                    "geofence": "inside"
                }
            ],
            "gewijzigd_op": "2026-06-02T01:42:00+02:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

GET /rondes/{id}

Een ronde

Scope beveiliging.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": {
        "id": 77,
        "dienst_id": 41,
        "volgnummer": 1,
        "status": "completed",
        "gepland_op": null,
        "gestart_op": "2026-06-02T01:00:00+02:00",
        "onderbroken_op": null,
        "onderbreking_reden": null,
        "hervat_op": null,
        "afgerond_op": "2026-06-02T01:42:00+02:00",
        "scans": [
            {
                "id": 900,
                "controlepunt_id": 9,
                "controlepunt": "Hal B noord",
                "status": "ok",
                "gescand_op": "2026-06-02T01:12:00+02:00",
                "storing": null,
                "geofence": "inside"
            }
        ],
        "gewijzigd_op": "2026-06-02T01:42:00+02:00"
    }
}

Dossier

Kwalificaties met vervaldatum (eigen scope).

GET /beveiligers/{id}/kwalificaties

De kwalificaties van een beveiliger

Scope beveiliging.dossier.lezen

ParameterWaarBetekenis
idpadHet id.

Antwoord

{
    "data": [
        {
            "id": 88,
            "beveiliger_id": 31,
            "soort": "wpbr_pas",
            "omschrijving": "WPBR-legitimatiebewijs (grijze pas)",
            "nummer": "P123456",
            "geldig_tot": "2027-02-28",
            "verlopen": false,
            "beoordeling": "verified",
            "beoordeeld_op": "2026-02-01T10:00:00+01:00",
            "gewijzigd_op": "2026-02-01T10:00:00+01:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

GET /kwalificaties

Kwalificaties met vervaldatum

Scope beveiliging.dossier.lezen

ParameterWaarBetekenis
beveiligerqueryHet id van de beveiliger.
soortquerywpbr_pas, vog, screening, diploma, ehbo of bhv.
verloopt_voorqueryAlleen wat voor deze datum (JJJJ-MM-DD) verloopt.

Antwoord

{
    "data": [
        {
            "id": 88,
            "beveiliger_id": 31,
            "soort": "wpbr_pas",
            "omschrijving": "WPBR-legitimatiebewijs (grijze pas)",
            "nummer": "P123456",
            "geldig_tot": "2027-02-28",
            "verlopen": false,
            "beoordeling": "verified",
            "beoordeeld_op": "2026-02-01T10:00:00+01:00",
            "gewijzigd_op": "2026-02-01T10:00:00+01:00"
        }
    ],
    "links": {
        "self": "...",
        "volgende": null
    },
    "meta": {
        "per_pagina": 100,
        "aantal": 1,
        "volgende_cursor": null
    }
}

Specificatie

Deze specificatie zelf.

GET /openapi.json

Deze specificatie (OpenAPI 3.1, JSON)

Zonder sleutel

Webhooks

Een webhook meldt een ander systeem wat er gebeurt, zodra het gebeurt. In de backoffice zet u een https-adres neer, kiest u de gebeurtenissen en krijgt u een geheim (whsec_...). Elke aflevering is een POST met deze envelop:

{
    "id": "evt_01jz8m2c4n7q9r0s1t2v3w4x5y",
    "type": "dienst.toegewezen",
    "occurred_at": "2026-05-28T14:03:12+02:00",
    "api_version": "v1",
    "tenant": {
        "id": 3,
        "naam": "Wachtpost Beveiliging B.V."
    },
    "data": {
        "dienst": {
            "id": 41,
            "object_id": 12,
            "team_id": 4,
            "beveiliger_id": 31,
            "contract_id": 6,
            "planperiode_id": 20,
            "dienstsoort": "dag",
            "begint_op": "2026-06-01T07:00:00+02:00",
            "eindigt_op": "2026-06-01T15:00:00+02:00",
            "geplande_minuten": 480,
            "planstatus": "gepubliceerd",
            "uitvoering": "afgerond",
            "bron": "handmatig",
            "vervanging": null,
            "aangemeld_op": "2026-06-01T06:54:00+02:00",
            "aanmeldmethode": "geofence",
            "geofence": "inside",
            "afgemeld_op": "2026-06-01T15:20:00+02:00",
            "afmelding_ontbreekt_sinds": null,
            "gewerkte_minuten": 506,
            "meerwerk": {
                "minuten": 26,
                "gevraagd_door": "Teamleider opdrachtgever",
                "reden": "Laatste vrachtwagen te laat",
                "geregistreerd_op": "2026-06-01T14:50:00+02:00"
            },
            "notities": null,
            "aangemaakt_op": "2026-05-20T10:00:00+02:00",
            "gewijzigd_op": "2026-06-01T15:20:02+02:00"
        },
        "beveiliger_id": 31,
        "vorige_beveiliger_id": null
    }
}
GebeurtenisNaamWanneer
dienst.aangemaaktDienst aangemaaktEen nieuwe dienst staat op het rooster: op het planbord, uit een basisrooster, een aanvraag van een opdrachtgever of via de API.
dienst.gewijzigdDienst gewijzigdTijd, soort, object, team, notitie of planstatus van een dienst veranderde (ook publiceren van de periode). `velden` noemt wat.
dienst.toegewezenBeveiliger toegewezen of vrijgegevenDe beveiliger op een dienst veranderde. `beveiliger_id` leeg is een open dienst; `vorige_beveiliger_id` is wie er stond.
dienst.vervallenDienst vervallenEen dienst vervalt; hij blijft met zijn geschiedenis bestaan.
dienst.aangemeldBeveiliger aangemeldDe beveiliger meldde zich aan op het object (geofence of handmatig).
dienst.afgemeldBeveiliger afgemeldDe dienst is afgerond, met de gewerkte minuten en eventueel meerwerk.
meerwerk.geregistreerdMeerwerk geregistreerdOp een dienst is meerwerk vastgelegd: wie het vroeg en waarom.
bevinding.gemeldBevinding gemeldEen beveiliger meldde een bevinding. Zonder foto; die haalt u met de scope beveiliging.bevindingen.foto.
verlof.aangevraagdVerlof aangevraagdEen beveiliger (of een koppeling namens hem) vroeg verlof aan.
verlof.goedgekeurdVerlof goedgekeurdKantoor keurde verlof goed of boekte het zelf in.
verlof.afgewezenVerlof afgewezenKantoor wees een verlofaanvraag af.
maandstaat.geslotenMaandstaat geslotenKantoor sloot de maandstaat van een object: de geleverde uren en het te factureren bedrag liggen vast.
factuur.aangemaaktVerkoopfactuur aangemaaktDe boekhouding maakte een verkoopfactuur of creditnota (alleen als de boekhouding aan staat).
kwalificatie.verlooptKwalificatie verlooptEen kwalificatie van een beveiliger verloopt binnen zestig dagen, of is net verlopen. Een keer per fase.
test.pingTestDe knop Test versturen in de backoffice.

Koppen

  • X-BeveiligingX-Handtekening: t=<tijdstempel>,v1=<hex>, de HMAC-SHA256 met uw geheim over <tijdstempel>.<inhoud>.
  • X-BeveiligingX-Tijdstempel: seconden sinds 1970 (UTC), dezelfde als in de handtekening.
  • X-BeveiligingX-Gebeurtenis en X-BeveiligingX-Gebeurtenis-Id: het type en het id uit de envelop.
  • X-BeveiligingX-Aflevering en X-BeveiligingX-Poging: deze aflevering en het nummer van de poging.

Ontvangen, herkansen en uitschakelen

  • Antwoord binnen tien seconden met een 2xx; zwaar werk doet u daarna. Een omleiding volgt Beveiliging X niet.
  • Lukt het niet, dan volgt een nieuwe poging na 1 minuut, 5 minuten, 30 minuten, 2, 6, 12 en 24 uur. Daarna staat de aflevering op mislukt en kan kantoor hem met de hand opnieuw versturen. Het id van de gebeurtenis blijft hetzelfde: verwerk elk id een keer.
  • Na vijftien mislukte pogingen achter elkaar zet Beveiliging X het adres uit en meldt dat in het signalencentrum. Weer aanzetten begint met een schone lei.
  • Elke poging staat in het logboek in de backoffice, met de statuscode, het begin van uw antwoord en de duur. Met Test versturen komt er een test.ping.
  • De volgorde is niet gegarandeerd. Vergelijk occurred_at of data.dienst.gewijzigd_op, of haal bij twijfel de bron op met de API.

De handtekening controleren

PHP

<?php
// Controleer de handtekening voordat u iets met de inhoud doet.
$geheim = getenv('BEVEILIGINGX_WEBHOOK_GEHEIM');            // whsec_..., uit de backoffice
$inhoud = file_get_contents('php://input');                  // de ruwe inhoud, niet opnieuw gecodeerd
$kop = $_SERVER['HTTP_X_BEVEILIGINGX_HANDTEKENING'] ?? '';   // t=1767225600,v1=5f2b...

$delen = [];
foreach (explode(',', $kop) as $deel) {
    [$sleutel, $waarde] = array_pad(explode('=', trim($deel), 2), 2, '');
    $delen[$sleutel] = $waarde;
}
$tijdstempel = (int) ($delen['t'] ?? 0);

// Replay-bescherming: niet ouder of nieuwer dan vijf minuten.
if (abs(time() - $tijdstempel) > 300) {
    http_response_code(400);
    exit('Tijdstempel te oud');
}

$verwacht = hash_hmac('sha256', $tijdstempel.'.'.$inhoud, $geheim);
if (! hash_equals($verwacht, (string) ($delen['v1'] ?? ''))) {
    http_response_code(401);
    exit('Handtekening klopt niet');
}

$gebeurtenis = json_decode($inhoud, true, 512, JSON_THROW_ON_ERROR);
// Hetzelfde id kan nog eens komen (opnieuw versturen): verwerk elk id een keer.
// ... zet $gebeurtenis['id'] en $gebeurtenis['type'] op uw eigen wachtrij ...
http_response_code(204);

Node.js (Express)

import crypto from 'node:crypto'
import express from 'express'

const app = express()

// express.raw: de handtekening gaat over de ruwe bytes, niet over opnieuw gecodeerde JSON.
app.post('/webhooks/beveiligingx', express.raw({ type: 'application/json' }), (req, res) => {
  const kop = req.get('X-BeveiligingX-Handtekening') ?? ''
  const delen = Object.fromEntries(kop.split(',').map((deel) => deel.trim().split('=', 2)))
  const tijdstempel = Number(delen.t)

  // Replay-bescherming: niet ouder of nieuwer dan vijf minuten.
  if (!Number.isInteger(tijdstempel) || Math.abs(Date.now() / 1000 - tijdstempel) > 300) {
    return res.status(400).send('Tijdstempel te oud')
  }

  const verwacht = crypto
    .createHmac('sha256', process.env.BEVEILIGINGX_WEBHOOK_GEHEIM)
    .update(`${tijdstempel}.${req.body}`)
    .digest('hex')
  const gekregen = String(delen.v1 ?? '')
  const klopt = gekregen.length === verwacht.length
    && crypto.timingSafeEqual(Buffer.from(verwacht), Buffer.from(gekregen))
  if (!klopt) return res.status(401).send('Handtekening klopt niet')

  const gebeurtenis = JSON.parse(req.body.toString('utf8'))
  // Hetzelfde id kan nog eens komen (opnieuw versturen): verwerk elk id een keer.
  res.sendStatus(204)
})

app.listen(3000)