Aller au contenu principal

Versioning — API publique Pesia

L'API publique Pesia utilise un versioning par chemin, major uniquement.

Schéma de versioning​

ÉlémentValeur
Version actuellev1
Chemin de base/partner/v1/*
Prochaine version (future)/partner/v2/*
Cohabitationv1 et v2 actives en parallèle pendant au moins 6 mois
https://api.pesia.fr/partner/v1/smic    # Version actuelle
https://api.pesia.fr/partner/v2/smic    # Future — non disponible en v1.1

Politique additive-only dans une major​

Dans une version majeure (ex. v1), Pesia garantit que aucun breaking change ne sera introduit. Voir la page Stabilité du contrat pour les détails complets.

En résumé :

  • Les champs JSON requis existants ne sont jamais supprimés.
  • Les endpoints existants ne sont jamais retirés sans runway de 6 mois.
  • Les nouveaux champs, endpoints et événements webhook sont ajoutés de façon additive.

Note (novembre 2026) — exceptions historiques, avant mise en production. Six breaking changes assumés ont été introduits avant la mise en production de v1 : trois en août 2026, un en septembre 2026, un en octobre 2026, un en novembre 2026. Ce sont les seuls de l'histoire de v1 ; la politique ci-dessus s'applique pleinement depuis. Les partenaires ayant reçu un pack de démarrage avant cette date sont informés nominativement des six points.

  1. Double enveloppe supprimée. Les réponses de succès portaient une enveloppe { "data": { "data": … } } non documentée. La ressource est désormais directement sous data, dans l'enveloppe { "success", "data", "timestamp" } (les collections portent data.items + data.meta).
  2. mission.contract_external_id devient requis sur le dépôt de lot de paie (POST /partner/v1/payroll-batches). C'est la seule référence de contrat stable de la chaîne : elle nomme le contrat sur le bulletin détaillé (« Contrat CTR-1042 du … au … »). Sans elle, un bulletin multi-contrat n'est rapprochable d'aucun document. Un dépôt qui l'omet reçoit désormais un 400 nommant la colonne.
  3. La règle du NIR devient stricte et commune. Le premier caractère accepte uniquement 1, 2, 3, 4, 7 ou 8. La clé accepte uniquement 01 à 97. Une clé fournie qui ne correspond pas au NIR reçoit un 400 sur le champ public. Le serveur accepte un NIR sur 13 caractères ou un numéro de sécurité sociale sur 15 caractères.
  4. paymentDate devient requis sur le dépôt de lot de paie (POST /partner/v1/payroll-batches), format YYYY-MM-DD. period est le mois travaillé ; la date de versement est le jour du virement, et c'est elle qui détermine le barème du prélèvement à la source. Elle ne se déduit pas de la période : Pesia la demande plutôt que de la deviner. Un dépôt qui l'omet reçoit un 400 nommant le champ. Voir Lots de paie.
  5. hours est borné sur le calcul SMIC (GET /partner/v1/smic/calculate). hours doit être strictement positif et valoir au plus 744, le nombre d'heures du mois le plus long (31 jours × 24 h). Une valeur hors de cet intervalle reçoit un 400 validation_error. Avant, la route répondait 200 avec un brut nul, négatif, ou calculé sur plus d'heures qu'un mois n'en compte.
  6. Statut mutuelle et prévoyance des intérimaires. Sur le dépôt de lot de paie (POST /partner/v1/payroll-batches), worker.reached_414h et worker.health_insurance_enrolled remplacent worker.above_414h et worker.wants_mutuelle. Un dépôt qui porte une ancienne clé reçoit un 400. L'ancien format ne pouvait pas déclarer la dispense de mutuelle d'un intérimaire au-dessus de 414 h. Un champ absent ne vaut plus false : Pesia reprend le statut du salarié en vigueur le mois du lot. Voir Lots de paie.

Les autres changements d'octobre 2026 sur /partner/v1/smic* ne sont pas des exceptions. Ils alignent les réponses sur le contrat publié : montants du barème en vigueur, hours renvoyé en nombre, 400 sur une date mal formée ou un hours absent ou non numérique, 404 au lieu de 500 pour une date sans barème. Ou ils ajoutent un code : 503 SMIC_UPSTREAM_UNAVAILABLE.

Headers de dépréciation​

Lorsqu'un endpoint ou une version est déprécié, Pesia émet les headers suivants sur chaque réponse concernée :

HeaderFormatDescription
SunsetRFC 8594 (HTTP-date)Date à laquelle l'endpoint/version sera retiré
X-Pesia-DeprecationISO 8601Date à laquelle la dépréciation a été annoncée

Exemple de réponse sur un endpoint déprécié :

HTTP/1.1 200 OK
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
X-Pesia-Deprecation: 2027-07-01T00:00:00Z
Content-Type: application/json

{ "success": true, "data": { ... }, "timestamp": "2026-08-10T12:00:00.000Z" }

Important : Le Sunset header est garanti ≥ 6 mois après l'annonce de dépréciation.

Runway minimum de 6 mois​

Entre l'annonce de dépréciation d'une version (v1) et son retrait effectif, Pesia respecte un runway minimum de 6 mois :

  1. Annonce : l'événement webhook partner_api.version_deprecation est émis à toutes les subscriptions actives (voir Webhooks).
  2. Headers actifs : Sunset et X-Pesia-Deprecation apparaissent sur tous les endpoints de la version concernée.
  3. Documentation : la page de stabilité est mise à jour avec la date de fin de vie.
  4. Retrait : après ≥ 6 mois, les endpoints v1 renvoient 410 Gone.

Événement webhook de dépréciation​

L'événement partner_api.version_deprecation annonce la fin de vie de v1 :

{
  "eventType": "partner_api.version_deprecation",
  "version": "v1",
  "sunsetAt": "2028-01-01T00:00:00.000Z",
  "tenantId": "01a08af4-d5c0-735f-bcd5-2e17f00b873d",
  "organizationId": "01a08af4-d5f8-70bb-b8b9-df37692cbd9a",
  "env": "production",
  "eventId": "58d926b0-789e-4a88-bd82-5673b556a3a5",
  "occurredAt": "2027-07-01T00:00:00.000Z"
}

Cohabitation v1 / v2​

Lorsque v2 sera disponible, v1 et v2 cohabiteront pendant au moins 6 mois :

/partner/v1/*   → déprécié, Sunset header actif
/partner/v2/*   → nouvelle version stable

Les partenaires peuvent migrer progressivement, endpoint par endpoint, sans rupture.

Voir aussi​