> 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/tijdelijke-arbeidsovereenkomst/medewerker-vastleggen.md).

# Medewerker vastleggen

Een medewerker in loondienst vastleggen, met de gegevens die een TAO-contract nodig heeft.

Een medewerker met een tijdelijke arbeidsovereenkomst komt bij jullie in loondienst. Hij hoort daarom niet bij een leverancier: je legt hem vast als persoon en koppelt hem aan de vaste waarde `TAO`.

* **Vereist recht:** Personen kunnen bewerken

Bestaat de persoon nog niet in Cootje, gebruik dan de eerste aanroep. Staat de persoon er al in, bijvoorbeeld bij een ander bedrijf, gebruik dan de tweede.

## Nieuwe persoon toevoegen

* **Aanroep:** `POST /organizations/persons`

Je maakt de persoon aan en koppelt hem in dezelfde aanroep aan de vaste waarde `TAO`.

### Verplichte velden

| Veld                   | Soort | Toelichting                                                                        |
| ---------------------- | ----- | ---------------------------------------------------------------------------------- |
| `person.firstName`     | tekst | Voornaam                                                                           |
| `person.lastName`      | tekst | Achternaam                                                                         |
| `person.initials`      | tekst | Voorletters                                                                        |
| `person.email`         | tekst | Een geldig e-mailadres dat nog niet bij een andere persoon in de omgeving voorkomt |
| `membership.companyId` | tekst | De vaste waarde `TAO`                                                              |
| `membership.roles`     | lijst | De rol van de persoon bij het bedrijf: `3` professional                            |

### Verplicht in bepaalde gevallen

| Situatie                                                  | Dan verplicht                                           |
| --------------------------------------------------------- | ------------------------------------------------------- |
| Je vult een deel van het adres in (`person.address`)      | `street`, `houseNumber`, `zipcode` en `city`, alle vier |
| De nationaliteit is Nederlands en je vult `person.bsn` in | Een geldig burgerservicenummer                          |

### Optionele velden

| Veld                     | Soort             | Toelichting                                                                                                                                     |
| ------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `membership.permissions` | lijst             | De rechten van de persoon bij het bedrijf, als getallen. Laat je dit weg, dan heeft de persoon de rol maar geen rechten. Zie de tabel hieronder |
| `person.tussenvoegsel`   | tekst             | Tussenvoegsel, zoals "van der"                                                                                                                  |
| `person.gender`          | getal             | `1` man, `2` vrouw                                                                                                                              |
| `person.phoneNumber`     | tekst             | Telefoonnummer                                                                                                                                  |
| `person.address`         | object            | Adres: `street`, `houseNumber`, `houseNumberAddition`, `zipcode`, `city` en `country`                                                           |
| `person.dateOfBirth`     | tekst             | Geboortedatum                                                                                                                                   |
| `person.nationality`     | tekst             | Nationaliteit                                                                                                                                   |
| `person.bsn`             | tekst             | Burgerservicenummer                                                                                                                             |
| `person.maritalStatus`   | tekst             | Burgerlijke staat                                                                                                                               |
| `person.function`        | tekst             | Functie                                                                                                                                         |
| `person.isApiAccount`    | ja/nee            | `true` voor een account dat alleen voor een koppeling is bedoeld. Standaard `false`                                                             |
| `acceptAddressWarnings`  | ja/nee, in de URL | `true` om de persoon ook op te slaan als het adres niet bevestigd kan worden                                                                    |

Zonder `country` in het adres wordt het land `NL`.

### Rechten bij deze rol

Cootje kent de rechten niet vanzelf toe. Stuur ze mee in `membership.permissions`. Dit zijn de rechten die Cootje zelf bij deze rol gebruikt:

| Getal | Recht                                             |
| ----- | ------------------------------------------------- |
| `506` | Urenstaten inzien waaraan de persoon gekoppeld is |
| `503` | Contracten inzien waaraan de persoon gekoppeld is |
| `402` | Eigen profiel lezen                               |

### Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/persons" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "firstName": "Sanne",
      "tussenvoegsel": "de",
      "lastName": "Vries",
      "initials": "S.",
      "email": "sanne@voorbeeld.nl",
      "phoneNumber": "0612345678",
      "dateOfBirth": "1990-05-14",
      "nationality": "Nederlandse",
      "bsn": "111222333",
      "address": {
        "street": "Voorbeeldstraat",
        "houseNumber": "12",
        "zipcode": "3511 AB",
        "city": "Utrecht",
        "country": "NL"
      }
    },
    "membership": {
      "companyId": "TAO",
      "roles": [
        3
      ],
      "permissions": [
        506,
        503,
        402
      ]
    },
    "bankAccount": {
      "iban": "NL91ABNA0417164300",
      "type": 1
    }
  }'
```

### Wat je terugkrijgt

De aangemaakte persoon, met het nieuwe `_id`. De koppeling met het bedrijf en de bankrekening staan niet in het antwoord:

```json
{
  "_id": "5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d",
  "createdAt": 1799746200000,
  "firstName": "Sanne",
  "tussenvoegsel": "de",
  "lastName": "Vries",
  "initials": "S.",
  "gender": null,
  "email": "sanne@voorbeeld.nl",
  "phoneNumber": "0612345678",
  "address": {
    "street": "Voorbeeldstraat",
    "houseNumber": "12",
    "houseNumberAddition": "",
    "city": "Utrecht",
    "zipcode": "3511 AB",
    "country": "NL"
  },
  "bsn": "111222333",
  "dateOfBirth": "1990-05-14",
  "nationality": "Nederlandse",
  "maritalStatus": "",
  "function": "",
  "isApiAccount": false,
  "displayName": "Sanne de Vries",
  "displayLastName": "de Vries"
}
```

Klopt de invoer niet (`400`) of kan het adres niet bevestigd worden (`422`), dan is het antwoord een lijst met bevindingen en is de persoon niet opgeslagen:

```json
[
  {
    "propertyName": "FirstName",
    "errorMessage": "Voornaam is verplicht"
  }
]
```

## Bestaande persoon koppelen

* **Aanroep:** `POST /organizations/memberships/companies/{companyId}/persons/{personId}`

### Verplichte velden

| Veld        | Soort            | Toelichting                                             |
| ----------- | ---------------- | ------------------------------------------------------- |
| `companyId` | tekst, in de URL | De vaste waarde `TAO`                                   |
| `personId`  | tekst, in de URL | Het `_id` van de persoon                                |
| `roles`     | lijst            | De rol van de persoon bij het bedrijf: `3` professional |

### Optionele velden

| Veld          | Soort | Toelichting                                                                                                                                    |
| ------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `permissions` | lijst | De rechten van de persoon bij het bedrijf, als getallen uit de tabel hierboven. Laat je dit weg, dan heeft de persoon de rol maar geen rechten |

### Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/memberships/companies/TAO/persons/5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": [
      3
    ],
    "permissions": [
      506,
      503,
      402
    ]
  }'
```

### Wat je terugkrijgt

De koppeling tussen de persoon en het bedrijf:

```json
{
  "_id": "4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b",
  "companyId": "TAO",
  "personId": "5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d",
  "roles": [
    3
  ],
  "permissions": [
    506,
    503,
    402
  ]
}
```

Bestaat het bedrijf of de persoon niet, dan is het antwoord een lijst met fouten:

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

## Nodig voor een TAO-contract

De aanroep hierboven dwingt deze gegevens niet af, maar zonder kan het contract van de medewerker later niet definitief worden:

| Gegeven                                     | Veld                                                  |
| ------------------------------------------- | ----------------------------------------------------- |
| Naam en e-mailadres                         | `person.firstName`, `person.lastName`, `person.email` |
| Geboortedatum                               | `person.dateOfBirth`                                  |
| Een geldig burgerservicenummer              | `person.bsn`                                          |
| Een gewone bankrekening met een geldig IBAN | `bankAccount` met `type` `1`                          |

## Goed om te weten

* De waarde `TAO` is geen `_id` van een bedrijf, maar een vaste aanduiding voor medewerkers in loondienst.
* Geef de bankrekening meteen mee. Staat de medewerker al in Cootje, voeg de rekening dan toe met `POST /organizations/persons/{id}/bankaccount`.
* Een nieuwe persoon kan nog niet inloggen. Bij het definitief maken van het contract maakt Cootje vanzelf een inlog aan en krijgt de medewerker een e-mail om een wachtwoord in te stellen.
* Daarna leg je de afspraken vast in een contract. Zie [Concept contract opmaken](https://docs.cootje.com/cootje-api/tijdelijke-arbeidsovereenkomst/concept-contract-opmaken.md).

## Antwoorden

| Code  | Betekenis                                                                                 |
| ----- | ----------------------------------------------------------------------------------------- |
| `200` | De aangemaakte persoon, of de koppeling                                                   |
| `400` | De invoer klopt niet. Het antwoord is de lijst met fouten                                 |
| `401` | Geen geldig token, of het account mist het recht                                          |
| `422` | Het adres van een nieuwe persoon kon niet bevestigd worden. De persoon is niet opgeslagen |
