> 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-klant-aanmaken.md). # Een klant aanmaken Deze use case laat zien hoe je via de API een **klantorganisatie** in Engyon opzet, inclusief klanten die uit meerdere juridische entiteiten bestaan, en hoe je gebruikers aan die klant toewijst. Op deze pagina gebruiken we **Fictiva Holding** als voorbeeldklant: een holding met een dochter, **Fictiva Dochter**. **Vereiste service account-rol:** API account manager (`api_account_manager`) ### Overzicht van de flow 1. (Optioneel) Industrieën en bestaande gebruikers/rollen opzoeken 2. De klantorganisatie aanmaken 3. Dochters (juridische entiteiten) onder de klant toevoegen 4. Gebruikers toewijzen aan de klantorganisatie ```mermaid sequenceDiagram participant I as Integratie participant API as Engyon API I->>API: POST /client-organisations/ API-->>I: Klant + root juridische entiteit I->>API: POST /client-organisations/{id}/legal-entities/ API-->>I: Dochter juridische entiteit I->>API: POST /client-organisations/{id}/users/ API-->>I: Gebruikerstoewijzing ``` ### Vereisten | Gegevens | Endpoint | Opmerkingen | | ----------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ | | Industrieën (optioneel) | `GET /api/v1/industries/` | Gebruik industrie-`id`-waarden in `industry_ids` | | Bestaande gebruikers | `GET /api/v1/users/` | Gebruikers moeten al in Engyon bestaan; geïdentificeerd via e-mail | | Klantrollen | `GET /api/v1/roles/?associated_model=ClientOrganisation` | Rolnamen zoals `client_manager` of `client_reader` | ```bash curl -X GET "https://audit.engyon.io/api/v1/industries/" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Accept: application/json" curl -X GET "https://audit.engyon.io/api/v1/roles/?associated_model=ClientOrganisation" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Accept: application/json" ``` ### 1. De klantorganisatie aanmaken ``` POST /api/v1/client-organisations/ ``` #### Requestvelden | Veld | Type | Verplicht | Beschrijving | | ---------------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | nee | Externe id. Uniek binnen je auditororganisatie. Onwijzigbaar na aanmaken. Indien weggelaten, dan genereert Engyon een id. | | `name` | string | ja | Weergavenaam van de klant | | `country` | string | ja | ISO 3166-1 alpha-2-landcode (bijvoorbeeld `NL`) | | `domains` | string\[] | nee | Logindomeinen voor de organisatie. Moeten uniek zijn binnen Engyon. | | `number` | string | nee | KvK-nummer / registratienummer | | `allow_password_login` | boolean | ja | Of gebruikers van deze klant mogen inloggen met e-mailadres en wachtwoord | | `industry_ids` | string\[] | nee | Externe id’s van industrieën | | `is_test_organisation` | boolean | nee | Bij `true` verbruiken audits voor deze klant geen credits en worden ze na een bewaartermijn verwijderd. Wordt geforceerd op `true` als je auditororganisatie zelf een testorganisatie is. Onwijzigbaar na aanmaken. | #### Voorbeeld ```bash curl -X POST "https://audit.engyon.io/api/v1/client-organisations/" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "id": "fictiva-holding", "name": "Fictiva Holding", "country": "NL", "domains": ["fictiva.example"], "number": "12345678", "allow_password_login": false, "is_test_organisation": true }' ``` #### Response (`201 Created`) ```json { "id": "fictiva-holding", "name": "Fictiva Holding", "country": "NL", "domains": ["fictiva.example"], "number": "12345678", "allow_password_login": false, "industry_ids": [], "is_test_organisation": true } ``` #### Belangrijk neveneffect: root juridische entiteit Wanneer een klantorganisatie wordt aangemaakt, maakt Engyon automatisch een ***root***** juridische entiteit** voor die klant aan met: * dezelfde **`id`** als de klantorganisatie (`fictiva-holding` in het voorbeeld) * overeenkomende naam, land en registratienummer Je maakt de *root* juridische entiteit **niet** zelf aan. Dochters voeg je in de volgende stap toe; die moeten verwijzen naar een bestaande *parent* (doorgaans deze *root*). #### Een klantorganisatie bijwerken ``` PATCH /api/v1/client-organisations/{client_organisation_id}/ ``` Je kunt `name`, `country`, `domains`, `number`, `allow_password_login` en `industry_ids` bijwerken. Je kunt `id` of `is_test_organisation` niet wijzigen. {% hint style="warning" %} Wanneer je `domains` opneemt in een PATCH-request, **vervangt** de lijst de logindomeinen van de organisatie volledig. Laat `domains` weg als je ze niet wilt wijzigen. {% endhint %} ### 2. Juridische entiteiten toevoegen (klanten met meerdere entiteiten) Een klant kan uit meerdere juridische entiteiten bestaan — bijvoorbeeld Fictiva Holding en Fictiva Dochter. Maak elke dochter aan onder de klantorganisatie. ``` POST /api/v1/client-organisations/{client_organisation_id}/legal-entities/ ``` #### Requestvelden | Veld | Type | Verplicht | Beschrijving | | ------------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------- | | `id` | string | nee | Externe id. Uniek binnen de klantorganisatie. Onwijzigbaar na aanmaken. | | `name` | string | ja | Weergavenaam | | `country` | string | ja | ISO 3166-1 alpha-2-landcode | | `is_active` | boolean | nee | Standaard `true` | | `introduction_date` | date | ja | Datum vanaf wanneer de entiteit relevant is (`YYYY-MM-DD`) | | `termination_date` | date | nee | Optionele einddatum | | `parent_id` | string | ja | Externe id van de parent juridische entiteit binnen dezelfde klant (gebruik de root-klant-id voor een directe dochter) | | `industry_ids` | string\[] | nee | Externe id’s van industrieën | #### Voorbeeld — Fictiva Dochter toevoegen onder Fictiva Holding ```bash curl -X POST "https://audit.engyon.io/api/v1/client-organisations/fictiva-holding/legal-entities/" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "id": "fictiva-dochter", "name": "Fictiva Dochter", "country": "NL", "introduction_date": "2020-01-01", "parent_id": "fictiva-holding" }' ``` #### Juridische entiteiten ophalen ```bash curl -X GET "https://audit.engyon.io/api/v1/client-organisations/fictiva-holding/legal-entities/" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Accept: application/json" ``` Je zou minstens moeten zien: * `fictiva-holding` — de *root* juridische entiteit * `fictiva-dochter` — de dochter die je hebt aangemaakt #### Verwijderregels * Alleen **dochter**-juridische entiteiten (met een *parent*) kunnen worden verwijderd. * Verwijderen mislukt met `409 Conflict` als de juridische entiteit in een audit wordt gebruikt. ### 3. Gebruikers toewijzen aan de klantorganisatie Gebruikers moeten al in Engyon bestaan. De API wijst een bestaande gebruiker toe aan de klant; ze nodigt geen volledig nieuwe persoon uit per e-mail zoals de UI-uitnodigingsflow dat soms doet. Het beoogde gebruik is om gebruikers van je auditororganisatie aan de klant toe te wijzen. ``` POST /api/v1/client-organisations/{client_organisation_id}/users/ ``` #### Requestvelden | Veld | Type | Verplicht | Beschrijving | | ------------------ | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | `id` | email | ja | E-mailadres van de bestaande gebruiker | | `role` | string | ja | App-rol voor klantorganisaties, bijvoorbeeld `client_manager` of `client_reader`. Geef hier **geen** administrator-rolnamen door. | | `is_administrator` | boolean | ja | Bij `true` krijgt de gebruiker ook beheerdersrechten op de klant | Beschikbare rolnamen vind je met: ``` GET /api/v1/roles/?associated_model=ClientOrganisation ``` #### Voorbeeld ```bash curl -X POST "https://audit.engyon.io/api/v1/client-organisations/fictiva-holding/users/" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "id": "partner@example.com", "role": "client_manager", "is_administrator": true }' ``` #### Response (`201 Created`) Typische velden zijn onder andere: | Veld | Beschrijving | | ------------------ | ----------------------------------------------------------------------- | | `id` | E-mail van de gebruiker | | `name` | Weergavenaam | | `role` | Toegewezen niet-administratorrol | | `is_administrator` | Of beheerdersrechten zijn toegekend | | `is_client` | `true` als de hoofdorganisatie van de gebruiker een klantorganisatie is | | `has_mfa_setup` | Of de gebruiker MFA heeft ingesteld | #### Een toewijzing bijwerken of verwijderen | Methode | Pad | Beschrijving | | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | | `PATCH` | `/api/v1/client-organisations/{id}/users/{user_id}/` | `role` en/of `is_administrator` bijwerken | | `DELETE` | `/api/v1/client-organisations/{id}/users/{user_id}/` | De toewijzing verwijderen (verwijdert het gebruikersaccount niet) | `{user_id}` is het e-mailadres van de gebruiker (niet hoofdlettergevoelig). ### Aanbevolen volgorde voor Fictiva 1. Maak klant `fictiva-holding` aan 2. Maak juridische entiteit `fictiva-dochter` aan met `parent_id: "fictiva-holding"` 3. Wijs de teamleden toe die toegang op klantniveau nodig hebben 4. Ga verder met Een audit aanmaken met `client_organisation_id: "fictiva-holding"` en de juiste `legal_entity_id` ### Gerelateerde endpoints | Methode | Pad | | -------- | ----------------------------------------------------------------------------------------- | | `GET` | `/api/v1/client-organisations/` | | `POST` | `/api/v1/client-organisations/` | | `GET` | `/api/v1/client-organisations/{client_organisation_id}/` | | `PATCH` | `/api/v1/client-organisations/{client_organisation_id}/` | | `GET` | `/api/v1/client-organisations/{client_organisation_id}/legal-entities/` | | `POST` | `/api/v1/client-organisations/{client_organisation_id}/legal-entities/` | | `GET` | `/api/v1/client-organisations/{client_organisation_id}/legal-entities/{legal_entity_id}/` | | `PATCH` | `/api/v1/client-organisations/{client_organisation_id}/legal-entities/{legal_entity_id}/` | | `DELETE` | `/api/v1/client-organisations/{client_organisation_id}/legal-entities/{legal_entity_id}/` | | `GET` | `/api/v1/client-organisations/{client_organisation_id}/users/` | | `POST` | `/api/v1/client-organisations/{client_organisation_id}/users/` | | `PATCH` | `/api/v1/client-organisations/{client_organisation_id}/users/{user_id}/` | | `DELETE` | `/api/v1/client-organisations/{client_organisation_id}/users/{user_id}/` |