French eInvoice - Activation via Organizations API
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

This integration guide describes the API flow used by a partner organization to activate French eInvoice for a final customer.

The flow mirrors the Organization Portal guide.

Replace:

{organizationId} with the partner organization id;
{customerId} with the final customer id;
{legalRepresentativeId} with the legal representative id;
{delegateId} with the delegate id, when onboarding is completed by a delegate instead of the legal representative;
{contractId} with the contract id returned by contract creation;
{sagId} with the Service Activation Group id.

Environment Configuration

Organizations API endpoint base URL can change depending on the target environment

Environment	Base URL
Production	`https://platform-api.namirial.app`
Pre-production	`https://platform-api-demo.namirial.app`
Test	`https://platform-api-test.namirial.app`

Authentication

All requests require a bearer token in the Authorization header.

Authorization: Bearer <token>

See Authentication for the OAuth2 client credentials flow used by One Platform integrations.

Flow at a Glance

#	Step	Method	Endpoint
1	Create or reuse final customer	`POST`	`/v2/organizations/{organizationId}/consumers`
2	Create or reuse legal representative	`POST`	`/v2/organizations/{organizationId}/consumers`
3	Create indirect contract and activation context	`POST`	`/v1/organizations/{organizationId}/contracts`
4	Add French eInvoice item with onboarding parameters	`POST`	`/v1/organizations/{organizationId}/contracts/{contractId}/contract-items`
5	Resolve or create Service Activation Group	`GET` / `POST`	`/v1/organizations/{organizationId}/contracts/{contractId}/service-activation-group` or `/v1/organizations/{organizationId}/service-activation-groups`
6	Confirm Service Activation Group	`PUT`	`/v1/organizations/{organizationId}/service-activation-groups/{sagId}/confirm?sendNotification=true`

For production-grade integrations, search first and reuse existing consumers/contracts when present. The payloads below show the creation path for a new activation.

Recommended lookups:

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

Conditional Onboarding Rules

French eInvoice onboarding uses two conditional rules that must be reflected in API payloads:

Configuration	API field	Effect in onboarding
Legal representative onboarding	Omit `hasDelegate` or set it to `false` in `onboardingExtraParameters`.	The recipient reviews and completes onboarding as the legal representative.
Delegate onboarding	Set `hasDelegate: "true"` in `onboardingExtraParameters`.	The recipient reviews and completes onboarding as a delegate instead of the legal representative.
Portail DT enabled	Include `dt-portal` in `featureIds` and provide `adminEmail`, `adminFirstName`, and `adminLastName` in `onboardingExtraParameters`.	The onboarding flow can request or display the Portail DT administrator data.
Portail DT not enabled	Do not include `dt-portal` in `featureIds`.	Portail DT administrator data is not required.

onboardingExtraParameters is part of the contract item creation payload. The values are string key/value pairs, so boolean-like values are sent as strings.

1. Create the Final Customer

Create the final customer as a Corporate consumer in the partner organization scope.

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"
}

Key fields:

Field	Description
`customerType`	Use `Corporate` for the final customer company.
`taxCode1`	French VAT / TVA number.
`taxCode2`	SIREN.
`taxCode3`	SIRET.
`metadata.siret_01`	Additional SIRET metadata used by the activation flow. You can provide an arbitrary number of SIRET entries using the `siret_nn` pattern, for example `siret_01`, `siret_02`, `siret_03`.
`billable`	Set to `true` to enable address input for the customer.

The identifiers must be consistent when more than one is provided:

taxCode3 (SIRET) starts with the 9-digit taxCode2 (SIREN);
the last 9 digits of taxCode1 (TVA) equal taxCode2 (SIREN).

Store the returned id as customerId.

2. Create the Legal Representative

Create the legal representative as a PrivateIndividual consumer.

POST /v2/organizations/{organizationId}/consumers
Content-Type: application/json

{
  "name": "Laurent Vidal",
  "country": "FR",
  "type": "Customer",
  "customerType": "PrivateIndividual",
  "firstName": "Laurent",
  "lastName": "Vidal",
  "taxCode2": "T0301KVRTQXKHJY1KCZ2SYKF0NRM2",
  "emails": ["laurent.vidal@vidal-solutions.fr"],
  "phones": [],
  "mobilePhones": [],
  "metadata": {},
  "billable": false
}

For a French PrivateIndividual, do not send taxCode1 or taxCode3.

Store the returned id as legalRepresentativeId.

Legal representative taxCode2

For the French eInvoice legal representative, generate taxCode2 (temporary SIREN) as T03 followed by a ULID, for example T0301KVRTQXKHJY1KCZ2SYKF0NRM2.

3. Create the Indirect Contract

Create the final customer contract in Draft state. The contract carries the commercial context and recipient. The Service Activation Group can be associated during the contract creation workflow when the API/UI version exposes that capability; otherwise create or retrieve it explicitly before confirmation as shown in step 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": "8ef6cf04-a0e4-478b-8c24-bd1104605df5",
  "legalEntityId": "ea5d7839-acb6-4ae8-91b1-79a6e928ef37",
  "description": "French eInvoice activation - VIDAL SOLUTIONS INFORMATIQUES SAS",
  "number": "VIDAL-FR-EINV-01",
  "metadata": {
    "serviceActivationGroupDescription": "French eInvoice activation - VIDAL SOLUTIONS INFORMATIQUES SAS"
  },
  "type": "Indirect",
  "resellContractId": "2d29844f-1365-46ea-8ebb-18c6d79f05d5",
  "createOrganization": false
}

Field	Description
`recipient.email`	Email used by the activation flow.
`legalRepresentativeId`	Id from step 2.
`billingConsumerId`	Final customer id from step 1.
`issuerId`	Issuer consumer id for the partner organization.
`legalEntityId`	Namirial legal entity that owns the offer.
`metadata.serviceActivationGroupDescription`	Optional integration metadata that keeps the SAG description aligned with the contract creation step. Use the native SAG field instead when your API version exposes one.
`type`	Use `Indirect` for partner-issued final customer contracts.
`resellContractId`	Distribution contract used as resell source.
`createOrganization`	`true` creates a customer-side organization; `false` keeps the activation back-office only.

Store the returned id as contractId.

4. Add the French eInvoice Contract Item

Add the service item to the contract.

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"
}

Field	Description
`skuId`	French eInvoice SKU. The current activation flow uses `1089000001`.
`featureIds`	Feature set to activate on the item. The default French eInvoice features are `out-b2b`, `in-b2b`, and `e-reporting`.
`onboardingExtraParameters.hasDelegate`	Set to `"true"` when the onboarding subject is a delegate rather than the legal representative. Omit it or set `"false"` for legal-representative onboarding.
`onboardingExtraParameters.adminEmail`	Portail DT administrator email. Required only when `featureIds` includes `dt-portal`.
`onboardingExtraParameters.adminFirstName`	Portail DT administrator first name. Required only when `featureIds` includes `dt-portal`.
`onboardingExtraParameters.adminLastName`	Portail DT administrator last name. Required only when `featureIds` includes `dt-portal`.
`signed`	Set to `true` only when the item is already signed outside One Platform.
`provisioned`	Set to `true` only when the item is already provisioned outside One Platform.
`resellContractItemId`	Contract item id from the resell/distribution contract.
`skuParameters`	Service-specific parameters when required by the selected features.
`envelopeParameters`	Optional envelope-specific parameters.

French eInvoice Features

Feature ID	English label	Italian label	French label	Default	Dependency
`out-b2b`	Out-B2B Domestic	Fatturazione attiva B2B	Facturation electronique sortante B2B domestique	Yes	None
`in-b2b`	In B2B	Fatturazione passiva B2B	Facturation electronique entrante B2B	Yes	None
`e-reporting`	eReporting	Reportistica elettronica	Declaration electronique	Yes	None
`dt-portal`	Portal DT	Portale DT	Portail DT	No	Requires any of `out-b2b`, `in-b2b`, `e-reporting`.
`editor`	Editor	Editor	Editeur	No	Requires `dt-portal`.
`identification`	KYC/KYB	KYC/KYB	KYC/KYB	No	Requires `dt-portal`.
`multiple-mandate`	Multiple mandate	Mandato multiplo	Mandat multiple	No	Requires `in-b2b`.

5. Resolve or Create the Service Activation Group

If the contract creation flow already created or associated a SAG, retrieve its id from the contract:

GET /v1/organizations/{organizationId}/contracts/{contractId}/service-activation-group

If no SAG exists yet, create one containing the contract to activate.

POST /v1/organizations/{organizationId}/service-activation-groups
Content-Type: application/json

{
  "description": {
    "en": "French eInvoice activation - VIDAL SOLUTIONS INFORMATIQUES SAS"
  },
  "contractIds": [
    "{contractId}"
  ]
}

Store the returned id as sagId. This replaces the old portal-side "update SAG" action: activation data should be supplied during contract and contract-item creation, then the SAG is confirmed.

6. Confirm the Service Activation Group

Confirm the SAG to move the contract out of Draft.

PUT /v1/organizations/{organizationId}/service-activation-groups/{sagId}/confirm?sendNotification=true
Content-Type: application/json

Set sendNotification=true to send the activation email to the recipient. If this parameter is omitted or set to false, the SAG is confirmed but the email is not sent.

The portal confirmation message explains that the recipient will be able to view the contract and fill in missing fields after confirmation.

End-to-End Pseudocode

customer = POST /v2/organizations/{org}/consumers
           { Corporate final customer payload }

legalRep = POST /v2/organizations/{org}/consumers
           { PrivateIndividual legal representative payload }

contract = POST /v1/organizations/{org}/contracts
           { Indirect, billingConsumerId, legalRepresentativeId, resellContractId, SAG description metadata }

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
      or POST /v1/organizations/{org}/service-activation-groups
         { description, contractIds: [contract.id] }

PUT /v1/organizations/{org}/service-activation-groups/{sag.id}/confirm?sendNotification=true