> For the complete documentation index, see [llms.txt](https://docs.cerrix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cerrix.com/cerrix-documentation-nl/cerrix-functionaliteiten/admin-settings/api-documentation.md).
# API-documentatie
U kunt de CERRIX API-documentatie rechtstreeks in het platform vinden door te klikken op de :question:het pictogram rechtsboven in het platform en vervolgens op "Manuals" te klikken
Ga vervolgens naar API Manual. Hier ziet u een overzicht van alle ondersteunde API-endpoints.
## Het juiste endpoint kiezen voor rapportage
De API Manual in het platform vermeldt elk endpoint, maar een veelgestelde vraag is *welk* endpoint u moet gebruiken voor een bepaalde rapportagebehoefte. Het belangrijkste onderscheid is tussen **Workflow-endpoints** en **rapportage-(DirectData)-datasets**.
* **Workflow-endpoints zijn niet bedoeld voor rapportage.** Workflow-endpoints per beheersmaatregel, zoals *Get Test Info* bestaan alleen om de workflow voor het testen van een enkele beheersmaatregel aan te sturen. Ze kunnen niet worden gebruikt om over meerdere beheersmaatregelen te rapporteren. Voor rapportage over testen van beheersmaatregelen (bijvoorbeeld start- en einddata van tests over beheersmaatregelen) gebruikt u de **DirectData Beheersmaatregel / Testen** datasets in plaats daarvan.
* **Reviewerresultaten** (welke reviewer een testplanbeoordeling heeft uitgevoerd, de beoordelingsscore en de tijdstempel) zijn niet beschikbaar in Workspace-exports, maar een speciaal API-dataset geeft de **ReviewerGUID, beoordelingsscore en tijdstempel**.
* **MoI-statusgeschiedenis** — hetzelfde overzicht als de Excel *"MoI's en opmerkingen"* download — is beschikbaar via een speciaal MoI-opmerkingen-API-endpoint, zodat het overzicht van de statusgeschiedenis geautomatiseerd kan worden gereconstrueerd.
{% hint style="info" %}
Er is momenteel **geen API om een lijst te tonen van welke beheersmaatregelen in een externe verbinding zijn geconfigureerd**. De opties zijn om de aanvraag uit te voeren zonder Identifier-filter, of om de wizard voor externe verbindingen in de CERRIX-gebruikersinterface te controleren.
{% endhint %}
## Risico-API-versies (V1, V2, V3)
De V1-, V2- en V3-Risico-API's geven de **dezelfde onderliggende risicogegevens**. De versies bestaan vanwege een wijziging in hoe de hoofdoorzaak / Gebeurteniscategorie van een Risico wordt geregistreerd. Zie de release notes voor de achtergrond van deze wijziging.
**V1 → V2: alleen een naamswijziging.** Het veld met de naam *"Gebeurteniscategorie"* in V1 werd hernoemd naar *"Hoofdoorzaakcategorie"* in V2. Het is dezelfde enkele waarde onder een nieuwe naam. Dit heeft gevolgen voor:
* De risico-endpoints (`/risicodata/v{version}/risico`, `/risicobeheersmaatregel`, `/risicobeheersmaatregelmois`): `gebeurteniscategorie` werd `hoofdoorzaakcategorie`.
* Het DirectData-risico-endpoint (`/directdata/v{version}/risico`): `GebeurteniscategorieId` werd `HoofdoorzaakcategorieId`.
* Het stamdata-endpoint zelf is hernoemd van `/directdata/v1/risicogebeurteniscategorie` ("Risico-gebeurteniscategorie") naar `/directdata/v2/risicohoofdoorzaakcategorie` ("Risico-hoofdoorzaakcategorie").
**V2 → V3: de hoofdoorzaakcategorie werd een meervoudige selectie.** In V3 kan een risico gekoppeld worden aan **meerdere** hoofdoorzaakcategorieën in plaats van slechts één, dus geven de relevante API's nu meerdere waarden terug in plaats van één enkele:
* De risico-endpoints retourneren `rootCauseCategories` (meervoud) in plaats van `hoofdoorzaakcategorie`.
* Het DirectData-risico-endpoint retourneert `RootCauseCategoryIds` als een array met waarden in plaats van de enkele `HoofdoorzaakcategorieId`.
{% hint style="success" %}
Voor nieuwe integraties, gebruik **V3** zodat u de nieuwste versie gebruikt.
{% endhint %}
## Incident-endpoints en inkomende registraties
De API ondersteunt incidenten in beide richtingen: externe systemen kunnen **aanmaken** incidenten in CERRIX, en rapportagetools kunnen **ophalen** ze.
### Incidenten aanmaken vanuit externe tooling
Gebruik het **POST incidenten** endpoint om incidenten automatisch te registreren vanuit externe systemen — bijvoorbeeld een IT-servicemanagementtool waarin incidenten ook worden vastgelegd. Genereer de API-sleutel vanuit een **serviceaccount**, zodat de integratie onder zijn eigen identiteit draait in plaats van onder een persoonlijk gebruikersaccount.
### Incidenten ophalen voor rapportage
De **DirectData-incidentdatasets** (incidenten, classificaties, incidenttypen, aangepaste velden en waarden, en gekoppelde MoI's) leveren uw incidentgegevens voor rapportagetools zoals Power BI.
De API-laag richt zich op het aanmaken en ophalen van incidenten; wijzigingen aan bestaande incidenten worden in de applicatie zelf doorgevoerd. Plan grotere oefeningen, zoals het opnieuw toewijzen van incidenten aan een nieuwe structuur voor hoofdoorzaakcategorieën, als een activiteit in het incidentoverzicht.
### Registraties vastleggen uit externe formulieren
Met de **POST formulierresultaten** endpoint kunt u inzendingen van een externe formulier-tool in een CERRIX-formulier invoeren, zodat elke medewerker een incident kan melden terwijl alleen uw incidentteam in CERRIX werkt — melders hebben geen eigen CERRIX-account nodig. Ook hier genereert u de API-sleutel vanuit een serviceaccount.
Twee aandachtspunten om rekening mee te houden bij het ontwerpen van het externe formulier:
* Koppel de formuliervragen aan gewone velden; structuurvelden binnen CERRIX, zoals organisatieselecties, worden door uw incidentteam ingesteld tijdens het afhandelen van de registratie.
* Neem een vraag naar de naam op in het formulier, zodat melders zichzelf kunnen identificeren, aangezien de inzending zelf onder het serviceaccount wordt geregistreerd.
Neem voor hulp bij het ontwerpen van een inkomende integratie contact op met de CERRIX-ondersteuning via de servicedesk.
## Direct Data-datasets per module
De Direct Data-endpoints (`/directdata/v1/...`) retourneren genormaliseerde datasets voor rapportagetools zoals Power BI. Naast de datasets voor risico's, beheersmaatregelen en beheerstests, MoI's, derde partijen, taken en gebruikers, zijn de volgende modules beschikbaar:
* **Incidenten** — incidenten (inclusief de registratiedatum en de GUID's van gekoppelde MoI's, risico's en beheersmaatregelen), classificaties, incidenttypen, aangepaste velden voor incidenttypen en hun waarden, en incident-MoI's.
* **Audit** — `GET /directdata/v1/audit` retourneert uw audits met hun Identifier, naam, doelstelling, rationale, conclusie, plan, status, type, criticaliteit, vertrouwelijkheid en score, samen met het gekoppelde Bevindingenrapport, derden, Risico's, Beheersmaatregelen, universumobjecten, Organisaties, bedrijfsdimensies, frameworkdimensies en de betrokken personen (sponsors, geauditeerden, auditors, Reviewers en chief audit executives). `GET /directdata/v1/auditfinding` retourneert één rij per auditbevinding — beschrijving, hoofdoorzaak, aanbeveling, ernst, opmerking, managementreactie en status — inclusief de vervolgacties, gekoppelde MoI's en de bovenliggende audit om op te koppelen. De basisgegevens van de audit (audittype, observatiescores per audittype, auditscore, kritischheid, vertrouwelijkheid, bevindingsernst, vervolgactie op bevindingen en workflow) en de aangepaste velden voor de auditcontext en het audit-risicoassessment zijn beschikbaar als afzonderlijke endpoints.
* **Gegevensbeheer** — één endpoint voor de gegevensverwerking, inclusief de gekoppelde MoI's, risico's en beheersmaatregelen, en één voor de beheerde datastructuren. Als er geen systeem is geconfigureerd, bevat het antwoord een opmerking die de waarde "Geen systeem" uitlegt.
* **Bedrijfsbeoordelingen** — organisatie, Bedrijfsdimensie, reviewers, reviewfrequentie, initiële datum en volgende reviewdatum, en per review de datum van beoordeling, score, Reviewer en opmerking. De basisgegevens van de Assessmentscore hebben een eigen endpoint.
* **KPI/KRI** — alle KPI's en KRI's (inclusief hun raamwerkdimensies) en hun gegevenswaarden.
* **Derde partijen en contracten** — derde partijen (inclusief raamwerkdimensies), contracten (inclusief de contract-GUID en de opzegtermijn als een getal en een eenheid), en de definities en waarden van aangepaste velden van zowel derde partijen als contracten.
* **MoI's** — één endpoint per MoI-type (Risico, Beheersmaatregel, Gebeurtenis, Incident, Derde partij, gegevensbeheer en BIM), elk inclusief de status en de initiële vervaldatum; het BIM MoI-endpoint retourneert ook de raamwerkdimensies.
De exacte velden en parameters van elke dataset worden beschreven onder *Directe data-API's* in de API-handleiding in het platform. Zie voor de sleutels om datasets te koppelen [Relaties tussen API-eindpunten](https://docs.cerrix.com/cerrix-functionalities/admin-settings/api-documentation/api-endpoint-relationships).
## Beheersmaatregeltest-endpoints voor geautomatiseerde testplannen
Naast de rapportagedatasets ondersteunt de Effectiviteitstoetsing-API het automatiseren van stappen van een Testplan-Workflow vanuit een extern systeem:
* **Genereer steekproeven** voor een Testplan, en **brondocumenten uploaden** voor handmatige steekproefname.
* **Haal steekproeven op** geeft de steekproeven en teststappen van een Testplan terug, inclusief de document-GUID en de naam van elk bewijsbestand — ook voor bewijsmateriaal dat afkomstig is van Beheersmaatregel-uitvoeringstaken in uitvoeringgebaseerde testing — en speciale eindpunten geven het bewijsbestand van een steekproef of van een teststap terug.
* **Dien de eindscore in** en het commentaar van een Testplan dat de status heeft *Testen – wachten op conclusie*; daarna gaat het Testplan verder naar de volgende Workflowstap. Het eindpunt volgt het machtigingsmodel van de applicatie: alleen de toegewezen Beheersmaatregeltester of een gebruiker met de rol Beheersmaatregelbeheer kan een score indienen (beperkte beheerders alleen voor hun eigen organisaties). Testplannen voor Beheersmaatregelen die niet hebben plaatsgevonden volgen een andere Workflow en vallen niet onder dit eindpunt.
Alle eindpunten voor Effectiviteitstoetsing, hun parameters en responsvelden worden beschreven in de API-handleiding in het platform.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.cerrix.com/cerrix-documentation-nl/cerrix-functionaliteiten/admin-settings/api-documentation.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
