Lis et modifie le planning depuis tes propres outils : une API REST en JSON protégée par une clé, et des webhooks signés pour être prévenu de ce qui change. N’importe quel client HTTP convient.
URL de base
https://api.swissplanif.ch/api/v1
Authentification
Clé dans l’en-tête Authorization
Format
JSON, UTF-8, dates en UTC
Débit
100 requêtes par 60 s
Relu contre le code et la production le 13 novembre 2026.
Démarrage rapide
1
Crée une clé
Dans Réglages → Clés API, crée une clé avec les seules permissions dont ton intégration a besoin. Elle s’affiche une seule fois : range-la tout de suite dans ton gestionnaire de secrets.
2
Garde-la hors du code
Ton programme lit la clé dans une variable d’environnement, ici SWISSPLANIF_TOKEN. Ne l’écris ni dans un dépôt, ni dans une URL, ni dans une page web ou une application mobile.
3
Fais un premier appel
Liste tes sites avec une clé qui porte locations:read. C’est une lecture : elle ne modifie rien.
Chaque requête porte l’en-tête Authorization: Bearer suivi de ta clé. Il n’y a ni cookie, ni clé dans l’URL.
Une clé commence par stk_live_, suivi de 64 caractères tirés au hasard (48 octets). Nous n’en gardons que l’empreinte SHA-256 : personne, nous compris, ne peut te la réafficher. Si tu la perds, crée-en une autre.
Une clé ouvre les données de toute l’organisation, dans la limite de ses permissions. Pour en créer une, il faut donc un compte autorisé à gérer les clés d’API et dont l’accès couvre toute l’organisation.
Une clé révoquée ou expirée est refusée dès l’appel suivant, avec un 401. Sa durée de vie se choisit à la création : 30, 90 (proposé par défaut) ou 365 jours, ou sans expiration.
Permissions
Une clé porte une ou plusieurs permissions. Un appel qui en demande une autre est refusé avec un 403. Lecture et écriture sont séparées : une clé de tableau de bord n’a jamais besoin d’écrire.
URL de base : https://api.swissplanif.ch/api/v1. La version est dans le chemin : un changement incompatible passera par un nouveau préfixe, jamais par une modification en place.
HTTPS seulement. Écris toujours https:// : une clé envoyée en clair doit être considérée comme perdue.
Requêtes et réponses en JSON (UTF-8). Envoie Content-Type: application/json dès qu’il y a un corps.
Les dates sont des instants ISO 8601 en UTC, terminés par Z, par exemple 2026-11-16T07:00:00Z. Un décalage comme +01:00 est refusé.
Les identifiants sont des UUID.
Un champ inconnu dans un corps est ignoré, pas refusé.
Un corps de requête pèse 5 Mo au plus.
Pagination
Seule la liste des créneaux est paginée. limit fixe la taille d’une page, de 1 à 200, 50 par défaut. Tant que la réponse contient un nextCursor, renvoie-le dans cursor pour lire la page suivante ; null signifie que tu as tout lu.
Les pages sont triées par identifiant. L’ordre est stable d’une page à l’autre, mais il n’est pas chronologique : trie sur start de ton côté si tu en as besoin.
Les listes d’employés, de sites et de postes renvoient tout en une seule réponse.
Objets
Les quatre objets que l’API renvoie. Un champ marqué « ou null » peut être vide.
Créneau
iduuid
Identifiant du créneau.
startdatetime
Début.
enddatetime
Fin.
breakMinutesinteger
Pause, en minutes.
statusenum
État du créneau.DRAFTPUBLISHEDCOMPLETEDCANCELLED
positionIduuid
Poste.
positionNamestring
Nom du poste.
locationIduuid
Site.
locationNamestring
Nom du site.
employeeIduuid · ou null
Personne affectée ; vide si le créneau n’est attribué à personne.
employeeFullNamestring · ou null
Prénom et nom de cette personne.donnée personnelle
notestring · ou null
Note libre.donnée personnelle
createdAtdatetime
Création.
updatedAtdatetime
Dernière modification.
Employé
iduuid
Identifiant de l’employé.
firstNamestring
Prénom.donnée personnelle
lastNamestring
Nom.donnée personnelle
emailstring · ou null
Adresse e-mail, si elle est renseignée.donnée personnelle
contractTypeenum
Type de contrat.PERMANENTFIXED_TERMTEMPINTERNFREELANCE
weeklyHoursnumber
Heures hebdomadaires du contrat.
locationIdsuuid[]
Sites auxquels la personne est rattachée.
positionIdsuuid[]
Postes qu’elle peut tenir.
Site
iduuid
Identifiant du site.
namestring
Nom.
addressstring · ou null
Adresse, si elle est renseignée.
timezonestring
Fuseau horaire IANA, par exemple Europe/Zurich.
Poste
iduuid
Identifiant du poste.
namestring
Nom.
colorstring
Couleur d’affichage, en hexadécimal.
requiredSkillsstring[]
Compétences exigées pour tenir le poste.
Points d’entrée
Tous les chemins partent de l’URL de base. En plus des erreurs propres à chaque appel, tous peuvent répondre 401, 403 et 429.
GET/shiftsPermissionshifts:read
Lister les créneaux
Renvoie les créneaux de l’organisation, par pages.
from et to filtrent sur l’heure de début : from est inclus, to est exclu.
Tous les états sont renvoyés, créneaux annulés compris : filtre sur status si tu n’en veux pas.
Paramètres de requête
fromdatetime
Début de la fenêtre, inclus.
todatetime
Fin de la fenêtre, exclue.
locationIduuid
Ne garde que ce site.
employeeIduuid
Ne garde que cette personne.
positionIduuid
Ne garde que ce poste.
limitinteger
Nombre de créneaux par page.de 1 à 200défaut : 50
cursoruuid
Valeur de nextCursor reçue à la page précédente.
Réponse
200 Un objet avec data, un tableau d’objets Créneau, et nextCursor.
Requête invalide : champ manquant ou mal formé, identifiant qui n’est pas un UUID, fin avant le début.Messages possiblesValidation failedValidation failed (uuid is expected)end must be strictly after start
401Unauthorized
Clé absente, inconnue, révoquée ou expirée.Messages possiblesMissing Bearer tokenEmpty bearer tokenInvalid API tokenToken revokedToken expired
402Payment Required
Abonnement inactif : période d’essai terminée, paiement non finalisé ou abonnement échu. Les écritures sont refusées, les lectures restent possibles ; tout reprend dès la réactivation.Messages possiblesVotre période d’essai est terminée. Activez un abonnement pour continuer à modifier vos données.Votre paiement n’a pas été finalisé. Terminez la souscription pour reprendre les modifications.Votre abonnement est arrivé à échéance. Réactivez-le pour continuer à modifier vos données.
403Forbidden
La clé n’a pas la permission exigée. Le message nomme la permission manquante.Messages possiblesMissing scope: shifts:write
404Not Found
Ressource introuvable dans ton organisation. Une ressource d’une autre organisation donne exactement la même réponse.Messages possiblesShift not foundemployee not foundposition not foundlocation not found
429Too Many Requests
Trop de requêtes. Attends le nombre de secondes indiqué par Retry-After.Messages possiblesThrottlerException: Too Many Requests
Un 400 a trois formes
Corps de requête refusé : message vaut Validation failed et issues liste chaque champ en cause.
Paramètre de liste refusé : le corps est un objet dont chaque clé est le nom du paramètre en cause.
400
{
"limit": [
"Too big: expected number to be <=200"
]
}
Autres cas : le corps standard.
400
{
"message": "end must be strictly after start",
"error": "Bad Request",
"statusCode": 400
}
Un corps de plus de 5 Mo est refusé avec un 413. Un 5xx signale une panne de notre côté : réessaie une lecture après un délai croissant ; avant de rejouer une création, vérifie qu’elle n’a pas abouti.
Limites de débit
100 requêtes par fenêtre de 60 secondes. Le compteur est tenu séparément pour chaque point d’entrée, et rattaché à l’appelant : son adresse IP, ou sa clé.
Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, le nombre de secondes avant la remise à zéro. Au-delà de la limite, la réponse est un 429 avec Retry-After.
Un plafond global par adresse protège aussi l’ensemble du service. Il répond de la même façon.
429
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Webhooks
Un webhook t’envoie une requête POST signée chaque fois qu’un événement auquel tu es abonné se produit. Tu les configures dans Réglages → Webhooks.
L’adresse doit être en https://, publique, sans identifiants dans l’URL, et faire 500 caractères au plus. Une adresse qui mène à un réseau privé est refusée, à l’enregistrement comme à chaque envoi.
Le secret de signature commence par whs_ et s’affiche une seule fois, à la création. Nous le conservons chiffré (AES-256-GCM).
Comme pour les clés, il faut un compte autorisé à gérer les webhooks et dont l’accès couvre toute l’organisation.
sha256= suivi de l’empreinte HMAC-SHA-256 du corps brut, en hexadécimal, calculée avec ton secret.
X-SwissPlanif-Event
Nom de l’événement, identique au champ event.
X-SwissPlanif-Delivery-Id
Identifiant unique de cette livraison (UUID). Garde-le pour reconnaître une livraison déjà traitée.
eventstring
Nom de l’événement.
tenantIduuid
Identifiant de ton organisation.
occurredAtdatetime
Instant de l’envoi, en UTC.
dataobject
Contenu propre à l’événement, décrit plus bas.
Vérifier la signature
Lis le corps brut, octet pour octet, avant tout décodage JSON.
Calcule son HMAC-SHA-256 avec ton secret et compare-le à l’en-tête par une comparaison à temps constant.
Refuse la requête si la signature ne correspond pas, ou si occurredAt date de plus de quelques minutes : c’est ta protection contre le rejeu d’une requête interceptée.
Réponds 2xx tout de suite, puis traite l’événement en arrière-plan.
Node.js, sans dépendance
import { createHmac, timingSafeEqual } from 'node:crypto';
const MAX_AGE_MS = 5 * 60 * 1000;
// rawBody: the request body exactly as received (string or Buffer).
export function verifyWebhook(rawBody, signatureHeader, secret) {
const expected = Buffer.from(
`sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`,
);
const received = Buffer.from(String(signatureHeader ?? ''));
if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
return null;
}
const event = JSON.parse(rawBody.toString());
const age = Math.abs(Date.now() - Date.parse(event.occurredAt));
return age <= MAX_AGE_MS ? event : null;
}
// const event = verifyWebhook(
// rawBody,
// request.headers['x-swissplanif-signature'],
// process.env.SWISSPLANIF_WEBHOOK_SECRET,
// );
// if (!event) return response.writeHead(401).end();
Livraison
Une seule tentative par événement, sans reprise automatique. Une réponse hors 2xx, une redirection ou un délai de plus de 8 secondes comptent comme un échec.
Après 10 échecs consécutifs, l’endpoint est mis en pause. Tu le réactives depuis les Réglages, où l’historique de ses livraisons reste consultable.
Un événement peut donc être perdu : pour connaître l’état exact, relis l’API.
Événements
Le contenu de data pour chaque événement. Les identifiants renvoient aux objets de ton organisation ; les dates sont en UTC.
shift.publishedCréneau publié
Un événement par créneau du planning publié.
shiftIduuid
Créneau concerné.
scheduleIduuid
Planning auquel le créneau appartient.
publicationIduuid
Publication qui a figé ce créneau.
employeeIduuid · ou null
Personne concernée.
locationIduuid
Site.
startdatetime
Début.
enddatetime
Fin.
weekStartdatetime
Début de la semaine publiée.
publishedAtdatetime
Instant de la publication.
shift.cancelledCréneau annulé
Envoyé quand un créneau passe à l’état annulé. Une suppression n’envoie rien.
shiftIduuid
Créneau concerné.
scheduleIduuid · ou null
Planning auquel le créneau appartient.
employeeIduuid · ou null
Personne concernée.
locationIduuid
Site.
startdatetime
Début.
enddatetime
Fin.
absence.requestedDemande d'absence
absenceIduuid
Absence concernée.
employeeIduuid
Personne concernée.
startdatetime
Début.
enddatetime
Fin.
absence.approvedAbsence validée
Valider une absence n’annule plus de créneau : cancelledShifts vaut toujours 0.
absenceIduuid
Absence concernée.
cancelledShiftsinteger
Toujours 0.
keptShiftsinteger
Nombre de créneaux de la personne qui chevauchent l’absence et restent en place.
absence.rejectedAbsence refusée
Envoyé pour un refus, et aussi quand une absence déjà validée est retirée, en entier ou pour un seul jour : revoked vaut alors true.
absenceIduuid
Absence concernée.
reasonstring
Motif saisi par le responsable, s’il y en a un.selon le castexte libre
revokedboolean
true quand une absence déjà validée est retirée.selon le cas
deletedboolean
true quand l’absence retirée a été supprimée.selon le cas
partialboolean
true quand un seul jour a été retiré de l’absence.selon le cas
restoredShiftsinteger
Nombre de créneaux remis en place.selon le cas
removedStartdatetime
Début de la période retirée.selon le cas
removedEnddatetime
Fin de la période retirée.selon le cas
tailAbsenceIduuid · ou null
Absence créée pour les jours qui suivent le jour retiré, s’il y en a.selon le cas
swap.requestedÉchange demandé
swapIduuid
Demande d’échange.
shiftIduuid
Créneau concerné.
requestedByIduuid
Employé qui demande l’échange.
targetEmployeeIduuid · ou null
Employé visé, si la demande en vise un.
swap.approvedÉchange validé
swapIduuid
Demande d’échange.
swap.rejectedÉchange refusé
swapIduuid
Demande d’échange.
reasonstring
Motif saisi par le responsable, s’il y en a un.selon le castexte libre
open_shift.appliedCandidature créneau ouvert
claimIduuid
Candidature.
shiftIduuid
Créneau concerné.
employeeIduuid
Personne concernée.
open_shift.assignedCréneau ouvert attribué
claimIduuid
Candidature.
shiftIduuid
Créneau concerné.
employeeIduuid
Personne concernée.
shift_offer.sentProposition de mission envoyée
offerIduuid
Proposition.
shiftIduuid
Créneau concerné.
recipientsinteger
Nombre de personnes à qui la proposition a été envoyée.
shift_offer.claimedProposition de mission acceptée
offerIduuid
Proposition.
shiftIduuid
Créneau concerné.
employeeIduuid
Personne concernée.
mission.activatedMission activée
missionIduuid
Mission.
mission.completedMission terminée
missionIduuid
Mission.
mission.cancelledMission annulée
missionIduuid
Mission.
employee.skill.expiringCompétence expire
Envoyé une fois par jour pour chaque compétence qui expire dans les 30 jours.
employeeSkillIduuid
Compétence de l’employé qui arrive à échéance.
employeeIduuid
Personne concernée.
skillIduuid
Compétence.
expiresAtdatetime
Date d’expiration.
observedAtdatetime
Instant du contrôle.
noticeDaysinteger
Préavis, en jours.
Sécurité
Une clé d’API ouvre les données de toute ton organisation. Ces règles tiennent en une page : applique-les toutes.
De ton côté
01Une clé par intégration, le moins de permissions possible
Un tableau de bord n’a besoin que de lectures. Une clé par outil te permet d’en révoquer une sans couper les autres.
02La clé vit dans un gestionnaire de secrets
Jamais dans un dépôt, un ticket, un e-mail ou une capture d’écran, ni dans le code d’une page web ou d’une application mobile.
03Appelle l’API depuis un serveur
Une clé chargée dans un navigateur est lisible par quiconque ouvre la page. L’API n’autorise d’ailleurs aucun autre site web à l’appeler depuis un navigateur.
04Remplace tes clés régulièrement
Crée la nouvelle clé, bascule ton intégration, vérifie, puis révoque l’ancienne. Les Réglages affichent le dernier appel de chaque clé.
05Au moindre doute, révoque
La révocation prend effet à l’appel suivant. Une clé qui a fuité doit être considérée comme lue.
06Ne journalise pas la clé
Masque l’en-tête Authorization dans tes journaux, tes outils de débogage et tes rapports d’erreur.
07Vérifie chaque webhook
Signature sur le corps brut, comparaison à temps constant, rejet des requêtes anciennes. Avant cette vérification, ne te fie ni à l’adresse d’origine ni au contenu.
08Traite les données personnelles comme telles
Noms, adresses e-mail et notes relèvent de la nLPD et du RGPD. Ne copie que ce dont tu as besoin, et supprime-le quand tu n’en as plus l’usage.
09Valide ce que tu reçois
Une note ou un motif est un texte saisi par une personne. Traite toute valeur reçue comme une donnée, jamais comme du code ou une commande à exécuter.
De notre côté
Seule l’empreinte SHA-256 d’une clé est conservée ; la clé n’apparaît qu’une fois, à sa création.
Les permissions sont contrôlées à chaque appel, et chaque requête s’exécute dans le périmètre de l’organisation de la clé, isolé par la Row-Level Security de PostgreSQL.
Une ressource d’une autre organisation répond comme une ressource qui n’existe pas.
La création et la révocation d’une clé, ainsi que chaque écriture faite par l’API, sont inscrites au journal d’audit avec l’identifiant de la clé.
Le secret d’un webhook est chiffré au repos (AES-256-GCM).
Avant chaque envoi, l’adresse d’un webhook est résolue et contrôlée : HTTPS seulement, réseaux privés refusés, certificat vérifié, aucune redirection suivie.
En production, l’API ne sert ni console interactive ni description OpenAPI.
Chaque point d’entrée a une limite de débit, et chaque réponse porte les en-têtes de sécurité HSTS et CSP.
Tu as trouvé une faille ? Écris à contact@swissplanif.ch. L’état réel de notre sécurité, manques compris, est sur la page Sécurité.
Ce que l’API ne fait pas encore
Ce qui manque aujourd’hui, pour que tu le saches avant de construire dessus.
Les lectures ne sont pas journalisées
Le journal d’audit garde les écritures faites par l’API, pas les appels en lecture.
Pas de clé d’idempotence
Rejouer une création crée un second créneau. Après une coupure, relis avant de recréer.
Pas de contrôle métier à l’écriture
L’API ne vérifie ni les chevauchements ni les règles de temps de travail que l’application signale.
Webhooks sans reprise
Une livraison échouée n’est pas rejouée. Son échec reste visible dans l’historique des livraisons, dans les Réglages.
Pas de rotation du secret d’un webhook
Pour changer de secret, supprime l’endpoint et recrée-le.
Pas d’environnement de test
Il n’existe que des clés de production. Commence par une clé en lecture seule.
Listes non paginées
Employés, sites et postes sont renvoyés en une fois.