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 ne couvre que l’API REST produit sur API Gateway ({stage}/v1/*, authentification x-api-key).
Les routes Next.js /api/* (webhooks Stripe, images OG, Web Vitals, etc.) sont internes à l’application web et ne font pas partie de cette API développeur. Ne les utilisez pas pour des intégrations externes.
GET /v1/processing-history n’est pas proposé (supprimé avec l’ancienne interface) et n’apparaît pas dans la liste des points de terminaison de cette page.
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.
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.
La lecture et la mise à jour des données d’entreprise (GET/PATCH /v1/company) nécessitent un abonnement payant actif. Si la facturation n’est pas configurée pour votre locataire, vous pouvez recevoir **503** (p. ex. code **STRIPE_NOT_CONFIGURED**).
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/company"
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 /v1/company et les mises à jour d’entreprise nécessitent un abonnement payant actif. Si la facturation n’est pas configurée, vous pouvez recevoir **503 / STRIPE_NOT_CONFIGURED**.
| 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/audit-logs | Liste les entrées du journal d’audit (plus récentes d’abord ; pagination par cursor). |
| 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/company | Renvoie les champs Stripe Customer (nom, e-mail, téléphone, adresse) pour le customerId lié à votre clé API. |
| GET | {baseUrl}/v1/users | Liste les utilisateurs du locataire (facultatif : limit, cursor, userName, permissionProfileId, scope fullAccess|nonFullAccess). |
| GET | {baseUrl}/v1/users/{userId} | Récupère un utilisateur par le userId indiqué dans le chemin. |
| 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/company refuse les chaînes vides pour des champs tels que le nom de l’entreprise (aligné sur l’application web). 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). DELETE /v1/users/{userId} renvoie 409 s’il ne resterait aucun utilisateur actif ou lors de la suppression du dernier administrateur. POST /v1/staff renvoie 409 STAFF_LIMIT si l’effectif dépasserait la limite du locataire.
POST /v1/users exige userName, email, permissionProfileId ; facultatif : locale, password. PATCH utilisateur : champs à modifier uniquement. 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.
| Méthode | Chemin | Description |
|---|---|---|
| PATCH | {baseUrl}/v1/company | Met à jour les champs du profil d’entreprise (client de facturation). |
| 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/users | Crée un utilisateur. Renvoie 201 avec le JSON utilisateur. |
| PATCH | {baseUrl}/v1/users/{userId} | Met à jour les champs utilisateur (userName, email, permissionProfileId, locale). |
| DELETE | {baseUrl}/v1/users/{userId} | Supprime un utilisateur. 409 s’il ne resterait aucun utilisateur ou règle du dernier administrateur. |
| 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. |
| POST | {baseUrl}/v1/users/{userId}/restore | Restaure un utilisateur supprimé logiquement. |
| 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 |
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).
| 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.
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.
| 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. |
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 ».
string | omis · Obligatoire: Non — facultatif
Valeurs autorisées
Comportement
Erreurs typiques
TYPE_ERRORValeur apiVersion non prise en charge.string · Obligatoire: Oui
Valeurs autorisées
Comportement
Erreurs typiques
INVALID_TIME_ZONEManquant, vide ou zone IANA invalide.string, string · Obligatoire: Oui — les deux
Valeurs autorisées
Comportement
Erreurs typiques
INVALID_DATE_RANGEMauvais format, dates invalides ou plage vide.SCHEDULE_SPAN_TOO_LONGPlus de maxScheduleDays jours.string, string · Obligatoire: Oui — les deux
Valeurs autorisées
Comportement
Erreurs typiques
INVALID_TIME_RANGEValeurs manquantes ou zéro créneau pour la plage.number (nombre JSON) · Obligatoire: Oui
Valeurs autorisées
Comportement
Erreurs typiques
INVALID_GRANULARITYPas 60/15 ou non autorisé par le plan.Record<string, number> · Obligatoire: Oui
Valeurs autorisées
Comportement
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.array · Obligatoire: Oui — tableau non vide
Valeurs autorisées
Comportement
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.string[] | omis · Obligatoire: Non — facultatif
Valeurs autorisées
Contrôle SHORTFALL
Erreurs typiques
INVALID_AVAILABLE_CELLClé de cellule inconnue ou entrée vide.SHORTFALL_CELLSPersonnel insuffisant par rapport au besoin pour une cellule.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
Documentation
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
displayName
Clés de cellule (requirements / availableCells)
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.
| 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.