Piloter l'onboarding

Les opérations de cette page agissent sur le parcours d'onboarding d'une unité légale déjà créée.

Le legalUnitId utilisé dans les routes est celui retourné par POST /v1/onboarding/legal-units.

Démarrer un onboarding

POST /v1/onboarding/legal-units/{legalUnitId}/start

Cette opération démarre le parcours d'onboarding d'une unité légale existante.

Exemple de requête :

{
  "registerDomesticFr": true,
  "registerPeppolInternational": false
}

Les deux paramètres indiquent sur quels réseaux les adresses de facturation électronique de l'unité légale doivent être inscrites. Ils pilotent les inscriptions réalisées pendant l'onboarding ; ils ne décrivent ni la forme de l'adresse ni le sens des échanges.

Choisir les réseaux d'inscription

registerDomesticFr

Lorsque registerDomesticFr vaut true, l'onboarding demande l'inscription de l'unité légale sur le réseau domestique français de facturation électronique.

Cette inscription permet à l'unité légale d'être enregistrée et adressable dans le dispositif français pour les échanges de factures électroniques domestiques.

Exemple — réseau domestique français uniquement :

{
  "registerDomesticFr": true,
  "registerPeppolInternational": false
}

registerPeppolInternational

Lorsque registerPeppolInternational vaut true, l'onboarding demande l'inscription de l'unité légale sur le réseau Peppol.

Cette inscription permet à l'unité légale d'être adressable sur Peppol pour les échanges avec les participants de ce réseau.

Exemple — Peppol uniquement :

{
  "registerDomesticFr": false,
  "registerPeppolInternational": true
}

Une unité légale peut également demander une inscription sur les deux réseaux :

{
  "registerDomesticFr": true,
  "registerPeppolInternational": true
}

registerDomesticFr	registerPeppolInternational	Inscription demandée
true	false	Réseau domestique français uniquement
false	true	Peppol uniquement
true	true	Réseau domestique français et Peppol
false	false	Aucune inscription réseau demandée

Ne pas confondre réseau et direction des échanges

registerDomesticFr et registerPeppolInternational répondent à la question : sur quels réseaux l'unité légale doit-elle être inscrite ?

operatorDirection, défini sur l'unité légale, répond à une autre question : dans quel sens utilise-t-elle la plateforme ?

• INBOUND : réception uniquement ;
• OUTBOUND : émission uniquement ;
• BIDIRECTIONAL : émission et réception.

Ces paramètres sont donc complémentaires et ne doivent pas être déduits les uns des autres.

Choix d'onboarding

Ces booléens ne sont pas de simples options d'affichage : ils déterminent les inscriptions réseau demandées lors du démarrage du parcours. L'intégrateur doit donc les renseigner en fonction du périmètre réellement attendu pour l'unité légale.

Adresses concernées et mobilité

L'inscription réseau porte sur les adresses de facturation électronique sélectionnées pendant le parcours.

Pour une entreprise française, ces adresses prennent notamment les formes suivantes :

0225:<SIREN>
0225:<SIREN>_<SIRET>
0225:<SIREN>_<libellé_de_service>

Une même adresse est ensuite enregistrée sur le ou les réseaux demandés par registerDomesticFr et registerPeppolInternational.

Adresse déjà utilisée auprès d'une autre PA

Si une adresse est déjà enregistrée auprès d'une autre Plateforme Agréée, l'intégrateur doit connaître l'intention du client avant de poursuivre :

• le client souhaite conserver cette adresse auprès de l'autre PA : sélectionner ou créer une adresse différente pour le nouveau périmètre ;
• le client souhaite transférer cette même adresse : le parcours déclenche une procédure de mobilité entre la PA d'arrivée et la PA de départ.

Le réenregistrement d'une même adresse n'est donc pas un simple écrasement technique.

Lorsque la mobilité est nécessaire, le parcours peut rester en attente pendant les échanges et validations entre plateformes. L'événement ELECTRONIC_ADDRESS_MIGRATION peut apparaître dans l'historique.

➡️ Comprendre la mobilité d'une adresse
➡️ État et historique

L'appel /start est distinct :

• de la création de l'unité légale ;
• de la configuration de operatorDirection, portée par l'unité légale ;
• du redémarrage d'un onboarding expiré, qui utilise /restart.

Après le démarrage, conservez le legalUnitId et l'éventuel onboardingRequestId, puis suivez le parcours avec /state.

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

➡️ État et historique

Redémarrer un onboarding expiré

POST /v1/onboarding/legal-units/{legalUnitId}/restart

Cette opération redémarre un onboarding arrivé à expiration.

Elle ne doit pas être utilisée comme équivalent de /start pour une unité légale qui n'a encore jamais démarré son onboarding.

Après le redémarrage, reprenez le suivi avec :

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

Annuler un onboarding automatique en cours

POST /v1/onboarding/legal-units/{legalUnitId}/cancel

Cette opération annule un onboarding automatique en cours.

Après l'annulation, /state devient la source de vérité pour confirmer l'état courant. L'historique peut ensuite être utilisé pour retrouver l'événement d'annulation.

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

Pas de route de clôture

L'API publiée ne prévoit plus de route POST /v1/onboarding/legal-units/{legalUnitId}/close. La fin normale du parcours est reflétée par l'état d'onboarding ; une annulation explicite utilise /cancel dans les cas où cette opération est autorisée.

Quel appel utiliser ?

Besoin	Opération
Premier démarrage d'une unité légale existante	POST .../start
Lire l'état courant	GET .../state
Comprendre la chronologie du parcours	GET .../history
Redémarrer un parcours expiré	POST .../restart
Annuler un onboarding automatique en cours	POST .../cancel

Principe d'intégration