# French eInvoice - Activation via Organizations API

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](/products/oneplatform/one-platform-knowledge-center/03-products-and-modules/02-namirial-services/01-french-einvoice/french-einvoice-activation-ui).

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.


```http
Authorization: Bearer <token>
```

See [Authentication](/products/oneplatform/one-platform-knowledge-center/04-api-and-integration/authentication/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:


```http
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.


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


```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.


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


```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.


```http
POST /v1/organizations/{organizationId}/contracts
Content-Type: application/json
```


```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.


```http
POST /v1/organizations/{organizationId}/contracts/{contractId}/contract-items
Content-Type: application/json
```


```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`. |



```mermaid
graph TD
  OUT["out-b2b<br/>Out-B2B Domestic"]
  IN["in-b2b<br/>In B2B"]
  ER["e-reporting<br/>eReporting"]
  DTP["dt-portal<br/>Portal DT"]
  EDITOR["editor<br/>Editor"]
  ID["identification<br/>KYC/KYB"]
  MM["multiple-mandate<br/>Multiple mandate"]

  OUT -->|"enables"| DTP
  IN -->|"enables"| DTP
  ER -->|"enables"| DTP
  DTP -->|"required by"| EDITOR
  DTP -->|"required by"| ID
  IN -->|"required by"| MM
```

## 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:


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

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


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


```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`.


```http
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


```text
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
```

## Related Concepts

- [French eInvoice Overview](/products/oneplatform/one-platform-knowledge-center/03-products-and-modules/02-namirial-services/01-french-einvoice/french-einvoice-overview)
- [French eInvoice - Service Activation (Organization Portal)](/products/oneplatform/one-platform-knowledge-center/03-products-and-modules/02-namirial-services/01-french-einvoice/french-einvoice-activation-ui)
- [French eInvoice - Activation Workflow](/products/oneplatform/workflows/french-einvoice-activation)
- [Create a Contract](/products/oneplatform/one-platform-knowledge-center/04-api-and-integration/integration-guides/create-a-contract)
- [Authentication](/products/oneplatform/one-platform-knowledge-center/04-api-and-integration/authentication/authentication)
- [Organizations API](/products/oneplatform/apis/oas/organizations)