Quelques conventions s’appliquent à l’ensemble de l’API. Apprenez-les une fois et la plupart des points d’entrée se comporteront de façon prévisible.

Identifiants

Les identifiants d’enregistrement sont des UUID, générés en ordre chronologique (version 7), ils se trient donc grossièrement par date de création. Traitez-les comme des chaînes opaques ; ne les analysez jamais et ne supposez aucune structure.

0190a1c2-3d4e-7f80-9a1b-2c3d4e5f6a7b

Vous recevez les identifiants dans les réponses et vous les renvoyez dans les chemins (/clients/{id}) ou comme clés étrangères dans les corps (client_id).

Dates et heures

Deux formats, selon le champ :

• Les horodatages sont au format RFC 3339 en UTC, par ex. 2026-01-05T09:00:00Z. Utilisés pour created_at, submitted_at, decided_at, et similaires.
• Les dates calendaires n’ont pas de composante horaire et ressemblent à 2026-01-05. Utilisées pour start_date, end_date, period_start, date, et les filtres de date.

Envoyez les dates exactement dans ces formats. Une date malformée est rejetée avec 400 ou 422 selon le point d’entrée.

Montants

Les montants sont des chaînes décimales, pas des nombres JSON, pour éviter la dérive des nombres à virgule flottante :

{ "amount": "1250.00", "vat_amount": "250.00", "net_amount": "1000.00" }

Règles :

• Envoyez une chaîne décimale. Les valeurs sont normalisées à 2 décimales maximum.
• Les montants négatifs et les valeurs supérieures ou égales à 1 000 000 000 sont rejetés avec 422 Unprocessable Entity.
• Une chaîne non numérique est rejetée avec 422.
• La devise est définie une fois par compte (voir les paramètres de l’organisation) et n’est pas portée par chaque montant. C’est un code ISO 4217 en majuscules, par ex. EUR.

Rappelez-vous, depuis Rôles et permissions, que daily_cost et billing_rate reviennent à null pour les jetons de rôle consultant.

Pagination

Les points d’entrée de liste renvoient la même enveloppe : un tableau items et un objet meta.

{
  "items": [ { "...": "..." } ],
  "meta": {
    "total_items": 57,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Deux paramètres de requête contrôlent la pagination :

Les valeurs hors plage sont bornées silencieusement plutôt que rejetées. total_pages vaut au moins 1, donc un résultat vide déclare quand même une page.

GET /clients?page=2&per_page=50 HTTP/1.1
Authorization: Bearer <access_token>

Recherche et filtres

Les points d’entrée de liste acceptent un paramètre search pour la recherche en texte libre. Elle recherche une sous-chaîne, sans tenir compte de la casse, sur quelques colonnes pertinentes (noms, e-mails, descriptions selon la ressource).

GET /clients?search=acme HTTP/1.1
Authorization: Bearer <access_token>

Au-delà de search, chaque point d’entrée de liste déclare ses propres filtres. Les plus courants :

• status - filtre par l’énumération de statut de la ressource (par ex. ?status=customer sur les clients).
• role - rôles séparés par des virgules sur GET /users (par ex. ?role=admin,operations).
• consultant_id, mission_id - restreindre à un consultant ou une mission.
• scope - mine (par défaut) ou team sur les feuilles de temps et les frais ; team élargit aux consultants que vous encadrez.
• Bornes de date - par ex. date_from / date_to sur les frais, period_start / period_end sur les feuilles de temps.

Il n’y a pas de paramètre sort ; l’ordre est fixe pour chaque point d’entrée.

Le point d’entrée de recherche globale fait exception : GET /search utilise ?q= (et non ?search=) et renvoie des résultats groupés (jusqu’à cinq par catégorie) dans les utilisateurs, les consultants, les clients, les missions, les feuilles de temps et les frais.

Énumérations

Les statuts, catégories et types sont des chaînes en snake_case minuscules : draft, time_and_materials, office_supplies, rate_based. Les devises font exception - des codes ISO en majuscules comme EUR. La référence de l’API liste les valeurs autorisées de chaque énumération.

Périodes de feuilles de temps

Les feuilles de temps couvrent une période délimitée par period_start et period_end (dates calendaires incluses). La longueur de la période suit la cadence du compte - hebdomadaire, toutes les deux semaines, mensuelle, tous les deux mois, ou trimestrielle. Les entrées journalières dans une ligne utilisent worked, half_day, ou not_worked. Voir Suivre le temps.