API payante · Abonnement

Référence API développeur (payant)

Intégrez l’API de production d’envoi de plannings avec une clé API liée à votre abonnement payant. Les valeurs par défaut du locataire s’enregistrent avec PATCH /v1/schedule-defaults ; les souhaits hebdomadaires par collaborateur se lisent ou se remplacent avec GET/PUT /v1/staff/{staffId}/weekly-shift-wish. La facturation suit votre abonnement et votre contrat (pas de tarification à l’appel API). Cette page documente les droits, règles de validation et codes d’erreur — utilisez la barre latérale pour accéder à chaque champ.

Cette page documente l'API REST produit pour les integrations externes (API Gateway {stage}/v1/*, authentification x-api-key).

Les webhooks de fin de resultat sont des notifications HTTPS sortantes configurees dans la gestion API (pas un CRUD REST). Voir Completion webhooks sur cette page.

Les routes navigateur internes (paiements, analytics, etc.) ne remplacent pas cette API produit. Pour les systemes externes, utilisez /v1/* et les webhooks de completion.

Cette API HTTP fait partie du produit payant : l’accès nécessite un accord commercial actif et les clés sont émises pour votre organisation après l’onboarding.

La facturation repose sur l’abonnement et le contrat. Pour les offres payantes, les montants suivent généralement la page Tarifs (souvent par collaborateur inscrit et par mois).

Les limites du playground ou du niveau gratuit ne s’appliquent pas aux clés API payantes. Les limites effectives (durée, effectifs, granularité 15 min) dépendent de vos droits payants. Voir Limites et valeurs par défaut sur cette page.

Les requêtes doivent inclure une clé API valide émise dans le cadre de votre abonnement payant. Créez, faites tourner et révoquez les clés depuis l’espace compte après connexion.

Envoyez la clé dans l’en-tête x-api-key. Les clés sont liées à votre organisation pour la résolution du locataire et les plafonds d’accès prévus au contrat.

Gérer les clés : Gestion des API

Envoyez une condition de planning au format JSON. Il s’agit de la surface d’intégration payante ; l’URL de base exacte est fournie par environnement après provisionnement de l’accès API.

POST {baseUrl}/v1/schedule

Utilisez l’URL de base fournie lors du provisionnement de l’accès API ou par votre contact d’exploitation.

Remplacez BASE_URL par l’URL de base de l’API (préfixe de chemin) fournie lors du provisionnement de votre accès.

Envoyez votre clé API dans l’en-tête **x-api-key**. Votre organisation (locataire) est identifiée à partir de la clé — vous ne passez pas d’identifiant de locataire séparé dans la chaîne de requête.

Les fonctions payantes (shift d’urgence, détails travail, certaines valeurs par défaut) nécessitent un abonnement payant actif. Si la facturation n’est pas configurée, vous pouvez recevoir **503** (p. ex. code **STRIPE_NOT_CONFIGURED**). Le profil d’entreprise, les journaux d’audit et la gestion des utilisateurs (comptes) relèvent de l’application web et ne font pas partie de l’API publique.

Exemple curl (bash / macOS / Linux / WSL)

Windows PowerShell : un `\` en fin de ligne **ne** poursuit **pas** la ligne. Écrivez sur une seule ligne, ou terminez chaque ligne par un accent grave (`) pour continuer.

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/schedule-results?limit=10"

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/staff"

Même URL de base et même clé x-api-key que pour POST /v1/schedule. Paramètres facultatifs : limit (1–100, 50 par défaut), cursor (jeton opaque : reprenez le champ nextCursor de la réponse précédente).

GET{baseUrl}/v1/schedule-results
Liste les lignes parentes SCHEDULE_RESULT : conditionId, status, candidateCount, createdAt/updatedAt, etc. Pagination DynamoDB.
GET{baseUrl}/v1/schedule-results/history
Recherche d’historique des résultats (équivalent navigateur). from / to (ISO 8601, défaut début de service à maintenant), keyword, eventName (INSERT,MODIFY,REMOVE séparés par virgules), limit, cursor. Fusion automatique récent + archive ; retourne uniquement items / nextCursor.
GET{baseUrl}/v1/schedule-results/{conditionId}
Récupère une ligne parente SCHEDULE_RESULT par conditionId (attributs JSON ; PK/SK omis).
GET{baseUrl}/v1/schedule-results/{conditionId}/resolution
Sortie d’optimisation résolue : status, candidates, confirmedAssignments si présents. Si status est completed et pas encore confirmé, rank-1 peut être auto-confirmé sur ce GET (effet de bord). Utilisez POST …/confirm-assignments pour une confirmation manuelle.
GET{baseUrl}/v1/schedule-results/{conditionId}/review
Charge utile de revue pour confirmation manuelle (candidats, requiredByCellKey, allowedCellKeys du personnel, etc.).
GET{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context
Contexte de shift d’urgence (dates, personnel, créneaux). Abonnement payant requis ; null si la condition est absente.
GET{baseUrl}/v1/schedule-conditions
Liste les lignes parentes SCHEDULE_CONDITION (conditionId, dates, publicApiCancelledAt optionnel).
GET{baseUrl}/v1/schedule-conditions/{conditionId}
Ligne parente de condition plus reqDays et staffSnapshots (sans PK/SK).
GET{baseUrl}/v1/schedule-defaults
Ligne de valeurs par défaut du locataire (SCHEDULE_DEFAULTS) ou null si non enregistrée.
GET{baseUrl}/v1/schedule-actual/{conditionId}
Ligne SCHEDULE_ACTUAL des affectations réelles, ou null si absente.
GET{baseUrl}/v1/staff/{staffId}/weekly-shift-wish
Ligne de souhaits hebdomadaires du collaborateur, ou null si absente.
GET{baseUrl}/v1/staff
Liste les membres actifs du personnel du locataire (tri par nom affiché).
GET{baseUrl}/v1/staff/{staffId}
Récupère un membre par staffId, détails travail inclus (laborLawCompliance, laborFlsaExempt, plafonds personnels, laborConstraintMask). Suppression logique → 404.

Méthode	Chemin	Description
GET	{baseUrl}/v1/schedule-results	Liste les lignes parentes SCHEDULE_RESULT : conditionId, status, candidateCount, createdAt/updatedAt, etc. Pagination DynamoDB.
GET	{baseUrl}/v1/schedule-results/history	Recherche d’historique des résultats (équivalent navigateur). from / to (ISO 8601, défaut début de service à maintenant), keyword, eventName (INSERT,MODIFY,REMOVE séparés par virgules), limit, cursor. Fusion automatique récent + archive ; retourne uniquement items / nextCursor.
GET	{baseUrl}/v1/schedule-results/{conditionId}	Récupère une ligne parente SCHEDULE_RESULT par conditionId (attributs JSON ; PK/SK omis).
GET	{baseUrl}/v1/schedule-results/{conditionId}/resolution	Sortie d’optimisation résolue : status, candidates, confirmedAssignments si présents. Si status est completed et pas encore confirmé, rank-1 peut être auto-confirmé sur ce GET (effet de bord). Utilisez POST …/confirm-assignments pour une confirmation manuelle.
GET	{baseUrl}/v1/schedule-results/{conditionId}/review	Charge utile de revue pour confirmation manuelle (candidats, requiredByCellKey, allowedCellKeys du personnel, etc.).
GET	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context	Contexte de shift d’urgence (dates, personnel, créneaux). Abonnement payant requis ; null si la condition est absente.
GET	{baseUrl}/v1/schedule-conditions	Liste les lignes parentes SCHEDULE_CONDITION (conditionId, dates, publicApiCancelledAt optionnel).
GET	{baseUrl}/v1/schedule-conditions/{conditionId}	Ligne parente de condition plus reqDays et staffSnapshots (sans PK/SK).
GET	{baseUrl}/v1/schedule-defaults	Ligne de valeurs par défaut du locataire (SCHEDULE_DEFAULTS) ou null si non enregistrée.
GET	{baseUrl}/v1/schedule-actual/{conditionId}	Ligne SCHEDULE_ACTUAL des affectations réelles, ou null si absente.
GET	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Ligne de souhaits hebdomadaires du collaborateur, ou null si absente.
GET	{baseUrl}/v1/staff	Liste les membres actifs du personnel du locataire (tri par nom affiché).
GET	{baseUrl}/v1/staff/{staffId}	Récupère un membre par staffId, détails travail inclus (laborLawCompliance, laborFlsaExempt, plafonds personnels, laborConstraintMask). Suppression logique → 404.

Utilisez la même clé API avec des corps JSON. PATCH /v1/schedule-defaults enregistre les valeurs par défaut du locataire (requirementsByCellKey, horizon de planification, etc.) ; les champs payants suivent votre abonnement. PUT /v1/staff/{staffId}/weekly-shift-wish remplace entièrement la grille hebdomadaire des souhaits (voir la note de validation). POST /v1/staff renvoie 409 STAFF_LIMIT si l’effectif dépasserait la limite du locataire. La gestion des utilisateurs (comptes), le profil d’entreprise et les journaux d’audit relèvent de l’application web et ne font pas partie de l’API publique.

POST /v1/staff : JSON { "displayName": "..." } uniquement. PATCH /v1/staff/{staffId} : displayName, laborLawCompliance, laborFlsaExempt, personalMaxWeeklyMinutes / personalMaxMonthlyMinutes / personalMaxThreeMonthMinutes (entier ou null), laborConstraintMask (objet ou null si laborLawCompliance true) — champs travail payants. POST /v1/schedule-results/{conditionId}/emergency-shift : absentStaffIds, absentDatesYmd et/ou absentSlots (payant, planning source terminé). POST …/confirm-assignments : tableau assignments et relaxAvailability optionnel. PATCH /v1/schedule-defaults : PUBLIC_API_SCHEDULE_REQUEST_BODY.md §12. PUT /v1/staff/{staffId}/weekly-shift-wish : scheduleStartDate, scheduleEndDate, timeRangeStart, timeRangeEnd, wishByCellKey.

PATCH{baseUrl}/v1/schedule-defaults
Enregistre les valeurs par défaut de planning du locataire (corps JSON aligné sur saveSchema dans schedule-defaults-actions). Les champs payants suivent votre abonnement.
POST{baseUrl}/v1/staff
Crée un membre du personnel (displayName). Renvoie 201 avec le JSON staff.
POST{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift
Clone un planning source terminé avec absences appliquées ; renvoie 201 avec conditionId. Abonnement payant requis.
POST{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments
Valide et enregistre les affectations éditées manuellement (200 avec { ok: true }).
PATCH{baseUrl}/v1/staff/{staffId}
Met à jour displayName et détails travail (laborLawCompliance, laborFlsaExempt, plafonds personnels, laborConstraintMask).
DELETE{baseUrl}/v1/staff/{staffId}
Supprime logiquement un membre du personnel (définit deletedAt).
DELETE{baseUrl}/v1/schedule-conditions/{conditionId}
Marque la condition comme annulée (publicApiCancelledAt) ; ne supprime pas les lignes enfants.
PUT{baseUrl}/v1/schedule-actual/{conditionId}
Enregistre les affectations réelles JSON { "assignments": [ ... ] } (validées contre la grille de la condition).
PUT{baseUrl}/v1/staff/{staffId}/weekly-shift-wish
Remplace les souhaits hebdomadaires : grille complète (1–7 jours), wishByCellKey par cellule (NONE|LOW|HIGH) ; granularité selon les valeurs par défaut du locataire.

Méthode	Chemin	Description
PATCH	{baseUrl}/v1/schedule-defaults	Enregistre les valeurs par défaut de planning du locataire (corps JSON aligné sur saveSchema dans schedule-defaults-actions). Les champs payants suivent votre abonnement.
POST	{baseUrl}/v1/staff	Crée un membre du personnel (displayName). Renvoie 201 avec le JSON staff.
POST	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift	Clone un planning source terminé avec absences appliquées ; renvoie 201 avec conditionId. Abonnement payant requis.
POST	{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments	Valide et enregistre les affectations éditées manuellement (200 avec { ok: true }).
PATCH	{baseUrl}/v1/staff/{staffId}	Met à jour displayName et détails travail (laborLawCompliance, laborFlsaExempt, plafonds personnels, laborConstraintMask).
DELETE	{baseUrl}/v1/staff/{staffId}	Supprime logiquement un membre du personnel (définit deletedAt).
DELETE	{baseUrl}/v1/schedule-conditions/{conditionId}	Marque la condition comme annulée (publicApiCancelledAt) ; ne supprime pas les lignes enfants.
PUT	{baseUrl}/v1/schedule-actual/{conditionId}	Enregistre les affectations réelles JSON { "assignments": [ ... ] } (validées contre la grille de la condition).
PUT	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Remplace les souhaits hebdomadaires : grille complète (1–7 jours), wishByCellKey par cellule (NONE\|LOW\|HIGH) ; granularité selon les valeurs par défaut du locataire.

When a schedule result reaches a terminal status, we POST a signed JSON notification to your HTTPS URL. The body does not include the full result; fetch details with GET /v1/schedule-results/{conditionId}.

Playground results are not delivered. If the webhook is disabled or no URL is saved, nothing is sent.

Setup

After sign-in, open API management and save an HTTPS notification URL.
Turn on Enable notifications.
Copy the signing secret shown once (it cannot be revealed again; regenerate if lost).
Verify the signature on your receiver, then GET links.result with your API key if needed.

Events

Event type and when it is sent.

schedule.result.terminal
Schedule result status becomes completed, no_solution, failed, error, or canceled

type	When
schedule.result.terminal	Schedule result status becomes completed, no_solution, failed, error, or canceled

Request body

status is terminal only. customerId is omitted from the body.

{
  "type": "schedule.result.terminal",
  "conditionId": "019ee481-e855-7000-abd8-977cbfd64ffc",
  "status": "completed",
  "occurredAt": "2026-07-16T13:00:54.694Z",
  "links": {
    "result": "{baseUrl}/v1/schedule-results/019ee481-e855-7000-abd8-977cbfd64ffc"
  }
}

Request headers

Content-Type
application/json
User-Agent
AutoScheduler-Webhook/1.0
X-AutoScheduler-Timestamp
Unix seconds as a string
X-AutoScheduler-Signature
v1=<hex> (see verification below)

Header	Description
Content-Type	application/json
User-Agent	AutoScheduler-Webhook/1.0
X-AutoScheduler-Timestamp	Unix seconds as a string
X-AutoScheduler-Signature	v1=<hex> (see verification below)

Signature verification

Compute a digest from the raw body (before JSON parse) and the Timestamp, then compare to Signature. Reject requests when |now − timestamp| exceeds 300 seconds (5 minutes) unless you intentionally allow wider clock skew.

HMAC-SHA256(signingSecret, `${timestamp}.${rawBody}`) → hex; header value is v1=<hex>

Retries

On 5xx or timeout we retry automatically. Persistent failures go to a dead-letter queue. Browser push notifications use a separate path.

x-api-key
Clé API liée à votre abonnement payant (identifie le locataire et les limites du plan).
Content-Type
application/json

En-tête	Description
x-api-key	Clé API liée à votre abonnement payant (identifie le locataire et les limites du plan).
Content-Type	application/json

En-têtes de réponse

Certains en-têtes de réponse (comme les identifiants de requête) sont des métadonnées de traçage, pas votre clé API. Traitez les **corps** JSON comme confidentiels lorsqu’ils contiennent des données d’entreprise ou d’utilisateur.

Limites de validation typiques pour votre contrat (granularité 15 min, durée du planning, nombre de collaborateurs inscrits et plafonds associés).

Modèle de facturation
Abonnement Stripe ; les frais produit évoluent généralement avec le nombre de sièges (personnel enregistré) comme sur la page tarifs (pas de facturation à l’appel API).
maxScheduleDays
Jusqu’à 14 jours civils par envoi pour la planification détaillée standard sur deux semaines (plages plus larges uniquement si le contrat le permet).
maxStaffPerSchedule
Jusqu’à 500 lignes staff par POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF ; staffId en ligne dans le corps).
maxRosterStaff
Jusqu’à 30 collaborateurs actifs via POST /v1/staff (STAFF_ROSTER_MAX_PAID) ; 409 STAFF_LIMIT si dépassement.
allowedGranularities
[60, 15] — les créneaux de 15 minutes sont une fonctionnalité payante ; 60 minutes est aussi pris en charge.
maxPayloadBytes
524288 (512 KiB) UTF-8 sauf plafond supérieur accordé.
strictUnknownRootKeys
true — les clés inconnues à la racine ou dans staff sont rejetées

Paramètre	API payante (typique)
Modèle de facturation	Abonnement Stripe ; les frais produit évoluent généralement avec le nombre de sièges (personnel enregistré) comme sur la page tarifs (pas de facturation à l’appel API).
maxScheduleDays	Jusqu’à 14 jours civils par envoi pour la planification détaillée standard sur deux semaines (plages plus larges uniquement si le contrat le permet).
maxStaffPerSchedule	Jusqu’à 500 lignes staff par POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF ; staffId en ligne dans le corps).
maxRosterStaff	Jusqu’à 30 collaborateurs actifs via POST /v1/staff (STAFF_ROSTER_MAX_PAID) ; 409 STAFF_LIMIT si dépassement.
allowedGranularities	[60, 15] — les créneaux de 15 minutes sont une fonctionnalité payante ; 60 minutes est aussi pris en charge.
maxPayloadBytes	524288 (512 KiB) UTF-8 sauf plafond supérieur accordé.
strictUnknownRootKeys	true — les clés inconnues à la racine ou dans staff sont rejetées

Le besoin en effectifs par cellule reste un entier de 0 à 15. Le dépassement des limites de débit peut renvoyer une réponse d’erreur.

En mode strict, seules les clés de niveau supérieur suivantes sont acceptées. Toute autre clé renvoie UNKNOWN_FIELD.

apiVersion
timeZone
scheduleStartDate
scheduleEndDate
timeRangeStart
timeRangeEnd
slotGranularityMinutes
requirementsByCell
staff

Le corps suit le modèle public payant : dates de calendrier, fuseau horaire, grille de créneaux (60 ou 15 minutes sur l’API payante), besoins par cellule et disponibilité du personnel. La juridiction en droit du travail, les indicateurs d’optimisation payante et les champs travail au niveau du personnel ne font pas partie du JSON — le serveur écrit des valeurs par défaut sur la ligne parente SCHEDULE_CONDITION à la persistance (voir « Droit du travail et options payantes »). N’incluez pas les clés DynamoDB ni les types d’entité internes dans le corps.

apiVersion — Facultatif. Si présent, uniquement la chaîne de version de schéma prise en charge.
Format cellKey — Les clés dans requirementsByCell et availableCells doivent correspondre à `${date}__${slotId}`, où date est au format YYYY-MM-DD dans la plage et slotId provient des créneaux énumérés pour votre plage horaire et granularité (comme `cellKey` dans les helpers du playground).

timeZone
Type
string
Obligatoire
Oui
Fuseau horaire IANA pour interpréter les dates et les créneaux.
scheduleStartDate / scheduleEndDate
Type
string (YYYY-MM-DD)
Obligatoire
Oui
Plage de calendrier inclusive ; début ≤ fin.
timeRangeStart / timeRangeEnd
Type
string (HH:mm)
Obligatoire
Oui
Plage horaire « horloge murale » qui définit la colonne de créneaux ; doit produire au moins un créneau.
slotGranularityMinutes
Type
60 | 15
Obligatoire
Oui
API payante : 60 (heure) ou 15 (quarts d’heure). Doit figurer dans allowedGranularities.
requirementsByCell
Type
object
Obligatoire
Oui
Clés = cellKey dans la grille calculée ; valeurs = entier 0–15.
staff
Type
array
Obligatoire
Oui
Non vide ; taille max. selon les limites ; chaque élément : staffId, displayName, availableCells facultatif.

Champ	Type	Obligatoire	Notes
timeZone	string	Oui	Fuseau horaire IANA pour interpréter les dates et les créneaux.
scheduleStartDate / scheduleEndDate	string (YYYY-MM-DD)	Oui	Plage de calendrier inclusive ; début ≤ fin.
timeRangeStart / timeRangeEnd	string (HH:mm)	Oui	Plage horaire « horloge murale » qui définit la colonne de créneaux ; doit produire au moins un créneau.
slotGranularityMinutes	60 \| 15	Oui	API payante : 60 (heure) ou 15 (quarts d’heure). Doit figurer dans allowedGranularities.
requirementsByCell	object	Oui	Clés = cellKey dans la grille calculée ; valeurs = entier 0–15.
staff	array	Oui	Non vide ; taille max. selon les limites ; chaque élément : staffId, displayName, availableCells facultatif.

Référence des champs (valeurs autorisées)

Les sections suivantes reflètent le validateur dans `app/lib/public-schedule-api/validate.ts` et les assainisseurs dans `sanitize.ts`, avec les valeurs par défaut payantes de `PUBLIC_SCHEDULE_SUBMIT_DEFAULTS` sauf options explicites. Envoyez les nombres JSON comme nombres réels (pas comme chaînes). Après validation, `build-schedule-transact-items.ts` ajoute des champs de ligne parente (copie d’optimisation payante, juridiction travail, version du modèle) qui ne sont pas des clés de requête — voir « Droit du travail et options payantes ».

Valeurs autorisées

Omis : accepté (comportement actuel).
Si présent, doit être exactement "2026-04-01" (PUBLIC_SCHEDULE_API_VERSION).
Toute autre chaîne est rejetée (TYPE_ERROR).

Comportement

Comparaison après traitement équivalent à un trim dans sanitizeApiVersion.

Erreurs typiques

TYPE_ERRORValeur apiVersion non prise en charge.

Valeurs autorisées

Format : une seule chaîne. L’API ne publie pas une énumération fermée de toutes les zones : le serveur valide dynamiquement.
La validation correspond à `isValidIanaTimeZone` : Luxon `DateTime.now().setZone(zone).isValid` doit être true.
Utilisez des identifiants IANA canoniques, ex. `Asia/Tokyo`, `America/New_York`, `Europe/Berlin`, `UTC`.
Ne vous fiez pas seulement aux abréviations (`EST`, `JST`, `GMT`) — ce ne sont pas des ID IANA stables et elles peuvent être rejetées.
Listes de référence : distribution IANA (https://www.iana.org/time-zones) ou l’API fuseau horaire de votre plateforme.

Comportement

Utilisé avec les dates et les heures de créneau dans la normalisation en aval.
Si vous avez besoin d’une liste fixe côté client, dérivez-la avec les mêmes règles (IDs IANA), sans attendre une énumération serveur dans le schéma JSON.

Erreurs typiques

INVALID_TIME_ZONEManquant, vide ou zone IANA invalide.

Valeurs autorisées

Doit correspondre à /^\d{4}-\d{2}-\d{2}$/ (après trim).
Dates de calendrier réelles ; la plage inclusive doit produire au moins un jour via enumerateDates.
Le nombre de jours ne doit pas dépasser maxScheduleDays (API payante typiquement jusqu’à 14 jours ; plafond exact = droits du locataire).

Comportement

scheduleStartDate doit être antérieur ou égal à scheduleEndDate.

Erreurs typiques

INVALID_DATE_RANGEMauvais format, dates invalides ou plage vide.
SCHEDULE_SPAN_TOO_LONGPlus de maxScheduleDays jours.

Valeurs autorisées

Chaînes non vides (trim) interprétées avec la même énumération de créneaux que l’UI (`enumerateSlotsByGranularity`).
La paire doit produire au moins un créneau ; sinon la validation échoue.

Comportement

Avec slotGranularityMinutes, définit les slotId utilisés pour cellKey.

Erreurs typiques

INVALID_TIME_RANGEValeurs manquantes ou zéro créneau pour la plage.

Valeurs autorisées

Exactement 60 ou 15 (pas une chaîne).
Doit aussi figurer dans allowedGranularities. Sur l’API payante les deux sont en général activés ; si 15 est désactivé pour votre locataire, INVALID_GRANULARITY.

Comportement

Définit le nombre de créneaux avec la plage horaire.

Erreurs typiques

INVALID_GRANULARITYPas 60/15 ou non autorisé par le plan.

Valeurs autorisées

Doit être un objet JSON plan (pas un tableau).
Chaque clé doit être un cellKey dans la grille attendue (dates × slotIds). Clés inconnues → UNKNOWN_CELL_KEY.
Chaque valeur : nombre JSON entier entre 0 et 15 inclus.
Les cellules omises sont traitées comme besoin 0 (SHORTFALL seulement pour besoin ≥ 1).

Comportement

Les clés sont comparées après trim via sanitizeCellKey.

Erreurs typiques

INVALID_REQUIREMENTSPas un objet ou valeur numérique invalide pour une clé.
UNKNOWN_CELL_KEYClé hors de la grille date × créneau calculée.

Valeurs autorisées

Longueur entre 1 et maxStaffPerSchedule (500 par défaut pour POST /v1/schedule ; distinct du plafond de liste POST /v1/staff).
Chaque élément : objet plan avec uniquement les clés autorisées : staffId, displayName, availableCells (mode strict).
staffId et displayName doivent passer l’assainissement (section Assainissement).
staffId doit être unique dans le tableau (DUPLICATE_STAFF_ID).

Comportement

L’ordre est conservé pour le décompte de disponibilité.

Erreurs typiques

INVALID_STAFFTableau vide, trop de lignes, objet invalide ou assainissement échoué.
UNKNOWN_FIELDClé supplémentaire sur un objet staff en mode strict.
DUPLICATE_STAFF_IDMême staffId deux fois.

Valeurs autorisées

Si omis : le membre du personnel est considéré disponible sur toutes les cellules (null = « toutes les cellules » en interne).
Si présent : tableau JSON de chaînes ; chaque chaîne non vide doit être un cellKey dans la grille attendue.
Les chaînes vides dans le tableau sont invalides (INVALID_AVAILABLE_CELL).

Contrôle SHORTFALL

Pour chaque cellule avec besoin ≥ 1, le nombre de personnel disponible doit être ≥ besoin, sinon SHORTFALL_CELLS.

Erreurs typiques

INVALID_AVAILABLE_CELLClé de cellule inconnue ou entrée vide.
SHORTFALL_CELLSPersonnel insuffisant par rapport au besoin pour une cellule.

Ce que l’API enregistre sur la ligne parente

L’API publique n’accepte que ROOT_KEYS à la racine et STAFF_KEYS sur chaque ligne personnel. N’envoyez pas laborLawJurisdiction, usLaborStateCode, laborModelVersion ni paidOptimization.
À l’envoi, le serveur remplit la ligne parente SCHEDULE_CONDITION avec les valeurs partagées : paidOptimization = DEFAULT_PAID_OPTIMIZATION — laborLawCompliance false ; balanceStaffLoad, honorShiftWishes et preferConsecutiveShifts true (voir schedule-defaults-shared.ts et build-schedule-transact-items.ts). laborLawJurisdiction JP, usLaborStateCode GENERIC, laborModelVersion v1.
Les contraintes de type légal dans l’optimiseur exigent les indicateurs de conformité parent et par personne ; ce chemin les laisse désactivés : n’attendez pas de plafonds légaux uniquement avec ce JSON.
Le modèle travail est une approximation pour la planification, pas un conseil juridique. Catalogue : optimizer/config/labor_models.json.

Documentation

Détail : docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §2.1.1 et §3.1.

Si vous envoyez des clés interdites

UNKNOWN_FIELDLe mode strict rejette les propriétés inconnues à la racine ou sur staff.

Appliquées avant ou pendant la validation comme dans `sanitize.ts`. Elles expliquent les rejets INVALID_STAFF.

staffId

Trim ; longueur 1–128.
Caractères : /^[a-zA-Z0-9._-]+$/ (pas de slash ni d’antislash).

displayName

Supprimer caractères de contrôle et zero-width ; fusionner les espaces ; trim.
Les chevrons < et > sont interdits.
Max. 128 caractères après assainissement ; ne doit pas devenir vide.

Clés de cellule (requirements / availableCells)

Les clés sont trimmées ; doivent correspondre exactement aux cellKey de la grille calculée.

202 Accepted

Le corps a passé la validation et la condition a été écrite ; l’optimisation peut continuer de façon asynchrone. Le gestionnaire peut renvoyer un JSON avec conditionId et champs associés.

Les erreurs de validation renvoient une information structurée avec un `code` stable. L’analyse précède la validation (INVALID_JSON, PAYLOAD_TOO_LARGE). Les échecs de persistance peuvent apparaître comme DYNAMODB_ERROR. PATCH /v1/schedule-defaults peut renvoyer SCHEDULE_DEFAULTS_SAVE_FAILED (HTTP 400) avec des détails.

INVALID_JSON
Le corps n’est pas du JSON valide.
PAYLOAD_TOO_LARGE
Longueur en octets UTF-8 supérieure à maxPayloadBytes (défaut 512 KiB).
TYPE_ERROR
Type JSON incorrect ou chaîne apiVersion non prise en charge.
UNKNOWN_FIELD
Mode strict : propriété interdite sur la racine ou l’objet staff.
INVALID_TIME_ZONE
timeZone manquant ou nom IANA invalide.
INVALID_DATE_RANGE
Dates pas au format YYYY-MM-DD, plage invalide ou énumération vide.
SCHEDULE_SPAN_TOO_LONG
Trop de jours entre début et fin (voir maxScheduleDays).
INVALID_TIME_RANGE
Plage horaire manquante ou zéro créneau.
INVALID_GRANULARITY
slotGranularityMinutes pas 60/15 ou non autorisé par le plan.
INVALID_REQUIREMENTS
requirementsByCell n’est pas un objet ou le compte n’est pas un entier 0–15.
UNKNOWN_CELL_KEY
Clé absente de la grille de planning calculée.
INVALID_STAFF
staff vide, trop grand, ligne invalide ou assainissement échoué.
DUPLICATE_STAFF_ID
Valeurs staffId dupliquées.
INVALID_AVAILABLE_CELL
Entrée vide ou inconnue dans availableCells.
SHORTFALL_CELLS
Disponibilité insuffisante par rapport aux besoins.
DYNAMODB_ERROR
Erreur transitoire ou de persistance après validation (selon le gestionnaire).
SCHEDULE_DEFAULTS_SAVE_FAILED
PATCH /v1/schedule-defaults : validation ou règles métier en échec (voir error.details).
LABOR_COMPLIANCE_REQUIRED
PATCH /v1/staff/{staffId} : laborConstraintMask envoyé alors que laborLawCompliance est false.

Code	Signification
INVALID_JSON	Le corps n’est pas du JSON valide.
PAYLOAD_TOO_LARGE	Longueur en octets UTF-8 supérieure à maxPayloadBytes (défaut 512 KiB).
TYPE_ERROR	Type JSON incorrect ou chaîne apiVersion non prise en charge.
UNKNOWN_FIELD	Mode strict : propriété interdite sur la racine ou l’objet staff.
INVALID_TIME_ZONE	timeZone manquant ou nom IANA invalide.
INVALID_DATE_RANGE	Dates pas au format YYYY-MM-DD, plage invalide ou énumération vide.
SCHEDULE_SPAN_TOO_LONG	Trop de jours entre début et fin (voir maxScheduleDays).
INVALID_TIME_RANGE	Plage horaire manquante ou zéro créneau.
INVALID_GRANULARITY	slotGranularityMinutes pas 60/15 ou non autorisé par le plan.
INVALID_REQUIREMENTS	requirementsByCell n’est pas un objet ou le compte n’est pas un entier 0–15.
UNKNOWN_CELL_KEY	Clé absente de la grille de planning calculée.
INVALID_STAFF	staff vide, trop grand, ligne invalide ou assainissement échoué.
DUPLICATE_STAFF_ID	Valeurs staffId dupliquées.
INVALID_AVAILABLE_CELL	Entrée vide ou inconnue dans availableCells.
SHORTFALL_CELLS	Disponibilité insuffisante par rapport aux besoins.
DYNAMODB_ERROR	Erreur transitoire ou de persistance après validation (selon le gestionnaire).
SCHEDULE_DEFAULTS_SAVE_FAILED	PATCH /v1/schedule-defaults : validation ou règles métier en échec (voir error.details).
LABOR_COMPLIANCE_REQUIRED	PATCH /v1/staff/{staffId} : laborConstraintMask envoyé alors que laborLawCompliance est false.

{
  "apiVersion": "2026-04-01",
  "timeZone": "Asia/Tokyo",
  "scheduleStartDate": "2026-04-07",
  "scheduleEndDate": "2026-04-13",
  "timeRangeStart": "08:00",
  "timeRangeEnd": "20:00",
  "slotGranularityMinutes": 60,
  "requirementsByCell": {
    "2026-04-07__slot-0": 2
  },
  "staff": [
    {
      "staffId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Example",
      "availableCells": ["2026-04-07__slot-0"]
    }
  ]
}

Pour aller plus loin. Offres et fonctions payantes : docs/architecture/NURSE_SCHEDULING_SERVICE_SPECIFICATION.md. Corps POST /v1/schedule : docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §1–§11. Corps PATCH des valeurs par défaut locataire : même fichier §12. Code : app/lib/public-schedule-api/, app/features/schedule-settings/schedule-defaults-actions.ts, app/lib/public-api-write/weekly-shift-wish-tenant.ts. Déploiement : docs/aws/CDK_DEPLOY.md.

Référence API développeur (payant)

Méthode

Chemin

Description

GET

{baseUrl}/v1/schedule-results

Liste les lignes parentes SCHEDULE_RESULT : conditionId, status, candidateCount, createdAt/updatedAt, etc. Pagination DynamoDB.

GET

{baseUrl}/v1/schedule-results/history

Recherche d’historique des résultats (équivalent navigateur). from / to (ISO 8601, défaut début de service à maintenant), keyword, eventName (INSERT,MODIFY,REMOVE séparés par virgules), limit, cursor. Fusion automatique récent + archive ; retourne uniquement items / nextCursor.

GET

{baseUrl}/v1/schedule-results/{conditionId}

Récupère une ligne parente SCHEDULE_RESULT par conditionId (attributs JSON ; PK/SK omis).

GET

{baseUrl}/v1/schedule-results/{conditionId}/resolution

Sortie d’optimisation résolue : status, candidates, confirmedAssignments si présents. Si status est completed et pas encore confirmé, rank-1 peut être auto-confirmé sur ce GET (effet de bord). Utilisez POST …/confirm-assignments pour une confirmation manuelle.

GET

{baseUrl}/v1/schedule-results/{conditionId}/review

Charge utile de revue pour confirmation manuelle (candidats, requiredByCellKey, allowedCellKeys du personnel, etc.).

GET

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context

Contexte de shift d’urgence (dates, personnel, créneaux). Abonnement payant requis ; null si la condition est absente.

GET

{baseUrl}/v1/schedule-conditions

Liste les lignes parentes SCHEDULE_CONDITION (conditionId, dates, publicApiCancelledAt optionnel).

GET

{baseUrl}/v1/schedule-conditions/{conditionId}

Ligne parente de condition plus reqDays et staffSnapshots (sans PK/SK).

GET

{baseUrl}/v1/schedule-defaults

Ligne de valeurs par défaut du locataire (SCHEDULE_DEFAULTS) ou null si non enregistrée.

GET

{baseUrl}/v1/schedule-actual/{conditionId}

Ligne SCHEDULE_ACTUAL des affectations réelles, ou null si absente.

GET

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Ligne de souhaits hebdomadaires du collaborateur, ou null si absente.

GET

{baseUrl}/v1/staff

Liste les membres actifs du personnel du locataire (tri par nom affiché).

GET

{baseUrl}/v1/staff/{staffId}

Récupère un membre par staffId, détails travail inclus (laborLawCompliance, laborFlsaExempt, plafonds personnels, laborConstraintMask). Suppression logique → 404.

Méthode

Chemin

Description

PATCH

{baseUrl}/v1/schedule-defaults

Enregistre les valeurs par défaut de planning du locataire (corps JSON aligné sur saveSchema dans schedule-defaults-actions). Les champs payants suivent votre abonnement.

POST

{baseUrl}/v1/staff

Crée un membre du personnel (displayName). Renvoie 201 avec le JSON staff.

POST

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift

Clone un planning source terminé avec absences appliquées ; renvoie 201 avec conditionId. Abonnement payant requis.

POST

{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments

Valide et enregistre les affectations éditées manuellement (200 avec { ok: true }).

PATCH

{baseUrl}/v1/staff/{staffId}

Met à jour displayName et détails travail (laborLawCompliance, laborFlsaExempt, plafonds personnels, laborConstraintMask).

DELETE

{baseUrl}/v1/staff/{staffId}

Supprime logiquement un membre du personnel (définit deletedAt).

DELETE

{baseUrl}/v1/schedule-conditions/{conditionId}

Marque la condition comme annulée (publicApiCancelledAt) ; ne supprime pas les lignes enfants.

PUT

{baseUrl}/v1/schedule-actual/{conditionId}

Enregistre les affectations réelles JSON { "assignments": [ ... ] } (validées contre la grille de la condition).

PUT

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Remplace les souhaits hebdomadaires : grille complète (1–7 jours), wishByCellKey par cellule (NONE|LOW|HIGH) ; granularité selon les valeurs par défaut du locataire.

type

When

schedule.result.terminal

Schedule result status becomes completed, no_solution, failed, error, or canceled

{ "type": "schedule.result.terminal", "conditionId": "019ee481-e855-7000-abd8-977cbfd64ffc", "status": "completed", "occurredAt": "2026-07-16T13:00:54.694Z", "links": { "result": "{baseUrl}/v1/schedule-results/019ee481-e855-7000-abd8-977cbfd64ffc" } }

Header

Description

Content-Type

application/json

User-Agent

AutoScheduler-Webhook/1.0

X-AutoScheduler-Timestamp

Unix seconds as a string

X-AutoScheduler-Signature

v1=<hex> (see verification below)

En-tête

Description

x-api-key

Clé API liée à votre abonnement payant (identifie le locataire et les limites du plan).

Content-Type

application/json

Paramètre

API payante (typique)

Modèle de facturation

Abonnement Stripe ; les frais produit évoluent généralement avec le nombre de sièges (personnel enregistré) comme sur la page tarifs (pas de facturation à l’appel API).

maxScheduleDays

Jusqu’à 14 jours civils par envoi pour la planification détaillée standard sur deux semaines (plages plus larges uniquement si le contrat le permet).

maxStaffPerSchedule

Jusqu’à 500 lignes staff par POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF ; staffId en ligne dans le corps).

maxRosterStaff

Jusqu’à 30 collaborateurs actifs via POST /v1/staff (STAFF_ROSTER_MAX_PAID) ; 409 STAFF_LIMIT si dépassement.

allowedGranularities

[60, 15] — les créneaux de 15 minutes sont une fonctionnalité payante ; 60 minutes est aussi pris en charge.

maxPayloadBytes

524288 (512 KiB) UTF-8 sauf plafond supérieur accordé.

strictUnknownRootKeys

true — les clés inconnues à la racine ou dans staff sont rejetées

Champ

Type

Obligatoire

Notes

timeZone

string

Oui

Fuseau horaire IANA pour interpréter les dates et les créneaux.

scheduleStartDate / scheduleEndDate

string (YYYY-MM-DD)

Oui

Plage de calendrier inclusive ; début ≤ fin.

timeRangeStart / timeRangeEnd

string (HH:mm)

Oui

Plage horaire « horloge murale » qui définit la colonne de créneaux ; doit produire au moins un créneau.

slotGranularityMinutes

60 | 15

Oui

API payante : 60 (heure) ou 15 (quarts d’heure). Doit figurer dans allowedGranularities.

requirementsByCell

object

Oui

Clés = cellKey dans la grille calculée ; valeurs = entier 0–15.

staff

array

Oui

Non vide ; taille max. selon les limites ; chaque élément : staffId, displayName, availableCells facultatif.

Référence des champs (valeurs autorisées)

Code

Signification

INVALID_JSON

Le corps n’est pas du JSON valide.

PAYLOAD_TOO_LARGE

Longueur en octets UTF-8 supérieure à maxPayloadBytes (défaut 512 KiB).

TYPE_ERROR

Type JSON incorrect ou chaîne apiVersion non prise en charge.

UNKNOWN_FIELD

Mode strict : propriété interdite sur la racine ou l’objet staff.

INVALID_TIME_ZONE

timeZone manquant ou nom IANA invalide.

INVALID_DATE_RANGE

Dates pas au format YYYY-MM-DD, plage invalide ou énumération vide.

SCHEDULE_SPAN_TOO_LONG

Trop de jours entre début et fin (voir maxScheduleDays).

INVALID_TIME_RANGE

Plage horaire manquante ou zéro créneau.

INVALID_GRANULARITY

slotGranularityMinutes pas 60/15 ou non autorisé par le plan.

INVALID_REQUIREMENTS

requirementsByCell n’est pas un objet ou le compte n’est pas un entier 0–15.

UNKNOWN_CELL_KEY

Clé absente de la grille de planning calculée.

INVALID_STAFF

staff vide, trop grand, ligne invalide ou assainissement échoué.

DUPLICATE_STAFF_ID

Valeurs staffId dupliquées.

INVALID_AVAILABLE_CELL

Entrée vide ou inconnue dans availableCells.

SHORTFALL_CELLS

Disponibilité insuffisante par rapport aux besoins.

DYNAMODB_ERROR

Erreur transitoire ou de persistance après validation (selon le gestionnaire).

SCHEDULE_DEFAULTS_SAVE_FAILED

PATCH /v1/schedule-defaults : validation ou règles métier en échec (voir error.details).

LABOR_COMPLIANCE_REQUIRED

PATCH /v1/staff/{staffId} : laborConstraintMask envoyé alors que laborLawCompliance est false.

{ "apiVersion": "2026-04-01", "timeZone": "Asia/Tokyo", "scheduleStartDate": "2026-04-07", "scheduleEndDate": "2026-04-13", "timeRangeStart": "08:00", "timeRangeEnd": "20:00", "slotGranularityMinutes": 60, "requirementsByCell": { "2026-04-07__slot-0": 2 }, "staff": [ { "staffId": "550e8400-e29b-41d4-a716-446655440000", "displayName": "Example", "availableCells": ["2026-04-07__slot-0"] } ] }

Référence API développeur (payant)

Périmètre de cette documentation

Abonnement et accès

Authentification

Point de terminaison

Utilisation (démarrage rapide)

Exemple curl (bash / macOS / Linux / WSL)

API en lecture (GET)

API en écriture (PATCH / POST / PUT / DELETE)

Completion webhooks

Setup

Events

Request body

Request headers

Signature verification

Retries

En-têtes

En-têtes de réponse

Limites du niveau payant (droits)

Clés racine autorisées (mode strict)

Corps de la requête (aperçu)

Tableau de référence rapide

Référence des champs (valeurs autorisées)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Droit du travail et optimisation payante (pas dans le corps JSON)

Règles d’assainissement

Réponse de succès

Codes d’erreur (liste complète)

Exemple JSON minimal

Référence API développeur (payant)

Périmètre de cette documentation

Abonnement et accès

Authentification

Point de terminaison

Utilisation (démarrage rapide)

Exemple curl (bash / macOS / Linux / WSL)

API en lecture (GET)

API en écriture (PATCH / POST / PUT / DELETE)

Completion webhooks

Setup

Events

Request body

Request headers

Signature verification

Retries

En-têtes

En-têtes de réponse

Limites du niveau payant (droits)

Clés racine autorisées (mode strict)

Corps de la requête (aperçu)

Tableau de référence rapide

Référence des champs (valeurs autorisées)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Droit du travail et optimisation payante (pas dans le corps JSON)

Règles d’assainissement

Réponse de succès

Codes d’erreur (liste complète)

Exemple JSON minimal