Aller au contenu principal

Sandbox — Environnement de test partenaire

L'environnement sandbox Pesia permet aux partenaires de tester leur intégration sans impacter les données de production.

Accès sandbox​

Chaque partenaire disposant d'un accès sandbox reçoit des identifiants OAuth2 dédiés (clientId / clientSecret) attachés à un accès sandbox.

L'URL de base est la même qu'en production :

https://api.pesia.fr/partner/v1/

Le sandbox n'est pas un domaine séparé. C'est une propriété de vos identifiants. Vous sélectionnez l'environnement avec le header X-Pesia-Env (voir plus bas). Des identifiants sandbox ne peuvent pas atteindre les données de production, quel que soit le header envoyé.

Swagger UI interactif​

Le Swagger interactif de l'API v1 est exposé sur /partner/v1/docs uniquement lorsqu'un service sandbox est disponible à cette adresse. Contactez Pesia pour son URL d'accès. Le header X-Pesia-Env: sandbox n'active pas le Swagger sur un service de production. La spécification OpenAPI téléchargeable reste disponible sur ce site.

Limite de requêtes​

La limite dépend de votre accès. Ne déduisez pas une limite de 1 000 requêtes par minute du seul header X-Pesia-Env: sandbox. Consultez les headers de réponse et respectez Retry-After en cas de 429 :

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 595
X-RateLimit-Reset: 1789030800

Contactez Pesia pour connaître ou ajuster la limite de votre accès.

Comportements spécifiques au sandbox​

Dépôts DPAE​

Un accès sandbox transmet les DPAE à l'URSSAF en mode de validation, sans enregistrer une embauche réelle. Les soumissions, leur historique, les annulations et la déduplication par contrat sont isolés de la production. Un identifiant de soumission de l'autre environnement renvoie 404. La même référence contrat peut exister dans les deux environnements.

Pesia ne crée ni ne modifie de salarié ou de profil agence en sandbox. Une nouvelle soumission acceptée porte employeeRegistration: { "status": "skipped", "reason": "sandbox" }. Ce résultat peut être absent pour une ancienne soumission, y compris lors du renvoi d'un doublon. Consultez le résultat DPAE.

Testez notamment :

  1. Un corps valide et les champs absents que Pesia peut déduire du NIR.
  2. Une contradiction NIR/date de naissance : erreur explicite sur l'élément, sans dépôt pour celui-ci.
  3. Un corps mal formé : HTTP 400 pour la requête entière.
  4. Le renvoi du même corps avec la même clé d'idempotence, puis la déduplication métier du contrat.
  5. Les retours URSSAF et les webhooks, avec un endpoint HTTPS public sans redirection.
  6. La séparation des historiques et des abonnements sandbox/production.

SENT confirme une transmission, pas un verdict de conformité. DECLARED indique un certificat de conformité positif. Les retours sont appliqués aux soumissions identifiables ; un retour ambigu ne fait pas rejeter toutes les embauches de l'agence.

Le mode de validation ne garantit ni tous les contrôles de production, ni un BIS, ni un délai de réponse. Ne faites pas dépendre vos tests d'un ACK à J+1. Testez aussi votre récepteur avec les exemples webhooks, y compris les doublons et les événements reçus dans un ordre différent. Un résultat sandbox ne dispense pas de suivre le dépôt réel.

Le bloc employeur provient de l'agence. Pour une anomalie liée à ce bloc ou un retour bloqué, contactez partenaires@pesia.fr avec les références de soumission. Voir DPAE pour le détail du contrat.

Header X-Pesia-Env​

En sandbox, chaque requête API doit inclure :

X-Pesia-Env: sandbox

Un grant sandbox retourne 403 si X-Pesia-Env est absent (défaut production ≠ sandbox).

Onboarding sandbox​

  1. Demander un accès sandbox à l'équipe Pesia (email : partenaires@pesia.fr).
  2. Recevoir vos identifiants : clientId, clientSecret (one-shot), projectId.
  3. Obtenir un token sandbox :
curl -X POST https://auth.pesia.fr/oauth/v2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<clientId>' \
  --data-urlencode 'client_secret=<clientSecret>' \
  --data-urlencode 'scope=urn:zitadel:iam:org:project:id:<projectId>:aud urn:zitadel:iam:user:resourceowner salary:read'

Le scope urn:zitadel:iam:user:resourceowner est obligatoire. Sans lui, le token est délivré mais l'API le refuse avec un 401. Voir Authentification.

  1. Tester un endpoint :
curl https://api.pesia.fr/partner/v1/smic \
  -H "Authorization: Bearer <token>" \
  -H "X-Pesia-Env: sandbox"
  1. Consulter la spécification : OpenAPI v1, ou le Swagger sandbox communiqué par Pesia.

Voir aussi​