> 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/use-cases/een-audit-aanmaken.md).

# Een audit aanmaken

Deze use case laat zien hoe je via de API een audit (controledossier) aanmaakt: welke gegevens je nodig hebt, hoe je een enkelvoudige audit of een groepscontrole (geconsolideerde audit) aanmaakt, hoe je component audits (controle-eenheden) definieert, en hoe je audits koppelt in een **auditnetwerk**.

We gaan verder met het **Fictiva**-voorbeeld uit \[Een klant aanmaken]\(<https://engyon.gitbook.io/engyon/api/use-cases/een-klant-aanmaken>).

**Vereiste service account-rol:** API account manager (`api_account_manager`)

### Begrippen

| Term                                       | Betekenis in de API                                                                                                                                               |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enkelvoudige audit**                     | Een audit met `audit_type: "single"`                                                                                                                              |
| **Groepscontrole / geconsolideerde audit** | Een top-level audit met `audit_type: "consolidated"`. Bevat component audits.                                                                                     |
| **Component audit**                        | Een kind van een groepsdossier (een controle-eenheid voor één of meer juridische entiteiten). Wordt aangemaakt onder `/audits/{group_audit_id}/component-audits/` |
| **Gekoppelde audit / auditnetwerk**        | Een audit die is gekoppeld aan één of meer geconsolideerde component audits, zodat werkzaamheden en data-objecten over opdrachten kunnen worden gedeeld           |

{% hint style="info" %}
In de Engyon-applicatie worden component audits vaak **controle-eenheden** genoemd. In de API worden ze aangemaakt en opgehaald als **component audits**.
{% endhint %}

### Overzicht van de flows

#### A. Een enkelvoudige audit aanmaken

1. Werkpakketten (en gerelateerde instellingen) ophalen
2. Controleren dat de klantorganisatie en juridische entiteit bestaan
3. `POST /api/v1/audits/` met `audit_type: "single"`
4. Pollen tot `status` gelijk is aan `open`
5. (Optioneel) Gebruikers toewijzen aan de audit

#### B. Een groepscontrole met component audits aanmaken

1. Het groepsdossier aanmaken met `audit_type: "consolidated"`
2. Wachten tot de status `open` is
3. Component audits aanmaken voor de relevante juridische entiteiten
4. (Optioneel) Een aparte audit aanmaken en die koppelen aan component audits

### Vereisten — gegevens die je nodig hebt voordat je een audit aanmaakt

| Nodig                                   | Endpoint                                                 | Te gebruiken veld                                                         |
| --------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------- |
| Werkpakket                              | `GET /api/v1/work-packages/`                             | `id` (identificatie van het methodiekpakket)                              |
| Scoping package                         | Zelfde response → `scoping_packages`                     | Gebruik een label uit die lijst als `scoping_package_id`                  |
| Talen / audittypes / instellingen       | Zelfde response → `languages`, `audit_types`, `settings` | Kies een ondersteunde `language`; map setting-id’s naar `settings`        |
| Klantorganisatie                        | `GET /api/v1/client-organisations/`                      | `client_organisation_id`                                                  |
| Juridische entiteit                     | `GET /api/v1/client-organisations/{id}/legal-entities/`  | `legal_entity_id` (root is vaak gelijk aan de id van de klantorganisatie) |
| Auditrollen (voor gebruikerstoewijzing) | `GET /api/v1/roles/?associated_model=Audit`              | Rolnamen zoals `audit_auditor`                                            |

#### Werkpakketten ophalen

```bash
curl -X GET "https://audit.engyon.io/api/v1/work-packages/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Elk werkpakket bevat onder andere:

| Veld               | Beschrijving                                                    |
| ------------------ | --------------------------------------------------------------- |
| `id`               | Werkpakket-id om als `work_package_id` mee te sturen            |
| `name`             | Weergavenaam                                                    |
| `version`          | Versiestring                                                    |
| `languages`        | Talen die voor dit pakket beschikbaar zijn                      |
| `audit_types`      | Ondersteunde audittypes voor prijzen/voorwaarden                |
| `scoping_packages` | Labels die je als `scoping_package_id` mag gebruiken            |
| `settings`         | Definities van instellingen (`id`, naam, type, default, opties) |
| `prices`           | Creditprijzen met associatievoorwaarden                         |

{% hint style="info" %}
Selecteer altijd het nieuwste werkpakket dat voor je organisatie beschikbaar is, ook als de financiële periode die je controleert eerder valt.
{% endhint %}

### Een audit aanmaken

```
POST /api/v1/audits/
```

#### Requestvelden

| Veld                          | Type      | Verplicht | Beschrijving                                                                                                     |
| ----------------------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `id`                          | string    | nee       | Externe id. Uniek binnen je auditororganisatie. Onwijzigbaar na aanmaken.                                        |
| `name`                        | string    | ja        | Auditnaam (max. 100 tekens)                                                                                      |
| `work_package_id`             | string    | ja        | Werkpakket-`id` uit `GET /work-packages/`                                                                        |
| `scoping_package_id`          | string    | ja        | Scoping package-label voor het werkpakket en de taal                                                             |
| `client_organisation_id`      | string    | ja        | Externe id van de klantorganisatie                                                                               |
| `legal_entity_id`             | string    | ja        | Externe id van de juridische entiteit binnen die klant                                                           |
| `period_start`                | date      | ja        | Start van de auditperiode (`YYYY-MM-DD`, inclusief)                                                              |
| `period_end`                  | date      | ja        | Einde van de auditperiode (`YYYY-MM-DD`, inclusief)                                                              |
| `language`                    | string    | ja        | Een van `en-us`, `nl`, `it` (moet beschikbaar zijn op het werkpakket)                                            |
| `unit_of_measurement`         | string    | nee       | Meeteenheid voor bedragen (bij financiële audits is dit doorgaans de valuta; gebruik dan de ISO 4217-valutacode) |
| `audit_type`                  | string    | nee       | `"single"` (standaard) of `"consolidated"`                                                                       |
| `coupled_component_audit_ids` | string\[] | nee       | Externe id’s van geconsolideerde **component** audits om bij aanmaken te koppelen (zie Koppelen)                 |
| `settings`                    | object    | nee       | Map van werkpakket-setting-id → waarde                                                                           |

#### Voorbeeld — enkelvoudige audit voor Fictiva Holding

```bash
curl -X POST "https://audit.engyon.io/api/v1/audits/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "fictiva-audit-2025",
    "name": "Fictiva Audit 2025",
    "work_package_id": "YOUR_WORK_PACKAGE_ID",
    "scoping_package_id": "YOUR_SCOPING_PACKAGE_LABEL",
    "client_organisation_id": "fictiva-holding",
    "legal_entity_id": "fictiva-holding",
    "period_start": "2025-01-01",
    "period_end": "2025-12-31",
    "language": "nl",
    "audit_type": "single"
  }'
```

#### Voorbeeld — groepscontrole (geconsolideerde audit)

```bash
curl -X POST "https://audit.engyon.io/api/v1/audits/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "fictiva-group-2025",
    "name": "Fictiva Groepsaudit 2025",
    "work_package_id": "YOUR_WORK_PACKAGE_ID",
    "scoping_package_id": "YOUR_SCOPING_PACKAGE_LABEL",
    "client_organisation_id": "fictiva-holding",
    "legal_entity_id": "fictiva-holding",
    "period_start": "2025-01-01",
    "period_end": "2025-12-31",
    "language": "nl",
    "audit_type": "consolidated"
  }'
```

#### Response (`201 Created`)

| Veld                          | Beschrijving                                                |
| ----------------------------- | ----------------------------------------------------------- |
| `id`                          | Externe id                                                  |
| `name`                        | Auditnaam                                                   |
| `work_package_id`             | Werkpakket-id                                               |
| `scoping_package_id`          | Scoping package-label                                       |
| `client_organisation_id`      | Externe id van de klantorganisatie                          |
| `legal_entity_ids`            | Juridische entiteiten op de controle-eenheid                |
| `period_start` / `period_end` | Auditperiode                                                |
| `language`                    | Taal                                                        |
| `unit_of_measurement`         | Meeteenheid                                                 |
| `settings`                    | Toegepaste instellingen                                     |
| `status`                      | `initializing`, `open`, `archived` of `deleting`            |
| `audit_type`                  | `single`, `consolidated` of `component`                     |
| `created_at`                  | Aanmaaktijdstip                                             |
| `group_audit_id`              | Ingesteld bij component audits                              |
| `coupled_component_audit_ids` | Id’s van gekoppelde component audits (op losstaande audits) |

#### Credits (`402`)

Het aanmaken van een audit kan credits verbruiken. Heeft de organisatie onvoldoende credits, dan retourneert de API **`402 Payment Required`**. Testklantorganisaties (`is_test_organisation: true`) verbruiken geen credits.

#### Initialisatie — pollen tot de audit klaar is

Het aanmaken van een audit loopt asynchroon door. De audit start doorgaans met `status: "initializing"`. Poll het detail-endpoint tot de status `open` is voordat je component audits aanmaakt of gebruikers toewijst.

```bash
curl -X GET "https://audit.engyon.io/api/v1/audits/fictiva-group-2025/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

{% hint style="warning" %}
Je kunt geen gebruikers toewijzen aan een audit zolang die nog initialiseert, gearchiveerd is, of wordt verwijderd. Wacht tot `status` gelijk is aan `open`.
{% endhint %}

{% hint style="info" %}
Let op bij het *list*-endpoint: `GET /api/v1/audits/` geeft alleen **top-level** audits terug (`single` en `consolidated`). Component audits staan onder het `/component-audits/`-endpoint van het groepsdossier.
{% endhint %}

### Component audits aanmaken (groepscontroles)

Nadat een geconsolideerd groepsdossier `open` is, maak je component audits aan voor de juridische entiteiten in scope.

```
POST /api/v1/audits/{group_audit_id}/component-audits/
```

#### Requestvelden

| Veld                 | Type      | Verplicht | Beschrijving                                                                                                                                                          |
| -------------------- | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legal_entity_ids`   | string\[] | ja        | Minstens één juridische-entiteit-id die bij de klant van het groepsdossier hoort. De volgorde blijft behouden; de eerste entiteit is de primaire juridische entiteit. |
| `name`               | string    | nee       | Weergavenaam. Standaard de namen van de juridische entiteiten, gekoppeld met `&`.                                                                                     |
| `country`            | string    | nee       | ISO-landcode. Standaard het land van de eerste juridische entiteit.                                                                                                   |
| `auditor_relation`   | string    | ja        | `"self"` (groepsaccountant), `"inter_office"` of `"inter_firm"`                                                                                                       |
| `component_settings` | object    | nee       | Ondersteunt momenteel `component_auditor_works_in_audit` (boolean). Mag alleen `true` zijn wanneer `auditor_relation` `inter_office` of `inter_firm` is.              |

#### Voorbeeld — component voor Fictiva Holding (groepsaccountant)

```bash
curl -X POST "https://audit.engyon.io/api/v1/audits/fictiva-group-2025/component-audits/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "legal_entity_ids": ["fictiva-holding"],
    "name": "Fictiva Holding",
    "auditor_relation": "self"
  }'
```

#### Voorbeeld — component voor Fictiva Dochter

```bash
curl -X POST "https://audit.engyon.io/api/v1/audits/fictiva-group-2025/component-audits/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "legal_entity_ids": ["fictiva-dochter"],
    "name": "Fictiva Dochter",
    "auditor_relation": "self"
  }'
```

#### Responsevelden

| Veld                       | Beschrijving                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------ |
| `id`                       | Externe id van de component audit — bewaar deze als je later een audit wilt koppelen |
| `name`                     | Weergavenaam                                                                         |
| `legal_entity_ids`         | Juridische entiteiten in de component                                                |
| `in_scope`                 | Of de component in scope is                                                          |
| `out_of_scope_explanation` | Toelichting wanneer de component out of scope is gezet                               |
| `auditor_relation`         | `self`, `inter_office` of `inter_firm`                                               |
| `status`                   | Lifecycle-status                                                                     |
| `coupled_entity_audit_id`  | Externe id van een gekoppelde audit, indien aanwezig                                 |

#### Een component out of scope zetten

```
PATCH /api/v1/audits/{group_audit_id}/component-audits/{component_audit_id}/
```

Zet `in_scope` op `false` en geef `out_of_scope_explanation` mee. Dit wist de inhoud van de component en is geblokkeerd als het groepsdossier is gearchiveerd of de scope is vergrendeld.

### Een audit koppelen aan component audits (auditnetwerk)

In Engyon kun je een aparte audit koppelen aan één of meer geconsolideerde **component audits**. Zo bouw je een **auditnetwerk**: werkzaamheden en data-objecten uit het groepsdossier kunnen ook gelden voor het gekoppelde dossier.

#### Koppelen kan alleen bij aanmaken

{% hint style="danger" %}
**Belangrijke beperking:** Koppelen kan alleen wanneer je de audit **aanmaakt**, door `coupled_component_audit_ids` mee te geven in het `POST /api/v1/audits/`-request.

Er is **geen** API-endpoint om een bestaande audit achteraf aan component audits te koppelen. Maak je de audit aan zonder `coupled_component_audit_ids`, dan kun je de koppeling later niet via de API toevoegen.
{% endhint %}

Plan het netwerk voordat je de audit aanmaakt:

1. Maak het groepsdossier (geconsolideerde audit) aan
2. Maak de component audits aan die je wilt koppelen
3. Noteer hun component audit-`id`-waarden
4. Maak de audit **in hetzelfde request** aan met `coupled_component_audit_ids`

{% hint style="info" %}
Als een audit moet worden gekoppeld aan meerdere component audits (bij een complexe “kerstboomstructuur”), kun je meerdere component audit-id’s doorgeven in de `coupled_component_audit_ids`-array. In dat geval moeten die component audits eerst zijn aangemaakt. Bij dit soort complexe audits is de volgorde waarin je audits aanmaakt belangrijk.
{% endhint %}

#### Voorbeeld — een gekoppelde audit aanmaken

```bash
curl -X POST "https://audit.engyon.io/api/v1/audits/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "fictiva-dochter-entity-2025",
    "name": "Fictiva Dochter Audit 2025",
    "work_package_id": "YOUR_WORK_PACKAGE_ID",
    "scoping_package_id": "YOUR_SCOPING_PACKAGE_LABEL",
    "client_organisation_id": "fictiva-holding",
    "legal_entity_id": "fictiva-dochter",
    "period_start": "2025-01-01",
    "period_end": "2025-12-31",
    "language": "nl",
    "audit_type": "single",
    "coupled_component_audit_ids": [
      "COMPONENT_AUDIT_ID_FOR_FICTIVA_DOCHTER"
    ]
  }'
```

Je mag meer dan één component audit-id doorgeven wanneer je koppelt in een groter netwerk (bijvoorbeeld complexe kerstboomstructuren). Alle id’s in de lijst worden samen gevalideerd.

#### Koppelregels

De API handhaaft de volgende voorwaarden (validatie faalt met `400` als ze niet worden nageleefd):

* Elke id moet verwijzen naar een **geconsolideerde component** audit (niet naar een top-level single/consolidated audit)
* Dubbele id’s zijn niet toegestaan
* Components moeten tot hetzelfde auditnetwerk behoren
* Components mogen niet gearchiveerd of al gekoppeld zijn
* Components moeten hetzelfde werkpakket, scoping package, periode en de verwachte juridische-entiteitsvoorwaarden van het netwerk delen
* Elke component- / groepsjuridische-entiteitscontext moet precies één juridische entiteit bevatten waar de validator dat vereist
* (Bij meerdere gekoppelde component audits) De **initialiserende** component is degene waarvan de juridische entiteit van het groepsdossier het hoogst in de entiteitenboom staat
* De `client_organisation_id`, `legal_entity_id`, `work_package_id`, `scoping_package_id`, `period_start` en `period_end` in je request moeten **overeenkomen** met die initialiserende component audit
* Je service account heeft toestemming nodig om de niet-initialiserende components te koppelen (`update:audit.linked_entity_audit`, opgenomen in de API account manager-rol)

Wanneer het koppelen slaagt, sluit de nieuwe audit aan bij het bestaande auditnetwerk. Op de response van de audit zie je `coupled_component_audit_ids`. Op elke component zie je `coupled_entity_audit_id`.

### Gebruikers toewijzen aan een audit

Nadat de audit `open` is:

```
POST /api/v1/audits/{audit_id}/users/
```

| Veld   | Type   | Verplicht | Beschrijving                                                            |
| ------ | ------ | --------- | ----------------------------------------------------------------------- |
| `id`   | email  | ja        | E-mail van een bestaande gebruiker in je auditororganisatie             |
| `role` | string | ja        | Auditrolnaam, bijvoorbeeld `audit_auditor` of `audit_engagement_leader` |

```bash
curl -X POST "https://audit.engyon.io/api/v1/audits/fictiva-audit-2025/users/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "auditor@example.com",
    "role": "audit_auditor"
  }'
```

Beschikbare rollen vind je met:

```
GET /api/v1/roles/?associated_model=Audit
```

Werk toewijzingen bij of verwijder ze met `PATCH` / `DELETE` op `/api/v1/audits/{audit_id}/users/{user_id}/` (`user_id` = e-mail).

### Aanbevolen volgorde voor een Fictiva-groepsopdracht

1. Zorg dat klant `fictiva-holding` en juridische entiteit `fictiva-dochter` bestaan (Een klant aanmaken)
2. Doe `GET /work-packages/` en kies het nieuwste pakket + scoping package
3. Maak geconsolideerde audit `fictiva-group-2025` aan
4. Poll tot `status` gelijk is aan `open`
5. Maak component audits aan voor `fictiva-holding` en `fictiva-dochter`; bewaar hun `id`s
6. Als een aparte entiteitsopdracht nodig is, maak die aan **met** `coupled_component_audit_ids` in het create-request
7. Wijs het auditteam toe zodra de audits `open` zijn

### Gerelateerde endpoints

| Methode  | Pad                                                                |
| -------- | ------------------------------------------------------------------ |
| `GET`    | `/api/v1/work-packages/`                                           |
| `GET`    | `/api/v1/work-packages/{work_package_id}/`                         |
| `GET`    | `/api/v1/audits/`                                                  |
| `POST`   | `/api/v1/audits/`                                                  |
| `GET`    | `/api/v1/audits/{audit_id}/`                                       |
| `DELETE` | `/api/v1/audits/{audit_id}/`                                       |
| `GET`    | `/api/v1/audits/{audit_id}/component-audits/`                      |
| `POST`   | `/api/v1/audits/{audit_id}/component-audits/`                      |
| `PATCH`  | `/api/v1/audits/{audit_id}/component-audits/{component_audit_id}/` |
| `DELETE` | `/api/v1/audits/{audit_id}/component-audits/{component_audit_id}/` |
| `GET`    | `/api/v1/audits/{audit_id}/users/`                                 |
| `POST`   | `/api/v1/audits/{audit_id}/users/`                                 |
| `PATCH`  | `/api/v1/audits/{audit_id}/users/{user_id}/`                       |
| `DELETE` | `/api/v1/audits/{audit_id}/users/{user_id}/`                       |
| `GET`    | `/api/v1/roles/?associated_model=Audit`                            |

Voor aanvullende endpoints voor auditinhoud (bestanden, source records, scope, controles, risico’s), zie <https://audit.engyon.io/api/v1/docs/>.