---
title: "Lister les feuilles de temps"
description: "Liste les feuilles de temps hebdomadaires, de la plus récente à la plus ancienne : heures prévues, travaillées, supplémentaires et leur compensation.\n\nUne semaine appartient au mois de paie de son dimanche, celui que filtrent `year` et `month`. Seules les semaines déjà ouvertes dans Puncto (par le collaborateur, un responsable ou une relance) sont listées ; la lecture n’en crée aucune."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.puncto.fr/llms.txt
> Use this file to discover all available pages before exploring further.

Path: API Puncto › Temps et congés

`GET /public/v1/timesheets`

Liste les feuilles de temps hebdomadaires, de la plus récente à la plus ancienne : heures prévues, travaillées, supplémentaires et leur compensation.

Une semaine appartient au mois de paie de son dimanche, celui que filtrent `year` et `month`. Seules les semaines déjà ouvertes dans Puncto (par le collaborateur, un responsable ou une relance) sont listées ; la lecture n’en crée aucune.

## Authentication

- `bearerAuth`, http, header `Authorization`

## Query parameters

- `page` (`listTimesheets.query.page`; integer, optional) — Numéro de page, à partir de 1.
  - min 1; default `1`
- `perPage` (`listTimesheets.query.perPage`; integer, optional) — Nombre d’éléments par page, 200 au plus.
  - min 1; max 200; default `50`
- `year` (`listTimesheets.query.year`; integer, optional) — Année du mois de paie de rattachement.
  - min 2000; max 2100; example `2026`
- `month` (`listTimesheets.query.month`; integer, optional) — Mois de paie de rattachement, de 1 (janvier) à 12.
  - min 1; max 12; example `9`
- `status[]` (`listTimesheets.query.status[]`; array<string>, optional) — Statuts à garder. Répétez le paramètre pour en passer plusieurs.
- `contractId` (`listTimesheets.query.contractId`; string, optional) — Identifiant Puncto du contrat.
  - example `"cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY"`
- `collaboratorId` (`listTimesheets.query.collaboratorId`; string, optional) — Identifiant Puncto du collaborateur. Ne pas combiner avec `collaboratorForeignErpId`.
  - example `"coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"`
- `collaboratorForeignErpId` (`listTimesheets.query.collaboratorForeignErpId`; string, optional) — Identifiant du collaborateur dans votre système (`foreignErpId`). Ne pas combiner avec `collaboratorId`.
  - example `"salarie-123"`

## Code samples

### cURL

```bash
curl --request GET \
  --url https://api.puncto.fr/public/v1/timesheets \
  --header 'Authorization: Bearer <token>'
```

### TypeScript

```typescript
const url = 'https://api.puncto.fr/public/v1/timesheets';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.puncto.fr/public/v1/timesheets"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Page de feuilles de temps

#### Example

```json
{
  "data": [
    {
      "timesheetId": "tshe_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "collaboratorForeignErpId": "string",
      "contractId": "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "weekStartDate": "2019-08-24",
      "year": 0,
      "month": 0,
      "status": "DRAFT",
      "days": [
        {
          "date": "2019-08-24",
          "kind": "WORKED",
          "expectedMinutes": 0,
          "expectedMorningMinutes": 0,
          "expectedAfternoonMinutes": 0,
          "workedMinutes": 0,
          "morning": {
            "start": "string",
            "end": "string"
          },
          "afternoon": {
            "start": "string",
            "end": "string"
          },
          "absenceType": "JNT",
          "absencePeriod": "FULL"
        }
      ],
      "contractWeeklyMinutes": 0,
      "expectedMinutes": 0,
      "workedMinutes": 0,
      "overtimeMinutes": 0,
      "compensationMode": "PAYMENT",
      "restHours": 0,
      "payrollVariableId": "pvar_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "submittedAt": "2019-08-24T14:15:22Z",
      "validatedAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "page": 0,
    "perPage": 0,
    "currentPage": 0,
    "firstPage": 0,
    "lastPage": 0
  }
}
```

- `data` (`listTimesheets.response.200.data`; array<object>, required)
  - `timesheetId` (`listTimesheets.response.200.data.timesheetId`; string, required) — Identifiant Puncto de la feuille de temps
  - `collaboratorId` (`listTimesheets.response.200.data.collaboratorId`; string, required) — Identifiant Puncto du collaborateur
  - `collaboratorForeignErpId` (`listTimesheets.response.200.data.collaboratorForeignErpId`; string | null, required) — Identifiant du collaborateur dans votre système, null s'il n'a pas été renseigné
  - `contractId` (`listTimesheets.response.200.data.contractId`; string, required) — Identifiant Puncto du contrat
  - `weekStartDate` (`listTimesheets.response.200.data.weekStartDate`; string, required) — Lundi de la semaine
    - format `date`
  - `year` (`listTimesheets.response.200.data.year`; number, required) — Année du mois de paie de rattachement : celui du dimanche de la semaine
  - `month` (`listTimesheets.response.200.data.month`; number, required) — Mois de paie de rattachement (1-12) : celui du dimanche de la semaine
  - `status` (`listTimesheets.response.200.data.status`; string, required) — Brouillon, à valider ou validée
    - one of `"DRAFT"`, `"TO_VALIDATE"`, `"VALIDATED"`
  - `days` (`listTimesheets.response.200.data.days`; array<object>, required) — Les sept jours de la semaine
    - `date` (`listTimesheets.response.200.data.days.date`; string, required) — Jour
      - format `date`
    - `kind` (`listTimesheets.response.200.data.days.kind`; string, required) — Nature de la journée : travaillée, non travaillée, hors contrat, fériée ou absence
      - one of `"WORKED"`, `"NOT_WORKED"`, `"OUT_OF_CONTRACT"`, `"PUBLIC_HOLIDAY"`, `"ABSENCE"`
    - `expectedMinutes` (`listTimesheets.response.200.data.days.expectedMinutes`; number, required) — Minutes prévues par le planning du contrat, 0 pour une journée non travaillée
    - `expectedMorningMinutes` (`listTimesheets.response.200.data.days.expectedMorningMinutes`; number | null, required) — Minutes prévues le matin, null sur les feuilles créées avant l'ajout de ce détail
    - `expectedAfternoonMinutes` (`listTimesheets.response.200.data.days.expectedAfternoonMinutes`; number | null, required) — Minutes prévues l'après-midi, null sur les feuilles créées avant l'ajout de ce détail
    - `workedMinutes` (`listTimesheets.response.200.data.days.workedMinutes`; number, required) — Minutes travaillées saisies
    - `morning` (`listTimesheets.response.200.data.days.morning`; any of, required) — Plage travaillée le matin, null si le matin n'est pas travaillé
      - any of: `WorkScheduleTimeRange`, `null`
    - `afternoon` (`listTimesheets.response.200.data.days.afternoon`; any of, required) — Plage travaillée l'après-midi, null si l'après-midi n'est pas travaillé
      - any of: `WorkScheduleTimeRange`, `null`
    - `absenceType` (`listTimesheets.response.200.data.days.absenceType`; any of, required) — Type de l'absence du jour, null sans absence
      - any of: `AbsenceType`, `null`
    - `absencePeriod` (`listTimesheets.response.200.data.days.absencePeriod`; any of, required) — Partie de la journée couverte par l'absence, null sans absence
      - any of: `TimesheetAbsencePeriod`, `null`
  - `contractWeeklyMinutes` (`listTimesheets.response.200.data.contractWeeklyMinutes`; number, required) — Durée hebdomadaire du contrat, en minutes
  - `expectedMinutes` (`listTimesheets.response.200.data.expectedMinutes`; number, required) — Minutes prévues sur la semaine
  - `workedMinutes` (`listTimesheets.response.200.data.workedMinutes`; number, required) — Minutes travaillées sur la semaine
  - `overtimeMinutes` (`listTimesheets.response.200.data.overtimeMinutes`; number, required) — Minutes au-delà de la durée hebdomadaire du contrat
  - `compensationMode` (`listTimesheets.response.200.data.compensationMode`; any of, required) — Compensation des heures supplémentaires choisie à la validation : paiement ou repos compensateur ; null avant la validation ou sans heures supplémentaires
    - any of: `TimesheetCompensationMode`, `null`
  - `restHours` (`listTimesheets.response.200.data.restHours`; number | null, required) — Heures de repos créditées (majoration comprise) quand `compensationMode` vaut `REST`
  - `payrollVariableId` (`listTimesheets.response.200.data.payrollVariableId`; any of, required) — Variable de paie des heures supplémentaires payées, créée à la validation, null sinon
    - any of: `string`, `null`
  - `submittedAt` (`listTimesheets.response.200.data.submittedAt`; any of, required) — Date de soumission par le collaborateur
    - any of: `string`, `null`
  - `validatedAt` (`listTimesheets.response.200.data.validatedAt`; any of, required) — Date de validation
    - any of: `string`, `null`
  - `createdAt` (`listTimesheets.response.200.data.createdAt`; string, required) — Date de création de la feuille de temps
    - format `date-time`
  - `updatedAt` (`listTimesheets.response.200.data.updatedAt`; string, required) — Date de dernière modification de la feuille de temps
    - format `date-time`
- `meta` (`listTimesheets.response.200.meta`; object, required)
  - `total` (`listTimesheets.response.200.meta.total`; integer, required) — Nombre total d’éléments.
  - `page` (`listTimesheets.response.200.meta.page`; integer, required) — Page renvoyée.
  - `perPage` (`listTimesheets.response.200.meta.perPage`; integer, required)
  - `currentPage` (`listTimesheets.response.200.meta.currentPage`; integer, required)
  - `firstPage` (`listTimesheets.response.200.meta.firstPage`; integer, required)
  - `lastPage` (`listTimesheets.response.200.meta.lastPage`; integer, required)

### 401

Clé d’API absente, invalide ou révoquée

#### Example

```json
{
  "error": "Les endpoints de l’API publique sont réservés aux comptes application."
}
```

- `error` (`listTimesheets.response.401.error`; string, required) — Message lisible, en français.
- `errorCode` (`listTimesheets.response.401.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 403

Opération hors de l’accès de la clé d’API

#### Example

```json
{
  "error": "Opération interdite"
}
```

- `error` (`listTimesheets.response.403.error`; string, required) — Message lisible, en français.
- `errorCode` (`listTimesheets.response.403.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 404

Collaborateur du filtre introuvable

#### Example

```json
{
  "error": "Collaborateur non trouvé"
}
```

- `error` (`listTimesheets.response.404.error`; string, required) — Message lisible, en français.
- `errorCode` (`listTimesheets.response.404.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 422

Paramètres invalides

#### Example

```json
{
  "errors": [
    {
      "message": "Le champ statut de l’absence doit être une valeur autorisée",
      "rule": "enum",
      "field": "status"
    }
  ]
}
```

- `errors` (`listTimesheets.response.422.errors`; array<object>, required)
  - `message` (`listTimesheets.response.422.errors.message`; string, required)
  - `rule` (`listTimesheets.response.422.errors.rule`; string, required) — Règle de validation en échec.
  - `field` (`listTimesheets.response.422.errors.field`; string, required) — Chemin du champ, par exemple `absences.0.type`.


Source: https://docs.puncto.fr/reference/timesheets/list/index.md
