Passer au contenu
Dernière mise à jour

French eInvoice - Activation via l'Organizations API

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.

Authentification

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.

Vue d'ensemble du flux

#ÉtapeMéthodeEndpoint
1Créer ou réutiliser le client finalPOST/v2/organizations/{organizationId}/consumers
2Créer ou réutiliser le représentant légalPOST/v2/organizations/{organizationId}/consumers
3Créer le contrat indirect et le contexte d'activationPOST/v1/organizations/{organizationId}/contracts
4Ajouter l'élément French eInvoice avec les paramètres d'onboardingPOST/v1/organizations/{organizationId}/contracts/{contractId}/contract-items
5Résoudre ou créer le Service Activation GroupGET / POST/v1/organizations/{organizationId}/contracts/{contractId}/service-activation-group ou /v1/organizations/{organizationId}/service-activation-groups
6Confirmer le Service Activation GroupPUT/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=1

Règles conditionnelles d'onboarding

L'onboarding French eInvoice utilise deux règles conditionnelles qui doivent être reflétées dans les payloads API :

ConfigurationChamp APIEffet dans l'onboarding
Onboarding du représentant légalOmettez 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.

1. Créer le client final

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 :

ChampDescription
customerTypeUtilisez Corporate pour la société cliente finale.
taxCode1Numéro de TVA français.
taxCode2SIREN.
taxCode3SIRET.
metadata.siret_01Mé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.
billableDé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 de taxCode2 (SIREN) ;
  • les 9 derniers chiffres de taxCode1 (TVA) correspondent à taxCode2 (SIREN).

Conservez l'identifiant retourné comme customerId.

2. Créer le représentant légal

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.

taxCode2 du représentant légal

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.

3. Créer le contrat indirect

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
}
ChampDescription
recipient.emailE-mail utilisé par le flux d'activation.
legalRepresentativeIdIdentifiant issu de l'étape 2.
billingConsumerIdIdentifiant du client final issu de l'étape 1.
issuerIdIdentifiant du consommateur émetteur pour l'organisation partenaire.
legalEntityIdEntité légale Namirial propriétaire de l'offre.
metadata.serviceActivationGroupDescriptionMé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.
typeUtilisez Indirect pour les contrats client final émis par un partenaire.
resellContractIdContrat de distribution utilisé comme source de revente.
createOrganizationtrue crée une organisation côté client ; false conserve une activation back-office uniquement.

Conservez l'identifiant retourné comme contractId.

4. Ajouter l'élément de contrat French eInvoice

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"
}
ChampDescription
skuIdSKU French eInvoice. Le flux d'activation actuel utilise 1089000001.
featureIdsEnsemble 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.hasDelegateDé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.adminEmailE-mail de l'administrateur du Portail DT. Requis uniquement lorsque featureIds inclut dt-portal.
onboardingExtraParameters.adminFirstNamePrénom de l'administrateur du Portail DT. Requis uniquement lorsque featureIds inclut dt-portal.
onboardingExtraParameters.adminLastNameNom de l'administrateur du Portail DT. Requis uniquement lorsque featureIds inclut dt-portal.
signedDéfinissez sur true uniquement lorsque l'élément est déjà signé hors One Platform.
provisionedDéfinissez sur true uniquement lorsque l'élément est déjà provisionné hors One Platform.
resellContractItemIdIdentifiant de l'élément de contrat issu du contrat de revente/distribution.
skuParametersParamètres spécifiques au service lorsque les fonctionnalités sélectionnées les exigent.
envelopeParametersParamètres optionnels propres à l'enveloppe.

Fonctionnalités French eInvoice

Feature IDLibellé anglaisLibellé italienLibellé françaisPar défautDépendance
out-b2bOut-B2B DomesticFatturazione attiva B2BFacturation electronique sortante B2B domestiqueOuiAucune
in-b2bIn B2BFatturazione passiva B2BFacturation electronique entrante B2BOuiAucune
e-reportingeReportingReportistica elettronicaDeclaration electroniqueOuiAucune
dt-portalPortal DTPortale DTPortail DTNonNécessite l'une des fonctionnalités out-b2b, in-b2b ou e-reporting.
editorEditorEditorEditeurNonNécessite dt-portal.
identificationKYC/KYBKYC/KYBKYC/KYBNonNécessite dt-portal.
multiple-mandateMultiple mandateMandato multiploMandat multipleNonNécessite in-b2b.

active

active

active

requis par

requis par

requis par

out-b2b
Out-B2B Domestic

in-b2b
In B2B

e-reporting
eReporting

dt-portal
Portal DT

editor
Editor

identification
KYC/KYB

multiple-mandate
Multiple mandate

active

active

active

requis par

requis par

requis par

out-b2b
Out-B2B Domestic

in-b2b
In B2B

e-reporting
eReporting

dt-portal
Portal DT

editor
Editor

identification
KYC/KYB

multiple-mandate
Multiple mandate

5. Résoudre ou créer le Service Activation Group

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-group

Si 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é.

6. Confirmer le Service Activation Group

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/json

Dé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.

Pseudo-code de bout en bout

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

Concepts associés