> 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/uren-registreren.md).

# Uren registreren

De juiste tarieven ophalen, uren per dag registreren en de timesheet indienen.

Uren registreer je op de timesheet van de periode waarin de dag valt. Voor elke dag geef je het aantal uren op, en het tarief als het geen gewone uren zijn. Daarna dien je de timesheet in.

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

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

## Stap 1: de juiste tarieven ophalen

Gewone uren gaan tegen het standaardtarief van 100%. Daarvoor hoef je geen tarief op te geven en kun je deze stap overslaan.

Voor andere uren, zoals overwerk, geef je het `_id` van een tarief mee. Een contract kan twee soorten tarieven gebruiken: de tarieven van de omgeving en eigen tarieven van het contract.

### De tarieven van de omgeving

* **Aanroep:** `GET /timeregistrationrates`
* **Verplicht:** niets
* **Optioneel:** niets

```bash
curl "https://mijn.cootje.com/api/timeregistrationrates" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

```json
[
  {
    "_id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
    "type": 1,
    "hirerValue": 100,
    "supplierValue": 100,
    "label": "Standaard uren 100%",
    "isStandby": false,
    "isMarginScalingEnabled": false,
    "isDefault": true
  },
  {
    "_id": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
    "type": 1,
    "hirerValue": 125,
    "supplierValue": 125,
    "label": "Overwerk 125%",
    "isStandby": false,
    "isMarginScalingEnabled": false,
    "isDefault": false
  },
  {
    "_id": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
    "type": 2,
    "hirerValue": 7.5,
    "supplierValue": 5,
    "label": "Bereikbaarheidsdienst",
    "isStandby": true,
    "isMarginScalingEnabled": false,
    "isDefault": false
  }
]
```

* `type` `1` is een percentage: `hirerValue` en `supplierValue` zijn percentages van het uurtarief van de klant en van de leverancier. `125` betekent 125%.
* `type` `2` is een vast bedrag per uur.
* `isDefault` is `true` bij het standaardtarief van 100%.
* `isStandby` is `true` bij een tarief voor bereikbaarheid.

### Welke tarieven het contract toestaat

Haal het contract op met `GET /contracts/{id}`. Voor de tarieven gebruik je uit dat antwoord twee velden:

```json
{
  "enabledRates": [
    "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
    "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e"
  ],
  "customRates": [
    {
      "_id": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",
      "type": 1,
      "hirerValue": 150,
      "supplierValue": 150,
      "label": "Weekenduren 150%",
      "isStandby": false,
      "isMarginScalingEnabled": false,
      "isDefault": false
    }
  ]
}
```

* `enabledRates` bevat de `_id`'s van de omgevingstarieven die dit contract mag gebruiken. Is het veld `null`, dan mag het contract ze allemaal gebruiken.
* `customRates` bevat de eigen tarieven van het contract. Die mag het contract altijd gebruiken.

Geef je een tarief op dat het contract niet mag gebruiken, dan weigert Cootje de registratie. In de foutmelding staan de tarieven die wel mogen, met hun `_id`.

## Stap 2: uren van één dag registreren

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

De aanroep zet de uren van één dag voor één tarief. Alle andere uren en declaraties op de timesheet blijven staan.

### Verplichte velden

| Veld       | Soort            | Toelichting                                                                                                                                                     |
| ---------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | tekst, in de URL | Het `_id` van de timesheet                                                                                                                                      |
| `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, van 0 tot en met 24. Met `0` haal je de uren van die dag en dat tarief weg                                                                     |

### Optionele velden

| Veld                     | Soort | Toelichting                                                                                  |
| ------------------------ | ----- | -------------------------------------------------------------------------------------------- |
| `timeRegistrationRateId` | tekst | Het `_id` van het tarief uit stap 1. Laat je het weg, dan geldt het standaardtarief van 100% |
| `comment`                | tekst | Een toelichting. Laat je het weg, dan blijft een bestaande toelichting staan                 |

Per dag kun je voor elk tarief één keer uren opgeven. Stuur je voor dezelfde dag en hetzelfde tarief opnieuw uren, dan vervangen die de eerdere.

### Voorbeeld

Acht gewone uren op 2 maart 2027:

```bash
curl -X PUT "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/hours" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": 1803945600000,
    "amount": 8
  }'
```

Twee uur overwerk op dezelfde dag:

```bash
curl -X PUT "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/hours" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": 1803945600000,
    "amount": 2,
    "timeRegistrationRateId": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
    "comment": "Oplevering fase 1"
  }'
```

### Wat je terugkrijgt

De hele timesheet, met de nieuwe uren erin:

```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"
    },
    {
      "_id": "a1b2c3d4-0002-4a1b-8c1d-000000000002",
      "comment": "",
      "dateTime": 1803945600000,
      "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"
    },
    {
      "_id": "a1b2c3d4-0003-4a1b-8c1d-000000000003",
      "comment": "Oplevering fase 1",
      "dateTime": 1803945600000,
      "createdAt": 1804089900000,
      "amount": 2,
      "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
      "type": 1,
      "timeRegistrationRateId": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
      "timeRegistrationRateType": 1,
      "hirerRate": 1.25,
      "supplierRate": 1.25,
      "isMarginScalingEnabled": false,
      "isStandby": false,
      "rateDescription": "Overwerk 125%",
      "feeMultiplier": 1,
      "rateIdentityKey": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e"
    }
  ],
  "declarations": [],
  "receiptDeclarations": [],
  "attachments": [],
  "approvals": [],
  "reopenedReason": null
}
```

* `hirerRate` en `supplierRate` zijn het tarief als factor: `1` is 100%, `1.25` is 125%. Bij een vast bedrag staat hier het bedrag per uur.
* `rateDescription` is de naam van het tarief.

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

```json
{
  "message": "Tarief '8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f' is niet beschikbaar voor dit contract; kies uit: 'Standaard uren 100%' (6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d), 'Overwerk 125%' (7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e).",
  "errors": [
    {
      "propertyName": "TimeRegistrationRateId",
      "errorMessage": "Tarief '8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f' is niet beschikbaar voor dit contract; kies uit: 'Standaard uren 100%' (6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d), 'Overwerk 125%' (7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e)."
    }
  ]
}
```

## Stap 3: de timesheet indienen

* **Aanroep:** `PUT /timesheets/{id}/close`
* **Verplicht:** `id` in de URL, het `_id` van de timesheet
* **Optioneel:** `suppressSubmittedMessage`

| Veld                       | Soort  | Toelichting                                                                  |
| -------------------------- | ------ | ---------------------------------------------------------------------------- |
| `suppressSubmittedMessage` | ja/nee | `true` om de urenverantwoordelijken geen e-mail te sturen. Standaard `false` |

Opslaan is nog niet indienen. Pas na deze aanroep gaat de timesheet naar de urenverantwoordelijken.

```bash
curl -X PUT "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/close" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "suppressSubmittedMessage": false
  }'
```

### Wat je terugkrijgt

Niets: bij een geslaagde indiening heeft het antwoord geen inhoud. De `status` is daarna `2` (ingediend). Is goedkeuring voor het contract uitgeschakeld, dan is de timesheet meteen goedgekeurd.

Indienen wordt geweigerd als een tarief niet is toegestaan, als het contract een urenstaat verplicht stelt en die ontbreekt, of als het budget van het contract wordt overschreden. Het antwoord is dan een lijst met fouten:

```json
[
  {
    "propertyName": "Attachments",
    "errorMessage": "Een urenstaat bijlage is verplicht om in te dienen."
  }
]
```

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

## Alle uren in één keer opslaan

Met `PUT /timesheets/{id}` sla je de hele timesheet in één keer op. Die aanroep vervangt alle uren en al het verlof op de timesheet door de lijst die je meestuurt. Alles wat je weglaat, wordt verwijderd. Onkosten met een bon blijven staan.

De inhoud van het verzoek is een lijst. Een regel met uren heeft `type` `1`, een `dateTime`, een `amount` en een `timeRegistrationRateId`:

```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": 1,
      "dateTime": 1803945600000,
      "amount": 8,
      "timeRegistrationRateId": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d"
    },
    {
      "type": 1,
      "dateTime": 1803945600000,
      "amount": 2,
      "timeRegistrationRateId": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
      "comment": "Oplevering fase 1"
    }
  ]'
```

Bij deze aanroep is `timeRegistrationRateId` verplicht: gebruik voor gewone uren het tarief met `isDefault` `true`. Het antwoord heeft geen inhoud.

## Antwoorden

| Code  | Betekenis                                                                                  |
| ----- | ------------------------------------------------------------------------------------------ |
| `200` | De timesheet met de nieuwe uren, of de lijst met tarieven                                  |
| `204` | Alle uren zijn opgeslagen, of de timesheet is ingediend. 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                                                                  |
