> 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/urenstaten-bijvoegen.md).

# Urenstaten bijvoegen

Een urenstaat als pdf of afbeelding bij een timesheet voegen, downloaden en verwijderen.

Een urenstaat is het document waarmee de uren worden onderbouwd, bijvoorbeeld een door de klant getekend overzicht. Je voegt hem als bestand bij de timesheet.

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

Een urenstaat bijvoegen kan alleen bij een timesheet met `status` `1` (open) of `4` (afgekeurd). Stelt het contract een urenstaat verplicht (veld `timesheetAttachmentRequired` op het contract), dan kan de timesheet zonder urenstaat niet worden ingediend.

## Urenstaat bijvoegen

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

Je stuurt het bestand mee als formulier (`multipart/form-data`), niet als JSON.

### Verplichte velden

| Veld   | Soort            | Toelichting                                                                                |
| ------ | ---------------- | ------------------------------------------------------------------------------------------ |
| `id`   | tekst, in de URL | Het `_id` van de timesheet                                                                 |
| `from` | getal, in de URL | Het begin van de periode waarover de urenstaat gaat, in milliseconden sinds 1970           |
| `to`   | getal, in de URL | Het einde van die periode. `from` en `to` moeten binnen de periode van de timesheet vallen |
| `file` | bestand          | De urenstaat: een pdf of een afbeelding, maximaal 10 MB                                    |

### Optionele velden

Geen.

### Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/attachments?from=1803859200000&to=1806537599999" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -F "file=@urenstaat-maart.pdf"
```

De waarden van `from` en `to` in dit voorbeeld zijn de `fromDate` en `toDate` van de timesheet: de urenstaat gaat over de hele periode.

### Wat je terugkrijgt

De hele timesheet, met de urenstaat in `attachments`:

```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": [],
  "attachments": [
    {
      "_id": "d4e5f6a7-0001-4d4e-9f1a-000000000001",
      "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
      "path": "timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/urenstaat-maart.pdf",
      "startDate": 1803859200000,
      "endDate": 1806537599999,
      "fileName": "urenstaat-maart.pdf"
    }
  ],
  "approvals": [],
  "reopenedReason": null
}
```

* `attachments[]._id` is het kenmerk van de urenstaat. Dat gebruik je om hem te downloaden of te verwijderen.
* `startDate` en `endDate` zijn de `from` en `to` die je hebt meegestuurd.

Klopt het bestand of de periode niet, dan staat de reden in het antwoord:

```json
{
  "message": "Alleen PDF- en afbeeldingsbestanden zijn toegestaan.",
  "errors": [
    {
      "propertyName": "",
      "errorMessage": "Alleen PDF- en afbeeldingsbestanden zijn toegestaan."
    }
  ]
}
```

## Urenstaat downloaden

* **Aanroep:** `GET /timesheets/{id}/attachments/{attachmentId}`
* **Vereist recht:** Geregistreerde uren inzien
* **Verplicht:** `id` en `attachmentId` in de URL
* **Optioneel:** niets

```bash
curl "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/attachments/d4e5f6a7-0001-4d4e-9f1a-000000000001" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -o urenstaat-maart.pdf
```

Het antwoord is het bestand zelf.

## Urenstaat verwijderen

* **Aanroep:** `DELETE /timesheets/{id}/attachments/{attachmentId}`
* **Verplicht:** `id` en `attachmentId` in de URL
* **Optioneel:** niets

```bash
curl -X DELETE "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/attachments/d4e5f6a7-0001-4d4e-9f1a-000000000001" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

Verwijderen kan alleen zolang de timesheet open of afgekeurd is. Het antwoord heeft geen inhoud.

## Antwoorden

| Code  | Betekenis                                                                                                  |
| ----- | ---------------------------------------------------------------------------------------------------------- |
| `200` | De timesheet met de urenstaat, of het bestand                                                              |
| `204` | De urenstaat is verwijderd. Het antwoord heeft geen inhoud                                                 |
| `400` | Het bestand of de periode 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                                                                                  |
