API REST · v1

Pilote SwissPlanif depuis tes automatisations.

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.

curl
curl "https://api.swissplanif.ch/api/v1/locations" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"

Authentification

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.

shifts:read
Lister les créneaux et en lire un.GET/shiftsGET/shifts/{id}
shifts:write
Créer, modifier et supprimer des créneaux. Ne donne pas la lecture.POST/shiftsPATCH/shifts/{id}DELETE/shifts/{id}
employees:read
Lire l’annuaire des employés : noms, adresses e-mail, contrat.GET/employees
locations:read
Lire les sites.GET/locations
positions:read
Lire les postes.GET/positions

Conventions

  • 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
curl "https://api.swissplanif.ch/api/v1/shifts?from=2026-11-16T00:00:00Z&to=2026-11-23T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Réponse · 200
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "start": "2026-11-16T07:00:00.000Z",
      "end": "2026-11-16T15:00:00.000Z",
      "breakMinutes": 30,
      "status": "DRAFT",
      "positionId": "00000000-0000-4000-8000-0000000000a1",
      "positionName": "Front desk",
      "locationId": "00000000-0000-4000-8000-0000000000b1",
      "locationName": "Lausanne Centre",
      "employeeId": "00000000-0000-4000-8000-0000000000c1",
      "employeeFullName": "Alex Example",
      "note": null,
      "createdAt": "2026-11-11T09:30:00.000Z",
      "updatedAt": "2026-11-11T09:30:00.000Z"
    }
  ],
  "nextCursor": "00000000-0000-4000-8000-000000000001"
}
GET/shifts/{id}Permissionshifts:read

Lire un créneau

Renvoie un créneau par son identifiant.

  • Un identifiant inconnu et un identifiant d’une autre organisation donnent la même réponse : 404.

Paramètres de requête

iduuid
Identifiant du créneau, dans le chemin.obligatoire

Réponse

200 Un objet Créneau.

Requête
curl "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Réponse · 200
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": "00000000-0000-4000-8000-0000000000c1",
  "employeeFullName": "Alex Example",
  "note": null,
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T09:30:00.000Z"
}
POST/shiftsPermissionshifts:write

Créer un créneau

Crée un créneau avec l’état DRAFT.

  • end doit être strictement après start.
  • positionId, locationId et employeeId doivent exister dans ton organisation, sinon 404.
  • L’API ne publie pas le créneau et n’envoie aucune notification.

Corps de la requête

startdatetime
Début du créneau.obligatoire
enddatetime
Fin, strictement après le début.obligatoire
breakMinutesinteger
Pause, en minutes.de 0 à 600défaut : 0
positionIduuid
Poste, dans ton organisation.obligatoire
locationIduuid
Site, dans ton organisation.obligatoire
employeeIduuid · ou null
Personne affectée, ou null pour un créneau sans personne.défaut : null
notestring · ou null
Note libre.2000 caractères au plusdéfaut : null

Réponse

201 Un objet Créneau.

Requête
curl -X POST "https://api.swissplanif.ch/api/v1/shifts" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "employeeId": "00000000-0000-4000-8000-0000000000c1"
}'
Réponse · 201
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": "00000000-0000-4000-8000-0000000000c1",
  "employeeFullName": "Alex Example",
  "note": null,
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T09:30:00.000Z"
}
PATCH/shifts/{id}Permissionshifts:write

Modifier un créneau

Modifie les champs envoyés ; les autres ne changent pas.

  • Si tu n’envoies que start ou que end, l’intervalle obtenu est contrôlé avec la valeur déjà enregistrée.
  • employeeId: null retire la personne ; note: null efface la note.

Paramètres de requête

iduuid
Identifiant du créneau, dans le chemin.obligatoire

Corps de la requête

Tous les champs sont facultatifs : n’envoie que ceux que tu modifies.

startdatetime
Début du créneau.
enddatetime
Fin, strictement après le début.
breakMinutesinteger
Pause, en minutes.de 0 à 600
positionIduuid
Poste, dans ton organisation.
locationIduuid
Site, dans ton organisation.
employeeIduuid · ou null
Personne affectée, ou null pour un créneau sans personne.
notestring · ou null
Note libre.2000 caractères au plus

Réponse

200 Un objet Créneau.

Requête
curl -X PATCH "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "employeeId": null,
  "note": "Cover needed"
}'
Réponse · 200
{
  "id": "00000000-0000-4000-8000-000000000001",
  "start": "2026-11-16T07:00:00.000Z",
  "end": "2026-11-16T15:00:00.000Z",
  "breakMinutes": 30,
  "status": "DRAFT",
  "positionId": "00000000-0000-4000-8000-0000000000a1",
  "positionName": "Front desk",
  "locationId": "00000000-0000-4000-8000-0000000000b1",
  "locationName": "Lausanne Centre",
  "employeeId": null,
  "employeeFullName": null,
  "note": "Cover needed",
  "createdAt": "2026-11-11T09:30:00.000Z",
  "updatedAt": "2026-11-11T10:05:00.000Z"
}
DELETE/shifts/{id}Permissionshifts:write

Supprimer un créneau

Supprime le créneau, définitivement.

  • Une suppression n’envoie pas l’événement shift.cancelled.

Paramètres de requête

iduuid
Identifiant du créneau, dans le chemin.obligatoire

Réponse

204 Aucun corps.

Requête
curl -X DELETE "https://api.swissplanif.ch/api/v1/shifts/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
GET/employeesPermissionemployees:read

Lister les employés

Renvoie les employés actifs de l’organisation, triés par nom.

  • La réponse contient des données personnelles : noms et adresses e-mail.

Réponse

200 Un tableau d’objets Employé, en une seule réponse.

Requête
curl "https://api.swissplanif.ch/api/v1/employees" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Réponse · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000c1",
    "firstName": "Alex",
    "lastName": "Example",
    "email": "alex@example.com",
    "contractType": "PERMANENT",
    "weeklyHours": 42,
    "locationIds": [
      "00000000-0000-4000-8000-0000000000b1"
    ],
    "positionIds": [
      "00000000-0000-4000-8000-0000000000a1"
    ]
  }
]
GET/locationsPermissionlocations:read

Lister les sites

Renvoie les sites de l’organisation, triés par nom.

  • Cet appel n’accepte aucun paramètre.

Réponse

200 Un tableau d’objets Site, en une seule réponse.

Requête
curl "https://api.swissplanif.ch/api/v1/locations" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Réponse · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000b1",
    "name": "Lausanne Centre",
    "address": "Example street 1, 1000 Lausanne",
    "timezone": "Europe/Zurich"
  }
]
GET/positionsPermissionpositions:read

Lister les postes

Renvoie les postes de l’organisation, triés par nom.

  • Cet appel n’accepte aucun paramètre.

Réponse

200 Un tableau d’objets Poste, en une seule réponse.

Requête
curl "https://api.swissplanif.ch/api/v1/positions" \
  -H "Authorization: Bearer $SWISSPLANIF_TOKEN"
Réponse · 200
[
  {
    "id": "00000000-0000-4000-8000-0000000000a1",
    "name": "Front desk",
    "color": "#6366f1",
    "requiredSkills": []
  }
]

Erreurs

Lis d’abord le code HTTP : c’est lui qui fait foi. La plupart des erreurs ont le corps standard ci-dessous, avec un message en anglais.

403
{
  "message": "Missing scope: shifts:write",
  "error": "Forbidden",
  "statusCode": 403
}
400Bad Request
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

  1. Corps de requête refusé : message vaut Validation failed et issues liste chaque champ en cause.

    400
    {
      "message": "Validation failed",
      "issues": [
        {
          "expected": "string",
          "code": "invalid_type",
          "path": [
            "positionId"
          ],
          "message": "Invalid input: expected string, received undefined"
        }
      ]
    }
  2. 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"
      ]
    }
  3. 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.

Ce que tu reçois

POST
POST /webhooks/swissplanif HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
X-SwissPlanif-Event: shift.published
X-SwissPlanif-Signature: sha256=<hex digest>
X-SwissPlanif-Delivery-Id: 00000000-0000-7000-8000-000000000101

{
  "event": "shift.published",
  "tenantId": "00000000-0000-4000-8000-0000000000d1",
  "occurredAt": "2026-11-13T16:02:11.000Z",
  "data": {
    "shiftId": "00000000-0000-4000-8000-000000000001",
    "scheduleId": "00000000-0000-4000-8000-0000000000e1",
    "publicationId": "00000000-0000-4000-8000-0000000000f1",
    "employeeId": "00000000-0000-4000-8000-0000000000c1",
    "locationId": "00000000-0000-4000-8000-0000000000b1",
    "start": "2026-11-16T07:00:00.000Z",
    "end": "2026-11-16T15:00:00.000Z",
    "weekStart": "2026-11-15T23:00:00.000Z",
    "publishedAt": "2026-11-13T16:02:10.000Z"
  }
}
X-SwissPlanif-Signature
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

  1. Lis le corps brut, octet pour octet, avant tout décodage JSON.
  2. Calcule son HMAC-SHA-256 avec ton secret et compare-le à l’en-tête par une comparaison à temps constant.
  3. 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.
  4. 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é

  1. Une 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.

  2. La 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.

  3. Appelle 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.

  4. Remplace 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é.

  5. Au moindre doute, révoque

    La révocation prend effet à l’appel suivant. Une clé qui a fuité doit être considérée comme lue.

  6. Ne journalise pas la clé

    Masque l’en-tête Authorization dans tes journaux, tes outils de débogage et tes rapports d’erreur.

  7. Vé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.

  8. Traite 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.

  9. Valide 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.
Pas de description OpenAPI publiée
Cette page est la référence.
API publique — SwissPlanif · SwissPlanif