État et historique de l'onboarding

État courant

GET /v1/onboarding/legal-units/{legalUnitId}/state

La route /state est la référence pour connaître l'état courant et réaliser le polling. Elle fournit une photographie du parcours au moment de l'appel.

Historique

GET /v1/onboarding/legal-units/{legalUnitId}/history

La route /history restitue les événements successifs du parcours. Elle permet de comprendre et de présenter sa progression chronologique, y compris lorsqu'une intervention manuelle, une migration d'adresse électronique ou une réouverture intervient.

Statuts pouvant apparaître dans l'historique

La liste ci-dessous est la liste exhaustive des statuts d'onboarding actuellement exposés sur la SANDBOX. Les valeurs doivent être traitées telles quelles par l'intégration.

Statut	Signification
STARTED	Le client a démarré le parcours d'onboarding.
ACTION_REQUIRED	Une revue ou une action manuelle est nécessaire avant de poursuivre.
IDENTITY_CHECK_STARTED	La vérification d'identité a démarré.
IDENTITY_CHECK_SUBMITTED	La vérification d'identité a été soumise. Statut déprécié, remplacé par IDENTITY_CHECK_ACTION_REQUIRED, mais susceptible d'être encore reçu.
IDENTITY_CHECK_ACTION_REQUIRED	La vérification d'identité nécessite une revue et une validation manuelles.
IDENTITY_CHECK_ACCEPTED	L'identité a été vérifiée et acceptée.
BUSINESS_VERIFICATION_STARTED	La vérification de l'entreprise (KYB) a démarré.
BUSINESS_VERIFICATION_ACTION_REQUIRED	Les justificatifs KYB ont été soumis et nécessitent une revue et une validation manuelles.
BUSINESS_VERIFICATION_ACCEPTED	La vérification de l'entreprise (KYB) a été acceptée.
MANDATE_SIGNED	Le mandat a été signé.
ELECTRONIC_ADDRESS_MIGRATION	Au moins une adresse de facturation électronique demandée est déjà rattachée à une autre PA sur le réseau concerné. Le parcours attend la procédure de mobilité avant de pouvoir finaliser l'inscription.
ACCEPTED	Statut déprécié, remplacé par REGISTERING, mais susceptible d'être encore reçu.
REGISTERING	Les adresses électroniques sont en cours d'inscription sur les réseaux demandés.
REGISTERED	Toutes les adresses électroniques ont été inscrites sur les réseaux demandés.
COMPLETED	Le parcours d'onboarding est entièrement terminé.
CANCELLED	Le parcours a été annulé avant son terme.
REOPEN	Le parcours a été rouvert à la suite d'une revue manuelle.

Cas particulier : mobilité d'une adresse

ELECTRONIC_ADDRESS_MIGRATION ne signifie pas qu'une erreur technique s'est produite.

Il indique qu'une adresse demandée est déjà enregistrée auprès d'une autre Plateforme Agréée et que son transfert doit être traité.

Deux situations doivent être distinguées :

• si le client veut conserver l'adresse auprès de la PA actuelle, il faut utiliser une autre adresse pour le nouveau périmètre ;
• si le client veut transférer cette adresse, la mobilité suit son processus de validation entre PA avant que l'adresse puisse être considérée comme enregistrée auprès de la nouvelle PA.

Pendant cette phase, /state reste la source de vérité sur l'état courant et /history permet d'expliquer les étapes traversées.

➡️ Comprendre la mobilité d'une adresse

Interprétation de l'historique

• COMPLETED est l'événement de fin de parcours ; REGISTERED indique l'achèvement des inscriptions réseau mais ne doit pas être utilisé à sa place.
• ACTION_REQUIRED, IDENTITY_CHECK_ACTION_REQUIRED et BUSINESS_VERIFICATION_ACTION_REQUIRED signalent qu'une intervention est attendue.
• CANCELLED est un état terminal pour la demande concernée. Une nouvelle reprise doit passer par l'opération prévue par l'API.
• L'intégration ne doit pas supposer que tous les statuts apparaîtront systématiquement ni qu'ils seront uniques. Le parcours dépend des contrôles nécessaires et des réseaux demandés.
• Les statuts dépréciés doivent rester acceptés en lecture pour préserver la compatibilité avec les historiques existants.

Polling

Après une commande asynchrone ou tant que onboardingUrl n'est pas disponible, l'intégrateur doit interroger /state. Aucun webhook public d'onboarding n'est actuellement exposé.

Le polling doit :

1. conserver le legalUnitId et l'éventuel onboardingRequestId ;
2. utiliser une temporisation raisonnable et croissante ;
3. considérer la réponse de /state comme la source de vérité ;
4. ralentir ou suspendre le suivi automatique lorsqu'une action humaine est attendue ;
5. s'arrêter lorsque la demande atteint un état terminal ;
6. respecter les limites de requêtes et traiter les réponses 429 avec un backoff.

La route /history complète ce suivi pour afficher ou diagnostiquer la chronologie. Elle ne remplace pas /state comme source de l'état courant.

➡️ Mode d'interrogation et synchronisation des APIs