> For the complete documentation index, see [llms.txt](https://docs.cootje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cootje.com/cootje-api/rollen-en-rechten.md).

# Rollen & Rechten

Alle rollen en rechten in Cootje met hun waarden en betekenis, de standaardrechten per rol en hoe je ze opvraagt en wijzigt.

In Cootje zegt een rol wat iemand bij een bedrijf is, bijvoorbeeld professional of tekenbevoegde. Een recht zegt wat iemand mag zien of doen. In de API zijn rollen en rechten getallen. Op deze pagina staan alle waarden met hun betekenis.

## Hoe het werkt

* Een persoon hoort bij een bedrijf via een koppeling. Die koppeling heeft twee lijsten: `roles` met de rollen en `permissions` met de rechten.
* Er zijn twee niveaus. Een koppeling met een bedrijf geeft rechten **bij dat ene bedrijf**. Een koppeling met de vaste waarde `Whitelabel` op de plek van het bedrijf geeft rechten **voor de hele omgeving**, dus voor alle bedrijven.
* De vaste waarde `TAO` op de plek van het bedrijf is voor medewerkers die bij jullie in loondienst zijn.
* De API kent bij een rol niet vanzelf rechten toe. Je stuurt de rechten zelf mee in `permissions`. Welke rechten Cootje zelf bij een rol gebruikt, staat verderop onder "Standaardrechten per rol".
* Het recht dat op de andere pagina's bij "Vereist recht" staat, is in de regel een recht voor de hele omgeving. Een API-account krijgt dat recht via een koppeling met `Whitelabel`.

## Rollen

| Waarde | Rol                   | Betekenis                                                                                     | Bij een bedrijf | Voor de hele omgeving |
| ------ | --------------------- | --------------------------------------------------------------------------------------------- | --------------- | --------------------- |
| `1`    | Eigenaar              | Beheert de gegevens van het bedrijf: bedrijfsgegevens, documenten, bankrekeningen en personen | ja              | ja                    |
| `2`    | Tekenbevoegde         | Ondertekent contracten namens het bedrijf                                                     | ja              | ja                    |
| `3`    | Professional          | Voert het werk uit en registreert uren                                                        | ja              | ja                    |
| `4`    | Urenverantwoordelijke | Keurt de uren van een professional goed                                                       | ja              | ja                    |
| `5`    | Recruiter             | Beheert vacatures en kandidaten                                                               | ja              | ja                    |
| `6`    | Zorgcoördinator       | Beheert de planning                                                                           | nee             | ja                    |

Eén persoon kan bij hetzelfde bedrijf meerdere rollen hebben. Een zzp'er heeft bij zijn eigen bedrijf bijvoorbeeld de rollen `[1, 2, 3]`.

## Rechten bij een bedrijf

Deze rechten gelden alleen bij het bedrijf waaraan de persoon gekoppeld is.

| Waarde | Recht                                              | Betekenis                                                                                 |
| ------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `300`  | Bedrijfsinformatie inzien                          | Alle gegevens van dit bedrijf bekijken                                                    |
| `305`  | Documenten inzien                                  | Alle documenten van dit bedrijf bekijken                                                  |
| `306`  | Documenten aanleveren                              | Documenten aanleveren voor dit bedrijf                                                    |
| `307`  | Documenten goedkeuren                              | Documenten van dit bedrijf goedkeuren                                                     |
| `308`  | Bankgegevens inzien                                | De bankrekeningen van dit bedrijf bekijken                                                |
| `309`  | Bankgegevens bewerken                              | De bankrekeningen van dit bedrijf wijzigen                                                |
| `310`  | Facturen inzien                                    | De facturen van dit bedrijf bekijken                                                      |
| `400`  | Alle personen kunnen inzien                        | Alle personen bekijken die aan dit bedrijf gekoppeld zijn                                 |
| `402`  | Eigen profiel kunnen lezen                         | De eigen persoonsgegevens bekijken                                                        |
| `403`  | Eigen profiel kunnen bewerken                      | De eigen persoonsgegevens wijzigen                                                        |
| `500`  | Alle contracten van het bedrijf kunnen inzien      | Alle contracten van dit bedrijf bekijken, met documenten, opdracht en financiële gegevens |
| `503`  | Contracten inzien waaraan u bent gekoppeld         | Alleen de contracten bekijken waarin de persoon zelf een rol heeft                        |
| `504`  | Financiële gegevens van het contract kunnen inzien | De financiële gegevens van contracten van dit bedrijf bekijken                            |
| `505`  | Timesheets: alle van het bedrijf kunnen inzien     | Alle geregistreerde uren en declaraties van dit bedrijf bekijken                          |
| `506`  | Timesheets: gerelateerde kunnen inzien             | Alleen de uren bekijken van contracten waarin de persoon zelf een rol heeft               |
| `507`  | Timesheets: alle van het bedrijf kunnen indienen   | Uren en declaraties indienen voor alle professionals van dit bedrijf                      |

## Rechten voor de hele omgeving

Deze rechten gelden voor alle bedrijven in de omgeving. Je geeft ze via een koppeling met de vaste waarde `Whitelabel`.

### Recruitment

| Waarde | Recht                     | Betekenis                                    |
| ------ | ------------------------- | -------------------------------------------- |
| `100`  | Alle kandidaten inzien    | Alle kandidaten bekijken                     |
| `101`  | Alle kandidaten bewerken  | Kandidaten aanmaken, wijzigen en verwijderen |
| `200`  | Alle vacatures inzien     | Alle vacatures bekijken                      |
| `201`  | Alle vacatures bewerken   | Vacatures aanmaken, wijzigen en verwijderen  |
| `202`  | Alle vacatures publiceren | Vacatures publiceren en depubliceren         |

### Bedrijven, documenten en personen

| Waarde | Recht                       | Betekenis                                                                                      |
| ------ | --------------------------- | ---------------------------------------------------------------------------------------------- |
| `300`  | Bedrijfsinformatie inzien   | De gegevens van alle bedrijven bekijken                                                        |
| `301`  | Bedrijfsinformatie bewerken | Bedrijven aanmaken, wijzigen en verwijderen                                                    |
| `305`  | Documenten inzien           | De documenten van alle bedrijven bekijken                                                      |
| `306`  | Documenten aanleveren       | Documenten aanleveren voor alle bedrijven                                                      |
| `307`  | Documenten goedkeuren       | Documenten van alle bedrijven goedkeuren                                                       |
| `308`  | Bankgegevens inzien         | De bankrekeningen van alle bedrijven bekijken                                                  |
| `309`  | Bankgegevens bewerken       | De bankrekeningen van alle bedrijven wijzigen                                                  |
| `310`  | Facturen inzien             | De facturen van alle bedrijven bekijken                                                        |
| `400`  | Personen kunnen inzien      | Alle personen bekijken                                                                         |
| `401`  | Personen kunnen bewerken    | Personen aanmaken, wijzigen en verwijderen, en hun rollen en rechten bij een bedrijf instellen |

### Contracten en uren

| Waarde | Recht                                              | Betekenis                                                            |
| ------ | -------------------------------------------------- | -------------------------------------------------------------------- |
| `500`  | Contracten kunnen inzien                           | Contracten bekijken, met documenten, opdracht en financiële gegevens |
| `501`  | Contracten kunnen bewerken                         | Contracten aanmaken en wijzigen                                      |
| `504`  | Financiële gegevens van het contract kunnen inzien | De financiële gegevens van contracten bekijken                       |
| `505`  | Geregistreerde uren inzien                         | De geregistreerde uren van contracten bekijken                       |

### Planning, overzichten en beheer

| Waarde  | Recht                          | Betekenis                                                                                            |
| ------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `700`   | Behoevenden kunnen beheren     | Behoevenden in de planning beheren                                                                   |
| `701`   | Behoeftes kunnen beheren       | Behoeftes in de planning beheren                                                                     |
| `702`   | Behoevenden kunnen inzien      | Behoevenden in de planning bekijken                                                                  |
| `600`   | Procesbewaking                 | De procesbewaking bekijken                                                                           |
| `601`   | Statistieken                   | Statistieken bekijken en dashboards samenstellen en delen                                            |
| `10000` | Cootje Eigenaar Module         | De gegevens van de eigenaar van de omgeving beheren, en rollen en rechten van personen bij bedrijven |
| `10001` | E-mail Module                  | De standaardteksten van e-mails beheren                                                              |
| `10002` | Documenten Module              | Documentenlijsten, formulieren en pdf-sjablonen beheren                                              |
| `10003` | Beheerders (gebruikers) Module | De beheerders van de omgeving beheren                                                                |
| `10004` | Contracten Module              | De standaardinstellingen voor contracten beheren                                                     |
| `10005` | API Koppelingen Module         | De koppelingen met andere systemen beheren                                                           |
| `10006` | Facturatie Module              | De instellingen voor facturen beheren                                                                |

## Standaardrechten per rol

Cootje gebruikt zelf deze rechten als iemand in de webapplicatie of via een uitnodiging een rol krijgt. Via de API stuur je ze zelf mee.

Bij een bedrijf:

| Rol                       | Rechten                                                              |
| ------------------------- | -------------------------------------------------------------------- |
| `1` Eigenaar              | `300`, `305`, `306`, `308`, `309`, `310`, `400`, `403`, `500`, `505` |
| `2` Tekenbevoegde         | `503`, `310`                                                         |
| `3` Professional          | `506`, `503`, `402`                                                  |
| `4` Urenverantwoordelijke | `506`, `503`                                                         |
| `5` Recruiter             | `100`, `101`, `200`, `201`, `202`, `300`, `301`                      |

Voor de hele omgeving:

| Rol                       | Rechten                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `1` Eigenaar              | `300`, `301`, `305`, `306`, `307`, `308`, `309`, `310`, `400`, `401`, `500`, `501`, `504`, `505`, `10000`, `10001`, `10002`, `10004` |
| `2` Tekenbevoegde         | `500`, `504`, `310`                                                                                                                  |
| `3` Professional          | `506`, `402`                                                                                                                         |
| `4` Urenverantwoordelijke | geen                                                                                                                                 |
| `5` Recruiter             | `100`, `101`, `200`, `201`, `202`, `300`, `301`                                                                                      |
| `6` Zorgcoördinator       | `700`, `701`, `702`                                                                                                                  |

## Rollen en rechten van een persoon opvragen

* **Aanroep:** `GET /organizations/memberships/persons/{personId}`
* **Vereist recht:** Personen kunnen inzien
* **Verplicht:** `personId` in de URL, het `_id` van de persoon
* **Optioneel:** niets

```bash
curl "https://mijn.cootje.com/api/organizations/memberships/persons/5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

### Wat je terugkrijgt

Eén regel per koppeling. In dit voorbeeld is de persoon professional bij één bedrijf en heeft hij daarnaast rechten voor de hele omgeving:

```json
[
  {
    "_id": "4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b",
    "companyId": "c2d3e4f5-6a7b-4c8d-9e0f-1b2c3d4e5f6a",
    "personId": "5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d",
    "roles": [
      3
    ],
    "permissions": [
      506,
      503,
      402
    ]
  },
  {
    "_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "companyId": "Whitelabel",
    "personId": "5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d",
    "roles": [
      5
    ],
    "permissions": [
      100,
      101,
      200,
      201,
      202,
      300,
      301
    ]
  }
]
```

* `_id` is het kenmerk van de koppeling. Dat gebruik je om de koppeling te wijzigen.
* `companyId` is het `_id` van het bedrijf, of de vaste waarde `Whitelabel` of `TAO`.

## Rollen en rechten wijzigen

* **Aanroep:** `PUT /organizations/memberships/companies/{companyId}/{membershipId}`
* **Vereist recht:** Personen kunnen bewerken

De aanroep vervangt beide lijsten. Stuur dus altijd alle rollen en alle rechten mee die de persoon moet houden.

### Verplichte velden

| Veld           | Soort            | Toelichting                                                                                               |
| -------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `companyId`    | tekst, in de URL | Het `_id` van het bedrijf, of `Whitelabel` of `TAO`. Dit moet het bedrijf van de bestaande koppeling zijn |
| `membershipId` | tekst, in de URL | Het `_id` van de koppeling                                                                                |

### Optionele velden

| Veld          | Soort | Toelichting                                                                                                                         |
| ------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `roles`       | lijst | De rollen, als getallen uit de tabel "Rollen" hierboven. Laat je dit weg, dan heeft de persoon daarna geen rol meer bij dit bedrijf |
| `permissions` | lijst | De rechten, als getallen uit de tabellen hierboven. Laat je dit weg, dan heeft de persoon daarna geen rechten meer bij dit bedrijf  |

### Voorbeeld

In dit voorbeeld krijgt een professional er de rol tekenbevoegde bij, met de rechten van beide rollen:

```bash
curl -X PUT "https://mijn.cootje.com/api/organizations/memberships/companies/c2d3e4f5-6a7b-4c8d-9e0f-1b2c3d4e5f6a/4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": [
      2,
      3
    ],
    "permissions": [
      506,
      503,
      402,
      310
    ]
  }'
```

### Wat je terugkrijgt

Niets: bij een geslaagde wijziging heeft het antwoord geen inhoud. Klopt de invoer niet, dan is het antwoord een lijst met fouten:

```json
[
  {
    "propertyName": "",
    "errorMessage": "Lidmaatschap bestaat niet"
  }
]
```

## Antwoorden

| Code  | Betekenis                                                           |
| ----- | ------------------------------------------------------------------- |
| `200` | De lijst met koppelingen                                            |
| `204` | De rollen en rechten zijn gewijzigd. Het antwoord heeft geen inhoud |
| `400` | De invoer klopt niet. Het antwoord is de lijst met fouten           |
| `401` | Geen geldig token, of het account mist het recht                    |
