> For the complete documentation index, see [llms.txt](https://engyon.gitbook.io/engyon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engyon.gitbook.io/engyon/api/introductie.md).

# Introductie

Met de Engyon REST API kunnen externe systemen op een gecontroleerde en veilige manier integreren met Engyon. Typische integraties zijn het aanmaken van klantorganisaties vanuit een CRM, het aanmaken van audits vanuit een practice management-systeem, en het uitwisselen van auditgegevens met andere tools in het IT-landschap van je kantoor.

Deze documentatie is geschreven voor systeemintegratoren. Ze behandelt de basisprincipes van de API, hoe je een service account configureert, hoe je *requests* authenticeert, en hoe je de meest voorkomende use cases implementeert.

{% hint style="info" %}
De interactieve API-referentie (Swagger) is beschikbaar op <https://audit.engyon.io/api/v1/docs/>. Je moet ingelogd zijn in Engyon om die pagina te openen. Gebruik die pagina als gezaghebbende referentie op veldniveau terwijl je je integratie bouwt.
{% endhint %}

### Basis-URL

Alle API-requests gebruiken de volgende basis-URL:

```
https://audit.engyon.io/api/v1
```

Het token-endpoint is bijvoorbeeld:

```
https://audit.engyon.io/api/v1/oauth/token/
```

### Hoe de API zich verhoudt tot Engyon

De API ontsluit geselecteerde Engyon-functionaliteit die je al kent uit de applicatie, zoals:

* **Klantorganisaties** — de klanten van je accountantskantoor
* **Juridische entiteiten** — de bedrijven die bij een klant horen (bijvoorbeeld een holding en haar dochters)
* **Audits** — controledossiers, inclusief groepsdossiers (geconsolideerde audits) en hun component audits
* **Gebruikers en rollen** — het toewijzen van bestaande Engyon-gebruikers aan klanten en audits

Een service account handelt altijd namens één **auditororganisatie** (je accountantskantoor). Die organisatie wordt afgeleid uit de credentials van het service account. Je stuurt nooit een identifier van de auditororganisatie mee in de request body.

### Externe ID’s

In de API wordt elk resource geïdentificeerd met een **externe id**. In request- en response-bodies verschijnt deze waarde als het veld `id`.

Externe id’s vormen de brug tussen je eigen systemen en Engyon:

* Bij het aanmaken van een resource mag je zelf een `id` meegeven (bijvoorbeeld het klantnummer uit je CRM).
* Laat je het `id` weg, dan genereert Engyon er een voor je.
* Na het aanmaken **kan de `id` niet meer worden gewijzigd**. Behandel hem als een permanente identifier.
* Padparameters zoals `{client_organisation_id}` en `{audit_id}` verwijzen altijd naar deze externe `id`, niet naar een interne database-id.

#### Uniciteit

Externe id’s zijn uniek binnen een gedefinieerde scope:

| Resource            | Uniciteitsscope                    |
| ------------------- | ---------------------------------- |
| Klantorganisatie    | Uniek binnen je auditororganisatie |
| Juridische entiteit | Uniek binnen haar klantorganisatie |
| Audit               | Uniek binnen je auditororganisatie |

{% hint style="warning" %}
Kies vooraf stabiele identifiers. Omdat externe id’s na aanmaken niet meer kunnen worden aangepast, kun je een slecht gekozen id alleen corrigeren door een nieuw resource aan te maken (en het oude op te schonen waar dat mogelijk is).
{% endhint %}

#### Voorbeeld

Wanneer je de klant Fictiva Holding aanmaakt met id `fictiva-holding`, is dat dezelfde waarde waarmee je de klant in elke volgende call aanspreekt:

```
GET /api/v1/client-organisations/fictiva-holding/
POST /api/v1/client-organisations/fictiva-holding/legal-entities/
POST /api/v1/audits/   # met "client_organisation_id": "fictiva-holding"
```

### Authenticatie in het kort

De API gebruikt de OAuth 2.0 **client credentials**-flow:

1. Een beheerder maakt in Engyon een **service account** aan en ontvangt een `client_id` en `client_secret`.
2. Je integratie wisselt die credentials in voor een kortlevend access token.
3. Elk API-request neemt dat token op in de `Authorization`-header.

Je zet dit op in Configuratie en oefent de token-flow in \[Basishandelingen]\(<https://engyon.gitbook.io/engyon/api/basishandelingen>).

### Wat nu verder lezen

1. \[Configuratie]\(<https://engyon.gitbook.io/engyon/api/configuratie>): een service account aanmaken en de juiste rollen kiezen
2. \[Basishandelingen]\(<https://engyon.gitbook.io/engyon/api/basishandelingen>): een token ophalen, requests authenticeren, paginering en rate limits
3. \[Use cases]\(<https://engyon.gitbook.io/engyon/api/use-cases>): end-to-end flows zoals het aanmaken van een klant of een audit