Temps travaillé

Ce qui a été enregistré sur chaque journée de travail — minutes travaillées contre minutes prévues. C'est ce que consomme une intégration de paie, et c'est la lecture où un null est le plus souvent pris pour un zéro. La section Non déclaré n'est pas zéro, plus bas, est celle à lire avant toutes les autres.

Le grain est la journée, pas le pointage

Une entrée, c'est ce qui a été enregistré pour une date et un contrat. Les événements individuels d'entrée et de sortie sont une donnée d'une autre nature, et cette API ne les sert pas : vous recevez les totaux sur lesquels une journée a été arrêtée, jamais la séquence qui les a produits.

C'est délibéré. Un calcul de paie consomme des journées ; une séquence de pointages décrit les déplacements de quelqu'un dans sa journée, ce qui est un relevé nettement plus intrusif que ce dont une intégration a réellement besoin.

Lister les journées

GET /api/v1/client/time-entries (scopes : time-entries:read)

{
  "items": [
    {
      "id": "WV5RJ7",
      "employmentId": "ePloqJ",
      "employeeId": "GNnBNO",
      "companyId": "1VaKPa",
      "date": "2026-01-12",
      "realMinutes": 495,
      "theoreticMinutes": 420,
      "isDeclared": true,
      "submittedOn": "<generated>",
      "hasExcessiveWorkload": true
    },
    {
      "id": "mNw9JY",
      "employmentId": "ePloqJ",
      "employeeId": "GNnBNO",
      "companyId": "1VaKPa",
      "date": "2026-01-13",
      "realMinutes": null,
      "theoreticMinutes": null,
      "isDeclared": false,
      "submittedOn": null,
      "hasExcessiveWorkload": false
    }
  ],
  "nextCursor": "pgyk3FWzA"
}

Les journées sortent de la plus ancienne à la plus récente.

La fenêtre filtre par inclusion, pas par recouvrement. Une journée est une date et appartient à exactement une fenêtre — contrairement à une absence, qui en couvre plusieurs et peut chevaucher une frontière de mois. Demander janvier rend les journées de janvier, rien de plus. Cela diffère de Congés et soldes à dessein : les deux lectures répondent à des questions de formes différentes, et les filtrer de la même manière serait faux pour l'une des deux.

Une date illisible laisse ce côté de la fenêtre ouvert plutôt que de faire échouer l'appel. Vous pouvez recevoir plus que ce que vous avez demandé, jamais moins.

establishmentId restreint, il n'élargit jamais. Nommer un établissement hors de votre périmètre ne renvoie rien plutôt que de l'atteindre, et il en va de même d'une valeur qui n'est pas un identifiant émis par cette API : un signet périmé vous donne une page vide, pas une erreur et pas le périmètre entier.

Il n'y a pas de filtre modifiedSince. Aucune colonne maintenue et indexée ne le porte, donc l'accepter reviendrait à l'ignorer en silence. Interrogez sur la fenêtre à la place — c'est ce qu'est réellement une période de paie.

Non déclaré n'est pas zéro

realMinutes: null signifie que la journée n'a PAS été déclarée. Cela ne signifie pas que zéro minute a été travaillée.

Le lire comme 0 ne paie rien pour une journée simplement pas encore soumise, et rien dans la réponse ne signale l'erreur : vous obtenez un nombre là où il y avait une absence de nombre. Branchez sur isDeclared, jamais sur realMinutes.

Et la règle ne fonctionne que dans un sens. isDeclared vaut vrai quand les deux totaux et submittedOn sont tous les trois renseignés — une journée peut donc porter realMinutes: 420 et se lire malgré tout isDeclared: false, parce qu'elle n'a pas été soumise. C'est le cas ordinaire, pas un cas limite : les totaux sont là dès que la journée est saisie, submittedOn seulement une fois la période réellement soumise. Un lecteur qui déduit la déclaration d'un realMinutes non nul traite donc des journées non déclarées comme déclarées — l'erreur symétrique de celle qui lit null comme zéro, et la plus fréquente des deux.

Les totaux repassent par ailleurs à null si la période est rouverte ou refusée. Une journée lue comme déclarée la semaine dernière peut donc légitimement se lire comme non déclarée aujourd'hui. Ce n'est ni une perte de données ni une correction : c'est la période qui est repartie pour un tour.

hasExcessiveWorkload est un indicateur enregistré, pas un indicateur dérivé des totaux. N'essayez pas de le reproduire en comparant realMinutes à theoreticMinutes : il est posé sur la journée par les règles propres de Staff & Go, qui tiennent compte de plus de choses que les deux nombres visibles ici.

Un salarié, plusieurs contrats

Un salarié peut détenir plusieurs contrats, chacun avec ses propres journées. C'est employmentId qui les sépare.

Deux entrées à la même date pour un même employeeId ne sont pas un doublon — ce sont deux contrats travaillés le même jour. Dédoublonner sur (employeeId, date) en écarte une en silence, et celle que vous écartez est du travail rémunéré. Clavez plutôt sur (employmentId, date).

Une journée qui disparaît est absente, pas supprimée

Il n'y a ni flux de delta ni pierre tombale. Une journée qui cesse d'être rendue entre deux lectures cesse simplement d'être rendue — rien ne l'annonce. Relisez la fenêtre plutôt que d'attendre un événement de suppression.

Quand la page est plus courte

Une liste couvre tout votre périmètre, mais un établissement qui n'a pas souscrit au module de gestion des temps est absent de cette lecture sans être nommé. La réponse dit qu'elle est incomplète, par le bloc partial — voir Quand une liste est plus courte que votre mandat dans Découvrir ce que vous pouvez appeler.

Ce point compte davantage ici qu'ailleurs : un périmètre mêlant des établissements qui utilisent Staff & Go pour la gestion des temps et des établissements qui ne l'utilisent pas est une situation ordinaire, pas une anomalie.