> 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/timesheets-ophalen.md).

# Timesheets ophalen

De timesheets van een contract of één timesheet ophalen, of zoeken met een filter, met het volledige antwoord.

Een timesheet is de urenregistratie van één periode van een contract. Je kunt de timesheets van een of meer contracten ophalen, één timesheet op kenmerk, of timesheets zoeken met een filter.

* **Vereist recht:** Geregistreerde uren inzien

Cootje maakt de timesheets zelf aan: zodra een contract definitief is, staat er voor elke periode van het contract een timesheet klaar.

## Timesheets van een contract

* **Aanroep:** `GET /timesheets/list/{contractIds}`
* **Verplicht:** `contractIds` in de URL: het `_id` van het contract. Meerdere contracten scheid je met een komma
* **Optioneel:** niets

```bash
curl "https://mijn.cootje.com/api/timesheets/list/d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

Heb je veel contracten, stuur de kenmerken dan als lijst mee met `POST /timesheets/list`:

```bash
curl -X POST "https://mijn.cootje.com/api/timesheets/list" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
    "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8d"
  ]'
```

### Wat je terugkrijgt

Een lijst met timesheets. Elke timesheet is aangevuld met gegevens van het contract:

```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": [],
    "approvals": [],
    "reopenedReason": null,
    "contractNumber": "CONTRACT-042",
    "professional": {
      "_id": "5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d",
      "name": "Sanne de Vries"
    },
    "hirer": {
      "_id": "0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b",
      "traderName": "Voorbeeld Zorg B.V.",
      "address": "Voorbeeldlaan 100, 3584 CX Utrecht, NL"
    },
    "timesheetPeriod": 4
  }
]
```

* `status` is `1` open, `2` ingediend, `3` goedgekeurd, `4` afgekeurd, `5` verwerkt (gefactureerd).
* `fromDate` en `toDate` zijn het begin en het einde van de periode. Alle tijdstippen zijn milliseconden sinds 1970.
* `hours` bevat de geregistreerde uren, `declarations` het verlof en de kilometers, `receiptDeclarations` de onkosten met een bon en `attachments` de bijgevoegde urenstaten.
* `approvals` bevat per urenverantwoordelijke de stand van de goedkeuring: `state` is `1` in afwachting, `2` goedgekeurd of `3` afgekeurd.
* `contractNumber`, `professional` en `hirer` komen van het contract. `timesheetPeriod` is de lengte van een periode: `2` week, `3` vier weken, `4` maand.

## Eén timesheet

* **Aanroep:** `GET /timesheets/{id}`
* **Verplicht:** `id` in de URL, het `_id` van de timesheet
* **Optioneel:** niets

```bash
curl "https://mijn.cootje.com/api/timesheets/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

### Wat je terugkrijgt

```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": [],
  "approvals": [],
  "reopenedReason": null
}
```

* `status` is `1` open, `2` ingediend, `3` goedgekeurd, `4` afgekeurd, `5` verwerkt (gefactureerd).
* `fromDate` en `toDate` zijn het begin en het einde van de periode. Alle tijdstippen zijn milliseconden sinds 1970.
* `hours` bevat de geregistreerde uren, `declarations` het verlof en de kilometers, `receiptDeclarations` de onkosten met een bon en `attachments` de bijgevoegde urenstaten.
* `approvals` bevat per urenverantwoordelijke de stand van de goedkeuring: `state` is `1` in afwachting, `2` goedgekeurd of `3` afgekeurd.

## Zoeken met een filter

* **Aanroep:** `POST /timesheets/query`
* **Verplicht:** niets
* **Optioneel:** `filter`, `sortBy`, `top` en `select`

| Veld     | Toelichting                                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `filter` | Eén voorwaarde in `filter`, of meerdere voorwaarden in `and` of `or`. Een voorwaarde bestaat uit `field`, `op` en `value` |
| `sortBy` | Sorteren: `field` en `ascending` (`true` of `false`)                                                                      |
| `top`    | Het maximale aantal resultaten                                                                                            |
| `select` | De velden die je terug wilt krijgen                                                                                       |

Bruikbare velden zijn onder meer `contractId`, `status`, `periodNumber` en `fromDate`. Bij `op` kies je uit `eq` (gelijk aan), `ne` (niet gelijk aan), `gt` en `gte` (groter dan), `lt` en `lte` (kleiner dan).

Dit voorbeeld zoekt alle ingediende timesheets, dus de timesheets die op goedkeuring wachten:

```bash
curl -X POST "https://mijn.cootje.com/api/timesheets/query" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filter": {
        "field": "status",
        "op": "eq",
        "value": 2
      }
    },
    "sortBy": {
      "field": "fromDate",
      "ascending": true
    }
  }'
```

### Wat je terugkrijgt

Een lijst met timesheets, in dezelfde vorm als bij één timesheet:

```json
[
  {
    "_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
    "createdAt": 1803115800000,
    "updatedAt": 1804089900000,
    "submittedAt": 1804089900000,
    "contractId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7b",
    "periodNumber": 3,
    "isEmpty": false,
    "hasUserInput": true,
    "year": 2027,
    "invoices": [],
    "fromDate": 1803859200000,
    "toDate": 1806537599999,
    "status": 2,
    "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": [],
    "approvals": [
      {
        "approverId": "3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a",
        "approverName": "Tom Visser",
        "updatedAt": 1804089900000,
        "rejectedReason": "",
        "state": 1,
        "overwritePaymentTerm": false
      }
    ],
    "reopenedReason": null
  }
]
```

* `status` is `1` open, `2` ingediend, `3` goedgekeurd, `4` afgekeurd, `5` verwerkt (gefactureerd).
* `fromDate` en `toDate` zijn het begin en het einde van de periode. Alle tijdstippen zijn milliseconden sinds 1970.
* `hours` bevat de geregistreerde uren, `declarations` het verlof en de kilometers, `receiptDeclarations` de onkosten met een bon en `attachments` de bijgevoegde urenstaten.
* `approvals` bevat per urenverantwoordelijke de stand van de goedkeuring: `state` is `1` in afwachting, `2` goedgekeurd of `3` afgekeurd.

## Antwoorden

| Code  | Betekenis                                            |
| ----- | ---------------------------------------------------- |
| `200` | De timesheet of de lijst met timesheets              |
| `400` | Het account mag deze timesheet niet bekijken         |
| `401` | Geen geldig token, of het account mist het recht     |
| `404` | De timesheet bestaat niet (alleen bij één timesheet) |
