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.
Périmètre de cette documentation
Cette page documente l'API REST produit pour les intégrations externes.
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.
Abonnement et accès
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.
Authentification
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. Les opérations hors scopes renvoient 403 (API_KEY_SCOPE_DENIED). Les clés sans attribut scopes autorisent encore toutes les opérations.
Collez le bloc ci-dessous dans un assistant de chat lorsque vous voulez de l'aide pour appeler cette API produit sans configurer MCP.
Il résume l'URL de base, l'authentification, les opérations principales et les précautions d'écriture. Il n'inclut jamais de vraie clé API.
Pour des appels API réels depuis un agent, configurez MCP (agents) plutôt que de vous fier uniquement à ce collage.
Contexte à coller
Auto Scheduler — Public API context for LLM assistants
Use this when helping a developer call the Auto Scheduler paid product REST API (/v1/*). Prefer configuring Tools MCP when available; this paste is for chat without MCP.
Base URL
- https://api.autoschedulers.com
- Paths are under /v1/*. Do not confuse this with the marketing website origin.
Authentication
- Every request needs header: x-api-key: <API_KEY>
- Never paste a real API key into chat logs or this prompt; ask the user to supply it via environment or a secret store.
- Keys are created in the product under Account → API management.
- JSON writes: Content-Type: application/json
Read endpoints
- GET /v1/schedule-results?limit=10
- GET /v1/schedule-results/{conditionId}
- GET /v1/schedule-conditions
- GET /v1/staff
- GET /v1/staff/{staffId}
- GET /v1/schedule-defaults
- GET /v1/schedule-results/{conditionId}/emergency-shift-context
Write endpoints (confirm with the user before calling)
- POST /v1/schedule — starts a job; may incur charges; max 14 calendar days
- PATCH /v1/schedule-defaults — tenant-wide
- POST /v1/staff
- PATCH /v1/staff/{staffId}
- PUT /v1/staff/{staffId}/weekly-shift-wish — full replace
- POST /v1/schedule-results/{conditionId}/emergency-shift — paid
- POST /v1/schedule-results/{conditionId}/confirm-assignments
- DELETE /v1/schedule-conditions/{conditionId}
- PUT /v1/schedule-actual/{conditionId} — full replace
Minimal curl (read)
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.autoschedulers.com/v1/staff"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.autoschedulers.com/v1/schedule-results?limit=10"
Contract notes
- Schedule submit body needs a supported apiVersion and valid JSON fields — see api-docs Field reference or Docs MCP Resources; do not invent fields.
- planningHorizon on defaults is only week or two_weeks (month_attendance is rejected).
- Outbound completion webhooks are HMAC-signed HTTPS callbacks configured in API management (not REST CRUD).
Safety
- Write endpoints change tenant data. Confirm destructive or irreversible actions with the user before calling them.
- Prefer read/list first when exploring an unfamiliar tenant.
Point de terminaison
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.
URL de base
Hôte de l'API REST publique (/v1/*), pas l'URL du site navigateur. Définissez AUTO_SCHEDULER_PUBLIC_API_BASE_URL (MCP) et BASE_URL (curl) sur cette valeur.
AUTO_SCHEDULER_PUBLIC_API_BASE_URL — URL de base configurée pour cet environnement de documentation. Utilisez la même valeur dans MCP et curl.
Utilisez l’URL de base fournie lors du provisionnement de l’accès API ou par votre contact d’exploitation.
Utilisation (démarrage rapide)
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.
Vous pouvez appeler la même API REST produit depuis des agents comme Cursor, Claude, Gemini et GPT via MCP. Les opérations correspondent à la surface /v1 de cette page.
Les serveurs MCP fournis utilisent stdio local. Ajoutez command / args / env dans chaque fichier de config client. Créez les clés dans Gestion des API (ne jamais les committer ni les coller dans des chats publics).
Pour la documentation seule, un MCP Resources n'exige ni connexion ni clé API (mcp/api-docs). Cette page (/{locale}/api-docs) est aussi consultable sans connexion ; la création de clés exige toujours Compte → Gestion des API.
Chemin le plus rapide (recommandé)
Create an API key in Account → API management (never paste the real key into chat).
In the repo: cd mcp/public-api && npm install && npm run build (also mcp/api-docs if you want documentation Resources).
Copy the env snippet below and the Cursor mcp.json under Client-specific setup; replace paths and YOUR_* placeholders.
Restart the client and confirm Tools (list_staff, …) appear. Prefer read tools before any write.
Quelle option utiliser
Tools MCP (public-api)
Live /v1 calls with your API key. Use this when the agent should actually list staff, submit schedules, etc.
Docs MCP (api-docs Resources)
Contract markdown only—no API key. Use when the agent needs field rules or request-body shape.
Copy for LLM (this page)
Orientation text for chat assistants without MCP. Not enough alone for correct request bodies—pair with MCP or the sections below.
Variables d'environnement requises (Tools MCP)
AUTO_SCHEDULER_PUBLIC_API_BASE_URL
URL de base de l'API REST publique (/v1/*)—pas le domaine du site. Utilisez l'hôte API fourni (slash final facultatif)
AUTO_SCHEDULER_API_KEY
Clé issue de Gestion des API (ne pas committer ni publier)
Variable
Description
AUTO_SCHEDULER_PUBLIC_API_BASE_URL
URL de base de l'API REST publique (/v1/*)—pas le domaine du site. Utilisez l'hôte API fourni (slash final facultatif)
AUTO_SCHEDULER_API_KEY
Clé issue de Gestion des API (ne pas committer ni publier)
Créer une clé API dans Gestion des API (Tools MCP uniquement ; inutile pour le MCP docs)
Dans le dépôt : cd mcp/public-api → npm install && npm run build (et mcp/api-docs si vous voulez Resources)
Suivez les étapes par client ci-dessous et ajustez chemins et env pour votre machine
Redémarrez le client (ou reconnectez MCP) et confirmez que tools / resources apparaissent
Configuration par client
La forme JSON est presque partout la même. Ce qui change est l'emplacement du fichier de config—et que ChatGPT (GPT) ne lance pas de serveurs stdio locaux.
Cursor
mcp.json utilisateur (ex. Windows %USERPROFILE%\.cursor\mcp.json). Vous pouvez aussi modifier via Cursor Settings → MCP.
Ajoutez le fragment ci-dessous sous mcpServers (gardez les serveurs existants)
Remplacez les chemins absolus et YOUR_BASE_URL / YOUR_API_KEY
Redémarrez Cursor et confirmez des Tools comme list_staff et des Resources depuis api-docs
Sous Windows, échappez les barres inverses en \\ dans le JSON. Sous macOS / Linux, utilisez des chemins avec barre oblique.
Les connecteurs de la console cloud Gemini ciblent le MCP distant. Utilisez Gemini CLI pour stdio local.
GPT (ChatGPT / OpenAI)
Paramètres du connecteur ChatGPT (MCP distant uniquement). Il n'y a pas de mcp.json local pour ChatGPT.
ChatGPT (connecteurs web / bureau) ne peut pas lancer de processus MCP stdio locaux
Ce produit ne fournit que du MCP stdio local, donc ChatGPT ne peut pas s'y connecter directement
Pour des agents de type GPT : (1) exécutez le même MCP dans Cursor / Claude / Gemini CLI, ou (2) appelez l'API REST de cette page avec x-api-key depuis Custom Actions / votre client API
Vous ne pouvez enregistrer un connecteur ChatGPT que si vous hébergez vous-même un MCP HTTPS distant (non fourni en standard).
OpenAI Agents / Responses API attendent aussi un MCP distant (HTTP). Les serveurs fournis sont pour clients stdio.
Aperçu des outils (public-api)
Des outils de lecture et d'écriture sont disponibles. Les écritures peuvent lancer des tâches facturées ou modifier des paramètres d'organisation—confirmez avant d'appeler.
If status is completed and not yet confirmed, rank-1 may be auto-confirmed on this GET (side effect). Prefer POST …/confirm-assignments for explicit confirmation.
Même clé API et corps JSON que les autres routes /v1. Chaque carte montre un corps de requête minimal à copier. Comptes utilisateurs, profil société et journaux d'audit restent dans l'app web — pas dans cette API. POST /v1/staff renvoie 409 STAFF_LIMIT si le roster dépasse le plafond du locataire.
Les champs travail et Soft prefer/avoid exigent un abonnement payant. Remplacez les UUID, dates et clés de cellule d'exemple par vos données locataire.
PATCH{baseUrl}/v1/schedule-defaults
Saves tenant-wide schedule defaults. Paid-tier fields follow your subscription.
requirementsByCellKey must include every cell in period × slots (missing/extra keys → 400). Cell key = YYYY-MM-DD__HH:mm. planningHorizon: week | two_weeks (month_attendance rejected). Optional: requiredRolesByCellKey, laborLawJurisdiction, usLaborStateCode, linkedMonthPlanStartDate / linkedMonthPlanEndDate, laborModelVersion.
Clones a completed source schedule with absences applied. Returns 201 with new conditionId. Paid subscription required.
Prefer absentDayPairs. Legacy: absentStaffIds + absentDatesYmd (Cartesian). You may also send absentSlots. Optional substituteDayPairs / substituteSlots open coverage (source must be completed).
Updates one staff member. Send any subset of the fields in the example.
Personal max minutes: integer or null to clear. laborConstraintMask only when laborLawCompliance is true. schedulingRoleIds / Soft prefer-avoid: UUID arrays; unknown catalog IDs filtered; prefer and avoid must be disjoint. Labor and Soft require paid.
Replaces the weekly wish grid for one staff member (full replace).
Dates/time range must match the tenant weekly-wish navigation window from schedule defaults. wishByCellKey must cover every cell in that window. Values: NONE | LOW | HIGH.
Lorsqu'un résultat de planning atteint un statut terminal, nous POSTONS une notification JSON signée vers votre URL HTTPS. Le corps n'inclut pas le résultat complet ; récupérez les détails avec GET /v1/schedule-results/{conditionId}.
Les résultats du playground ne sont pas livrés. Si le webhook est désactivé ou qu'aucune URL n'est enregistrée, rien n'est envoyé.
Configuration
Après connexion, ouvrez Gestion des API et enregistrez une URL de notification HTTPS.
Activez « Activer les notifications ».
Copiez le secret de signature affiché une seule fois (il ne peut pas être révélé à nouveau ; régénérez-le s'il est perdu).
Vérifiez la signature sur votre récepteur, puis GET links.result avec votre clé API si besoin.
Événements
Type d'événement et moment d'envoi.
schedule.result.terminal
Le statut du résultat de planning devient completed, no_solution, failed, error ou canceled
type
Quand
schedule.result.terminal
Le statut du résultat de planning devient completed, no_solution, failed, error ou canceled
Corps de la requête
status est uniquement terminal. customerId est omis du corps.
Calculez un digest à partir du corps brut (avant parse JSON) et du Timestamp, puis comparez à Signature. Rejetez si |now − timestamp| dépasse 300 secondes (5 minutes), sauf si vous autorisez volontairement un décalage d'horloge plus large.
En cas de 5xx ou de délai d'attente, nous réessayons automatiquement. Les échecs persistants vont dans une file dead-letter. Les notifications push navigateur utilisent un autre chemin.
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 du niveau payant (droits)
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 sur deux semaines (plafond fixe ; non étendu par contrat).
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.
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 sur deux semaines (plafond fixe ; non étendu par contrat).
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.
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 n’est pas dans le JSON. paidOptimization est facultatif pour apiVersion 2026-09-13+ (sinon valeurs par défaut du locataire). Les champs Soft prefer/avoid du personnel exigent 2026-09-14. Voir « Droit du travail et options payantes ». N’incluez pas les clés DynamoDB ni les types d’entité internes dans le corps.
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).
Tableau de référence rapide
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.
requiredRolesByCell
Type
object
Obligatoire
Non — 2026-09-09 uniquement
cellKey → roleId→need. Somme des need par cellule ≤ requirementsByCell. Versions héritées → UNKNOWN_FIELD.
staff
Type
array
Obligatoire
Oui
Non vide ; taille max. selon les limites ; chaque élément : staffId, displayName, availableCells / laborConstraintMask / schedulingRoleIds (2026-09-09+) / Soft prefer-avoid (2026-09-14) facultatifs.
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.
requiredRolesByCell
object
Non — 2026-09-09 uniquement
cellKey → roleId→need. Somme des need par cellule ≤ requirementsByCell. Versions héritées → UNKNOWN_FIELD.
staff
array
Oui
Non vide ; taille max. selon les limites ; chaque élément : staffId, displayName, availableCells / laborConstraintMask / schedulingRoleIds (2026-09-09+) / Soft prefer-avoid (2026-09-14) facultatifs.
Référence des champs (valeurs autorisées)
Les règles de champs suivantes correspondent au validateur de l’API publique. Envoyez les nombres JSON comme nombres réels (pas comme chaînes). Après validation, le serveur peut enregistrer des valeurs par défaut parentes (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 ».
apiVersion
string | omis · Obligatoire: Non — facultatif
Valeurs autorisées
Omis : accepté (comportement actuel).
Si présent, doit être « 2026-04-01 », « 2026-09-09 », « 2026-09-13 » ou « 2026-09-14 ». Dernière version publiée : 2026-09-14.
Toute autre chaîne est rejetée (TYPE_ERROR).
Comportement
Comparaison après traitement équivalent à un trim dans sanitizeApiVersion.
La version sélectionne les ensembles de clés autorisés au niveau racine et dans l'objet staff (rôles en 2026-09-09+ ; paidOptimization en 2026-09-13+ ; Soft prefer/avoid en 2026-09-14).
Erreurs typiques
TYPE_ERRORValeur apiVersion non prise en charge.
timeZone
string · Obligatoire: Oui
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.
scheduleStartDate, scheduleEndDate
string, string · Obligatoire: Oui — les deux
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 : plafond fixe de 14 jours pour la planification sur deux semaines).
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.
timeRangeStart, timeRangeEnd
string, string · Obligatoire: Oui — les deux
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.
slotGranularityMinutes
number (nombre JSON) · Obligatoire: Oui
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.
requirementsByCell
Record<string, number> · Obligatoire: Oui
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.
Accepté uniquement lorsque apiVersion est « 2026-09-09 ». Omise / 2026-04-01 → UNKNOWN_FIELD.
Doit être un objet JSON simple. Chaque clé est un cellKey de la grille requirements.
Chaque valeur est un objet associant roleId (UUID) → need entier ≥ 1.
Pour chaque cellule, sum(need) doit être ≤ requirementsByCell[cell] (ou 0 si omis).
Le chemin d'envoi ne valide que la forme UUID et la somme (pas de lookup catalogue).
Comportement
Les valeurs sont normalisées et validées (ID de rôle UUID ; somme des need ≤ effectifs).
Persisté comme requiredRolesBySlot sur les lignes de besoin quotidien.
Erreurs typiques
UNKNOWN_FIELDEnvoyé avec une apiVersion héritée.
INVALID_REQUIREMENTSForme incorrecte, roleId non UUID, ou somme supérieure aux effectifs.
UNKNOWN_CELL_KEYcellKey hors de la grille calculée.
staff
array · Obligatoire: Oui — tableau non vide
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 pour l’apiVersion : staffId, displayName, availableCells, laborConstraintMask ; plus schedulingRoleIds en 2026-09-09+ ; plus preferredSchedulingRoleIds / avoidedSchedulingRoleIds en 2026-09-14 (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.
staff[].availableCells
string[] | omis · Obligatoire: Non — facultatif
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.
staff[].schedulingRoleIds / Soft prefer-avoid
string[] | omitted · Obligatoire: Non — facultatif ; rôles en 2026-09-09+ ; Soft en 2026-09-14
Tableaux JSON de chaînes UUID. Les doublons sont supprimés. Soft prefer ∩ avoid doit être vide.
Tableau vide / omis = pas de cadre de rôle Hard / préférence Soft sur le snapshot de condition.
Le chemin d'envoi ne filtre pas contre le catalogue locataire ; PATCH /v1/staff/{staffId} le fait (PATCH Soft payant).
Comportement
Les valeurs sont normalisées (chaînes UUID ; doublons supprimés). Chevauchement Soft → INVALID_STAFF.
Copié sur les lignes du snapshot de condition staff lorsqu'il n'est pas vide.
Erreurs typiques
UNKNOWN_FIELDEnvoyé avec une apiVersion qui n’autorise pas la clé.
INVALID_STAFFCe n'est pas un tableau, élément non UUID ou chevauchement Soft prefer/avoid.
Droit du travail et optimisation payante (pas dans le corps JSON)
n/a — persisté côté serveur · Dans la requête: Non — n’envoyez jamais ces clés
Ce que l’API enregistre sur la ligne parente
L’API publique n’accepte que les clés racine et les clés d’objet staff autorisées pour votre apiVersion. N’envoyez pas laborLawJurisdiction, usLaborStateCode ni laborModelVersion. paidOptimization est facultatif pour apiVersion 2026-09-13+. Les champs Soft prefer/avoid du personnel exigent 2026-09-14.
À l’envoi, le serveur remplit la ligne parente SCHEDULE_CONDITION avec les valeurs partagées : paidOptimization du corps (apiVersion 2026-09-13+) ou SCHEDULE_DEFAULTS du locataire si omis ; sinon DEFAULT_PAID_OPTIMIZATION (laborLawCompliance parent forcé à true). laborLawJurisdiction / usLaborStateCode / laborModelVersion sont hérités de SCHEDULE_DEFAULTS du locataire (repli JP / GENERIC / modèle selon la juridiction).
Les contraintes de type légal dans l’optimiseur exigent les indicateurs de conformité parent et par personne. Les indicateurs par personne ne sont pas dans le JSON : le serveur les hérite de la liste du personnel (staffId absents = activés par défaut). POST /v1/staff crée aussi activé ; désactiver par personne via PATCH payant /v1/staff/{staffId}.
Le modèle travail est une approximation pour la planification, pas un conseil juridique. Catalogue : .
Documentation
Détail : this page 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.
Règles d’assainissement
Appliqué avant ou pendant la validation. Ces règles expliquent pourquoi une valeur peut être rejetée comme 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.
Réponse de succès
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.
Codes d’erreur (liste complète)
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.
Sur cette page. POST /v1/schedule : référence des champs et tableau. Valeurs par défaut : points d'écriture → PATCH /v1/schedule-defaults. Travail / Soft : PATCH /v1/staff/{staffId}. Offres : page tarifs.