> 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/timesheets/verlof-en-onkosten.md).

# Verlof & Onkosten

Verlof, kilometers en onkosten met een bon vastleggen op een timesheet, met alle soorten en hun waarden.

Naast uren kun je op een timesheet verlof, kilometers en onkosten vastleggen. In de API heten die samen declaraties. Er zijn twee manieren: verlof en kilometers sla je op met de uren, onkosten met een bon voeg je los toe.

* **Vereist recht:** Contracten kunnen bewerken. Ook de professional van het contract en de urenverantwoordelijken van het contract mogen dit

Declaraties vastleggen kan alleen bij een timesheet met `status` `1` (open) of `4` (afgekeurd).

## Soorten

| `declarationKind` | Soort                       | Wat je invult bij `amount`        | Hoe              |
| ----------------- | --------------------------- | --------------------------------- | ---------------- |
| `1`               | Kilometers woon-werk        | Het aantal kilometers van die dag | Met de uren      |
| `10`              | Zakelijke kilometers        | Het aantal kilometers van die dag | Met de uren      |
| `3`               | Thuiswerken                 | Het aantal uren                   | Met de uren      |
| `5`               | Kort verzuim                | Het aantal uren                   | Met de uren      |
| `6`               | Feestdag                    | Het aantal uren                   | Met de uren      |
| `7`               | Ziekte                      | Het aantal uren                   | Met de uren      |
| `8`               | Vrije dag                   | Het aantal uren                   | Met de uren      |
| `9`               | Bijzonder verlof            | `1`                               | Met de uren      |
| `2`               | Reiskosten openbaar vervoer | Het bedrag inclusief btw          | Los, met een bon |
| `4`               | Onkosten                    | Het bedrag inclusief btw          | Los, met een bon |

Welke soorten bij een contract horen, staat op het contract: de vergoedingen in `financial.compensations` en de lijst in `financial.allowedDeclarations`. Leg alleen soorten vast die daar staan.

## Verlof en kilometers vastleggen

* **Aanroep:** `PUT /timesheets/{id}`

{% hint style="warning" %}
Deze aanroep vervangt alle uren en al het verlof op de timesheet door de lijst die je meestuurt. Haal de timesheet daarom eerst op, neem `hours` en `declarations` over, voeg je regel toe en stuur het geheel terug.
{% endhint %}

De inhoud van het verzoek is een lijst met regels.

### Verplichte velden per regel

| Veld                     | Soort | Toelichting                                                                                                                                                     |
| ------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                   | getal | `2` voor verlof of kilometers, `1` voor uren                                                                                                                    |
| `dateTime`               | getal | De dag, als tijdstip om 00:00 uur UTC in milliseconden sinds 1970. De dag moet binnen de periode van de timesheet en binnen de looptijd van het contract vallen |
| `amount`                 | getal | Het aantal uren of kilometers, zie de tabel hierboven                                                                                                           |
| `declarationKind`        | getal | De soort, bij een regel met `type` `2`                                                                                                                          |
| `timeRegistrationRateId` | tekst | Het `_id` van het tarief, bij een regel met `type` `1`                                                                                                          |

### Optionele velden per regel

| Veld      | Soort | Toelichting     |
| --------- | ----- | --------------- |
| `comment` | tekst | Een toelichting |

Op een dag met thuiswerken (`3`) kun je geen kilometers woon-werk (`1`) opgeven.

### Voorbeeld

Een timesheet met acht gewone uren op 1 maart, 42 kilometer woon-werk op die dag en een ziektedag van acht uur op 3 maart:

```bash
curl -X PUT "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "type": 1,
      "dateTime": 1803859200000,
      "amount": 8,
      "timeRegistrationRateId": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d"
    },
    {
      "type": 2,
      "dateTime": 1803859200000,
      "amount": 42,
      "declarationKind": 1,
      "comment": "Bezoek locatie Amersfoort"
    },
    {
      "type": 2,
      "dateTime": 1804032000000,
      "amount": 8,
      "declarationKind": 7
    }
  ]'
```

### Wat je terugkrijgt

Niets: het antwoord heeft geen inhoud. Haal je de timesheet daarna op, dan staat het verlof in `declarations`:

```json
{
  "_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
  "createdAt": 1803115800000,
  "updatedAt": 1804089900000,
  "submittedAt": 0,
  "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
  "periodNumber": 3,
  "isEmpty": false,
  "hasUserInput": true,
  "year": 2027,
  "invoices": [],
  "fromDate": 1803859200000,
  "toDate": 1806537599999,
  "status": 1,
  "hours": [
    {
      "_id": "a1b2c3d4-0001-4a1b-8c1d-000000000001",
      "comment": "",
      "dateTime": 1803859200000,
      "createdAt": 1804089900000,
      "amount": 8,
      "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
      "type": 1,
      "timeRegistrationRateId": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
      "timeRegistrationRateType": 1,
      "hirerRate": 1,
      "supplierRate": 1,
      "isMarginScalingEnabled": false,
      "isStandby": false,
      "rateDescription": "Standaard uren 100%",
      "feeMultiplier": 1,
      "rateIdentityKey": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d"
    }
  ],
  "declarations": [
    {
      "_id": "b2c3d4e5-0001-4b2c-9d1e-000000000001",
      "comment": "Bezoek locatie Amersfoort",
      "dateTime": 1803859200000,
      "createdAt": 1804089900000,
      "amount": 42,
      "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
      "type": 2,
      "declarationKind": 1
    },
    {
      "_id": "b2c3d4e5-0002-4b2c-9d1e-000000000002",
      "comment": "",
      "dateTime": 1804032000000,
      "createdAt": 1804089900000,
      "amount": 8,
      "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
      "type": 2,
      "declarationKind": 7
    }
  ],
  "receiptDeclarations": [],
  "attachments": [],
  "approvals": [],
  "reopenedReason": null
}
```

Klopt de invoer niet, dan is het antwoord een lijst met fouten:

```json
[
  {
    "propertyName": "",
    "errorMessage": "Kilometerdeclaraties zijn niet toegestaan op een thuiswerkdag."
  }
]
```

Elke fout bevat daarnaast enkele technische velden, zoals `attemptedValue` en `errorCode`.

## Onkosten met een bon toevoegen

* **Aanroep:** `POST /timesheets/{id}/declarations`

Je stuurt de gegevens en de bon mee als formulier (`multipart/form-data`), niet als JSON. Deze aanroep voegt één declaratie toe en laat de rest van de timesheet staan.

### Verplichte velden

| Veld                          | Soort            | Toelichting                                                                                        |
| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `id`                          | tekst, in de URL | Het `_id` van de timesheet                                                                         |
| `Declaration.Type`            | getal            | Altijd `2`                                                                                         |
| `Declaration.DeclarationKind` | getal            | `2` reiskosten openbaar vervoer of `4` onkosten                                                    |
| `Declaration.DateTime`        | getal            | De dag van de uitgave, in milliseconden sinds 1970. Moet binnen de periode van de timesheet vallen |
| `Declaration.Amount`          | getal            | Het bedrag inclusief btw, groter dan 0                                                             |
| `Declaration.AmountExclVat`   | getal            | Het bedrag exclusief btw, groter dan 0 en niet hoger dan het bedrag inclusief btw                  |
| `File`                        | bestand          | De bon: een pdf of een afbeelding, maximaal 10 MB                                                  |

### Optionele velden

| Veld                  | Soort | Toelichting                     |
| --------------------- | ----- | ------------------------------- |
| `Declaration.Comment` | tekst | Een omschrijving van de uitgave |

### Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/declarations" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -F "Declaration.Type=2" \
  -F "Declaration.DeclarationKind=2" \
  -F "Declaration.DateTime=1803859200000" \
  -F "Declaration.Amount=12.10" \
  -F "Declaration.AmountExclVat=11.10" \
  -F "Declaration.Comment=Treinkaartje Utrecht - Amersfoort" \
  -F "File=@treinkaartje.pdf"
```

### Wat je terugkrijgt

De hele timesheet, met de nieuwe declaratie in `receiptDeclarations`:

```json
{
  "_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
  "createdAt": 1803115800000,
  "updatedAt": 1804089900000,
  "submittedAt": 0,
  "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
  "periodNumber": 3,
  "isEmpty": false,
  "hasUserInput": true,
  "year": 2027,
  "invoices": [],
  "fromDate": 1803859200000,
  "toDate": 1806537599999,
  "status": 1,
  "hours": [
    {
      "_id": "a1b2c3d4-0001-4a1b-8c1d-000000000001",
      "comment": "",
      "dateTime": 1803859200000,
      "createdAt": 1804089900000,
      "amount": 8,
      "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
      "type": 1,
      "timeRegistrationRateId": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
      "timeRegistrationRateType": 1,
      "hirerRate": 1,
      "supplierRate": 1,
      "isMarginScalingEnabled": false,
      "isStandby": false,
      "rateDescription": "Standaard uren 100%",
      "feeMultiplier": 1,
      "rateIdentityKey": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d"
    }
  ],
  "declarations": [],
  "receiptDeclarations": [
    {
      "_id": "c3d4e5f6-0001-4c3d-8e1f-000000000001",
      "comment": "Treinkaartje Utrecht - Amersfoort",
      "dateTime": 1803859200000,
      "createdAt": 1804089900000,
      "amount": 12.1,
      "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
      "type": 2,
      "declarationKind": 2,
      "filePath": "timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/treinkaartje.pdf",
      "amountExclVat": 11.1
    }
  ],
  "attachments": [],
  "approvals": [],
  "reopenedReason": null
}
```

* `receiptDeclarations[]._id` is het kenmerk van de declaratie. Dat gebruik je om hem te wijzigen of te verwijderen.
* `amount` is het bedrag inclusief btw, `amountExclVat` het bedrag exclusief btw.

Klopt de invoer niet, dan staat de reden in het antwoord:

```json
{
  "message": "Een bijlage moet worden opgegeven voor de declaratie.",
  "errors": [
    {
      "propertyName": "File",
      "errorMessage": "Een bijlage moet worden opgegeven voor de declaratie."
    }
  ]
}
```

## Onkosten wijzigen, verwijderen en de bon downloaden

| Wat            | Aanroep                                                                                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Wijzigen       | `PUT /timesheets/{id}/declarations/{declarationId}`, met dezelfde formuliervelden als bij toevoegen. `File` is hier optioneel: zonder bestand blijft de bestaande bon staan |
| Verwijderen    | `DELETE /timesheets/{id}/declarations/{declarationId}`. Het antwoord heeft geen inhoud                                                                                      |
| Bon downloaden | `GET /timesheets/{id}/declarations/{declarationId}`. Het antwoord is het bestand zelf                                                                                       |

Wijzigen geeft de hele timesheet terug, in dezelfde vorm als hierboven.

## Antwoorden

| Code  | Betekenis                                                                                                   |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| `200` | De timesheet met de declaratie, of de bon                                                                   |
| `204` | Het verlof en de kilometers zijn opgeslagen, of de declaratie is verwijderd. Het antwoord heeft geen inhoud |
| `400` | De invoer klopt niet, de timesheet is niet meer aan te passen, of het account mag dit niet                  |
| `401` | Geen geldig token                                                                                           |
| `404` | De timesheet bestaat niet                                                                                   |
