Ce guide d'intégration décrit le flux API utilisé par une organisation partenaire pour activer French eInvoice pour un client final.
Le flux reprend le guide du Portail Organisation.
Remplacez :
{organizationId}par l'identifiant de l'organisation partenaire ;{customerId}par l'identifiant du client final ;{legalRepresentativeId}par l'identifiant du représentant légal ;{delegateId}par l'identifiant du délégué, lorsque l'onboarding est réalisé par un délégué à la place du représentant légal ;{contractId}par l'identifiant du contrat retourné lors de sa création ;{sagId}par l'identifiant du Service Activation Group.
Toutes les requêtes nécessitent un jeton bearer dans l'en-tête Authorization.
Authorization: Bearer <token>Consultez Authentication pour le flux OAuth2 client credentials utilisé par les intégrations One Platform.
| # | Étape | Méthode | Endpoint |
|---|---|---|---|
| 1 | Créer ou réutiliser le client final | POST | /v2/organizations/{organizationId}/consumers |
| 2 | Créer ou réutiliser le représentant légal | POST | /v2/organizations/{organizationId}/consumers |
| 3 | Créer le contrat indirect et le contexte d'activation | POST | /v1/organizations/{organizationId}/contracts |
| 4 | Ajouter l'élément French eInvoice avec les paramètres d'onboarding | POST | /v1/organizations/{organizationId}/contracts/{contractId}/contract-items |
| 5 | Résoudre ou créer le Service Activation Group | GET / POST | /v1/organizations/{organizationId}/contracts/{contractId}/service-activation-group ou /v1/organizations/{organizationId}/service-activation-groups |
| 6 | Confirmer le Service Activation Group | PUT | /v1/organizations/{organizationId}/service-activation-groups/{sagId}/confirm?sendNotification=true |
Pour des intégrations prêtes pour la production, recherchez d'abord les consommateurs et contrats existants et réutilisez-les lorsqu'ils sont présents. Les payloads ci-dessous montrent le parcours de création pour une nouvelle activation.
Recherches recommandées :
GET /v2/organizations/{organizationId}/consumers?taxCode1=<TVA>&country=FR&customerType=Corporate&exact=true&pageSize=1
GET /v2/organizations/{organizationId}/consumers?taxCode2=<temporary-siren>&country=FR&customerType=PrivateIndividual&exact=true&pageSize=1L'onboarding French eInvoice utilise deux règles conditionnelles qui doivent être reflétées dans les payloads API :
| Configuration | Champ API | Effet dans l'onboarding |
|---|---|---|
| Onboarding du représentant légal | Omettez hasDelegate ou définissez-le à false dans onboardingExtraParameters. | Le destinataire vérifie et complète l'onboarding comme représentant légal. |
| Onboarding d'un délégué | Définissez hasDelegate: "true" dans onboardingExtraParameters. | Le destinataire vérifie et complète l'onboarding comme délégué à la place du représentant légal. |
| Portail DT activé | Incluez dt-portal dans featureIds et renseignez adminEmail, adminFirstName et adminLastName dans onboardingExtraParameters. | Le parcours d'onboarding peut demander ou afficher les données de l'administrateur du Portail DT. |
| Portail DT non activé | N'incluez pas dt-portal dans featureIds. | Les données d'administrateur du Portail DT ne sont pas requises. |
onboardingExtraParameters fait partie du payload de création de l'élément de contrat. Les valeurs sont des paires clé/valeur de type chaîne ; les valeurs booléennes sont donc envoyées sous forme de chaînes.
Créez le client final comme consommateur Corporate dans le périmètre de l'organisation partenaire.
POST /v2/organizations/{organizationId}/consumers
Content-Type: application/json{
"name": "VIDAL SOLUTIONS INFORMATIQUES SAS",
"country": "FR",
"type": "Customer",
"customerType": "Corporate",
"taxCode1": "FR43573849262",
"taxCode2": "573849262",
"taxCode3": "57384926200007",
"emails": ["contact@vidal-solutions.fr"],
"phones": [],
"mobilePhones": [],
"metadata": {
"siret_01": "57384926200007"
},
"billable": true,
"address": "12 RUE DES ARCHIVES",
"state": "ILE-DE-FRANCE",
"city": "PARIS",
"postalCode": "75004"
}Champs clés :
| Champ | Description |
|---|---|
customerType | Utilisez Corporate pour la société cliente finale. |
taxCode1 | Numéro de TVA français. |
taxCode2 | SIREN. |
taxCode3 | SIRET. |
metadata.siret_01 | Métadonnée SIRET supplémentaire utilisée par le flux d'activation. Vous pouvez fournir un nombre arbitraire d'entrées SIRET avec le modèle siret_nn, par exemple siret_01, siret_02, siret_03. |
billable | Définissez sur true pour activer la saisie de l'adresse du client. |
Les identifiants doivent être cohérents lorsque plusieurs valeurs sont fournies :
taxCode3(SIRET) commence par les 9 chiffres detaxCode2(SIREN) ;- les 9 derniers chiffres de
taxCode1(TVA) correspondent àtaxCode2(SIREN).
Conservez l'identifiant retourné comme customerId.
Créez le représentant légal comme consommateur PrivateIndividual.
POST /v2/organizations/{organizationId}/consumers
Content-Type: application/json{
"name": "Laurent Vidal",
"country": "FR",
"type": "Customer",
"customerType": "PrivateIndividual",
"firstName": "Laurent",
"lastName": "Vidal",
"taxCode2": "T0301KW15PGCJYHGWWYMJZGMK1MNH",
"emails": ["laurent.vidal@vidal-solutions.fr"],
"phones": [],
"mobilePhones": [],
"metadata": {},
"billable": false
}Pour un PrivateIndividual français, ne renseignez pas taxCode1 ni taxCode3.
Conservez l'identifiant retourné comme legalRepresentativeId.
Pour le représentant légal French eInvoice, générez taxCode2 (SIREN temporaire) sous la forme T03 suivi d'un ULID, par exemple T0301KW15PGCJYHGWWYMJZGMK1MNH.
Créez le contrat du client final à l'état Draft. Le contrat porte le contexte commercial et le destinataire. Le Service Activation Group peut être associé pendant le flux de création du contrat lorsque la version API/UI expose cette capacité ; sinon, créez-le ou récupérez-le explicitement avant la confirmation comme indiqué à l'étape 5.
POST /v1/organizations/{organizationId}/contracts
Content-Type: application/json{
"recipient": {
"email": "laurent.vidal@vidal-solutions.fr"
},
"startDate": "2026-06-23",
"legalRepresentativeId": "{legalRepresentativeId}",
"billingConsumerId": "{customerId}",
"issuerId": "51aaed15-afbc-4e9c-8f50-15c4040fa6ac",
"legalEntityId": "ea5d7839-acb6-4ae8-91b1-79a6e928ef37",
"description": "French eInvoice activation - VIDAL SOLUTIONS INFORMATIQUES SAS",
"number": "VIDAL-FR-EINV-01",
"metadata": {
"serviceActivationGroupDescription": "Activation French eInvoice - VIDAL SOLUTIONS INFORMATIQUES SAS"
},
"type": "Indirect",
"resellContractId": "2d29844f-1365-46ea-8ebb-18c6d79f05d5",
"createOrganization": false
}| Champ | Description |
|---|---|
recipient.email | E-mail utilisé par le flux d'activation. |
legalRepresentativeId | Identifiant issu de l'étape 2. |
billingConsumerId | Identifiant du client final issu de l'étape 1. |
issuerId | Identifiant du consommateur émetteur pour l'organisation partenaire. |
legalEntityId | Entité légale Namirial propriétaire de l'offre. |
metadata.serviceActivationGroupDescription | Métadonnée d'intégration optionnelle qui garde la description du SAG alignée avec l'étape de création du contrat. Utilisez le champ SAG natif lorsque votre version API en expose un. |
type | Utilisez Indirect pour les contrats client final émis par un partenaire. |
resellContractId | Contrat de distribution utilisé comme source de revente. |
createOrganization | true crée une organisation côté client ; false conserve une activation back-office uniquement. |
Conservez l'identifiant retourné comme contractId.
Ajoutez l'élément de service au contrat.
POST /v1/organizations/{organizationId}/contracts/{contractId}/contract-items
Content-Type: application/json{
"skuId": "1089000001",
"startDate": "2026-06-27",
"endDate": "2027-06-27",
"description": "French eInvoice",
"signed": false,
"provisioned": false,
"featureIds": [
"out-b2b",
"in-b2b",
"e-reporting",
"dt-portal"
],
"billingModelParameters": {},
"skuParameters": {},
"onboardingExtraParameters": {
"hasDelegate": "true",
"adminEmail": "camille.martin@vidal-solutions.fr",
"adminFirstName": "Camille",
"adminLastName": "Martin"
},
"envelopeParameters": [],
"resellContractItemId": "cd7c2a76-f1a2-418f-a5c9-66363eabf444"
}| Champ | Description |
|---|---|
skuId | SKU French eInvoice. Le flux d'activation actuel utilise 1089000001. |
featureIds | Ensemble de fonctionnalités à activer sur l'élément. Les fonctionnalités French eInvoice par défaut sont out-b2b, in-b2b et e-reporting. |
onboardingExtraParameters.hasDelegate | Définissez à "true" lorsque le sujet de l'onboarding est un délégué et non le représentant légal. Omettez ce champ ou utilisez "false" pour un onboarding du représentant légal. |
onboardingExtraParameters.adminEmail | E-mail de l'administrateur du Portail DT. Requis uniquement lorsque featureIds inclut dt-portal. |
onboardingExtraParameters.adminFirstName | Prénom de l'administrateur du Portail DT. Requis uniquement lorsque featureIds inclut dt-portal. |
onboardingExtraParameters.adminLastName | Nom de l'administrateur du Portail DT. Requis uniquement lorsque featureIds inclut dt-portal. |
signed | Définissez sur true uniquement lorsque l'élément est déjà signé hors One Platform. |
provisioned | Définissez sur true uniquement lorsque l'élément est déjà provisionné hors One Platform. |
resellContractItemId | Identifiant de l'élément de contrat issu du contrat de revente/distribution. |
skuParameters | Paramètres spécifiques au service lorsque les fonctionnalités sélectionnées les exigent. |
envelopeParameters | Paramètres optionnels propres à l'enveloppe. |
| Feature ID | Libellé anglais | Libellé italien | Libellé français | Par défaut | Dépendance |
|---|---|---|---|---|---|
out-b2b | Out-B2B Domestic | Fatturazione attiva B2B | Facturation electronique sortante B2B domestique | Oui | Aucune |
in-b2b | In B2B | Fatturazione passiva B2B | Facturation electronique entrante B2B | Oui | Aucune |
e-reporting | eReporting | Reportistica elettronica | Declaration electronique | Oui | Aucune |
dt-portal | Portal DT | Portale DT | Portail DT | Non | Nécessite l'une des fonctionnalités out-b2b, in-b2b ou e-reporting. |
editor | Editor | Editor | Editeur | Non | Nécessite dt-portal. |
identification | KYC/KYB | KYC/KYB | KYC/KYB | Non | Nécessite dt-portal. |
multiple-mandate | Multiple mandate | Mandato multiplo | Mandat multiple | Non | Nécessite in-b2b. |
Si le flux de création du contrat a déjà créé ou associé un SAG, récupérez son identifiant depuis le contrat :
GET /v1/organizations/{organizationId}/contracts/{contractId}/service-activation-groupSi aucun SAG n'existe encore, créez-en un contenant le contrat à activer.
POST /v1/organizations/{organizationId}/service-activation-groups
Content-Type: application/json{
"description": {
"en": "French eInvoice activation - VIDAL SOLUTIONS INFORMATIQUES SAS",
"fr": "Activation French eInvoice - VIDAL SOLUTIONS INFORMATIQUES SAS"
},
"contractIds": [
"{contractId}"
]
}Conservez l'identifiant retourné comme sagId. Cela remplace l'ancienne action de mise à jour du SAG côté portail : les données d'activation doivent être fournies lors de la création du contrat et de l'élément de contrat, puis le SAG est confirmé.
Confirmez le SAG pour faire sortir le contrat de l'état Draft.
PUT /v1/organizations/{organizationId}/service-activation-groups/{sagId}/confirm?sendNotification=true
Content-Type: application/jsonDéfinissez sendNotification=true pour envoyer l'e-mail d'activation au destinataire. Si ce paramètre est omis ou défini sur false, le SAG est confirmé mais l'e-mail n'est pas envoyé.
Le message de confirmation du portail explique que le destinataire pourra consulter le contrat et renseigner les champs manquants après confirmation.
customer = POST /v2/organizations/{org}/consumers
{ payload du client final Corporate }
legalRep = POST /v2/organizations/{org}/consumers
{ payload du représentant légal PrivateIndividual }
contract = POST /v1/organizations/{org}/contracts
{ Indirect, billingConsumerId, legalRepresentativeId, resellContractId, métadonnée de description SAG }
item = POST /v1/organizations/{org}/contracts/{contract.id}/contract-items
{ skuId, featureIds, dates, resellContractItemId, onboardingExtraParameters }
sag = GET /v1/organizations/{org}/contracts/{contract.id}/service-activation-group
ou POST /v1/organizations/{org}/service-activation-groups
{ description, contractIds: [contract.id] }
PUT /v1/organizations/{org}/service-activation-groups/{sag.id}/confirm?sendNotification=true