Company Config Create
Purpose of Use: This endpoint creates the initial France e-invoicing module configuration record for a company on the Docnova platform. It is a one-time setup operation — a given company can only have one France configuration. Attempting to call this endpoint again for the same company returns 400; subsequent changes must go through PUT /reporting/FR/config/{companyId}.
The French e-invoicing reform, mandatory from 01/09/2026, requires all VAT-registered companies (assujettis) to transmit B2B transaction and payment data to the PPF (Portail Public de Facturation) via a Plateforme Agréée (PA — approved platform). This endpoint bootstraps the PPF participation lifecycle for the company.
This endpoint is used for the following purposes:
- Conditional PPF onboarding trigger: PPF Annuaire registration trigger: If enabled is sent as true, Docnova immediately registers the company in the PPF Annuaire after saving the record. If enabled is false, registration is deferred until the record is updated with enabled: true.
- PPF status initialization: Automatically sets
ppfStatustoPENDINGon creation. This field transitions toACTIVEonce PPF onboarding completes. - VAT regime assignment: The
vatRegimevalue drives the reporting cadence, including transaction and payment report frequency, for all subsequent PPF submissions. - Declarant role assignment: Declarant role assignment: Sets whether the company acts as SE (Seller — issues invoices) or BY (Buyer — receives invoices) in PPF reporting. Most companies should use SE.
Reporting Frequency by VAT Regime
Reporting frequency by VAT regime
| VatRegime | Full Name | Transaction Report | Payment Report |
|---|---|---|---|
| RRN_M | Régime Réel Normal — Mensuel | Décadaire (3 × 10-day / month) | Monthly |
| RRN_T | Régime Réel Normal — Trimestriel | Monthly | Monthly |
| RSI | Régime Simplifié d'Imposition | Monthly | Monthly |
| FB | Franchise en Base de TVA | Bi-monthly | Bi-monthly |
Endpoint Information
| Property | Value |
|---|---|
| URL | /reporting/FR/config |
| Method | POST |
| Content-Type | application/json |
| Base URL | Stage Environment URLhttps://api-fr-stage.docnova.ai/ Production Environment URLhttps://api-fr.docnova.ai/ |
| Authorization | R-Auth header (JWT token) |
Example Request
curl --location 'https://api-fr-stage.docnova.ai/reporting/FR/config' \
--header 'Content-Type: application/json' \
--header 'R-Auth: {{companyJwt}}' \
--data '{
"companyId": "{{companyId}}",
"vatRegime": "RSI",
"declarantRoleCode": "SE",
"enabled": true,
"siret": "{{siret}}"
}'
Request Parameters
Request Body
Content-Type: application/json
Body Field Definitions
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| companyId | string (UUID) | Yes | Valid UUID | The Docnova system UUID of the company for which the France configuration is being created. The company must already exist in the system. |
| vatRegime | FranceVatRegime | Yes | Enum — see Enum Values | The company's TVA regime. Determines reporting cadence and PPF submission deadlines. |
| enabled | boolean | Yes | true / false | Activates or deactivates the France e-reporting module. If true, the server immediately triggers PPF annuaire onboarding after saving the record. If false, onboarding is deferred. |
| siret | string | No | Exactly 14 digits (\d{14}) | The company's 14-digit SIRET number (SIREN 9 digits + NIC 5 digits). Validated by format if provided. Can be set or corrected later via PUT, unless PPF onboarding has already completed. |
| siren | string | No | Exactly 9 digits | The company's 9-digit SIREN number. When provided without siret, PPF registration is performed at SIREN level (ppfMaille: "SIREN"). |
| declarantRoleCode | string | No | 2-3 characters | Sets whether the company acts as SE (Seller — issues invoices) or BY (Buyer — receives invoices) in PPF reporting. Most companies should use SE. |
| dynamicEdiEnabled | boolean | No | true / false | Enables per-company dynamic EDI transformation mode. Defaults to false if omitted. |
⚠️ One-time operation: Only one France configuration can exist per company. Calling this endpoint again for the same
companyIdreturns400 BAD_REQUESTwith the message"France configuration already exists for this company. Use update instead."
Responses
200 - Successful Response
A successful creation returns HTTP 200 OK with the full newly created configuration object.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"companyId": "b7844db0-57a1-4f5d-af65-f1e55b1e9beb",
"siret": "27168850399286",
"vatRegime": "RSI",
"enabled": false,
"declarantRoleCode": "SE",
"dynamicEdiEnabled": false,
"ppfIdInstance": null,
"ppfActivationDate": null,
"ppfStatus": "PENDING",
"ppfMaille": null,
"createdTime": "2026-06-20T17:26:56",
"updatedTime": "2026-06-20T17:26:56"
}
Response Body — Created Configuration Record Fields
| Field | Type | Initial Value | Description |
|---|---|---|---|
| id | UUID | Auto-generated | Unique system identifier for this configuration record. |
| companyId | UUID | From request | The company UUID that owns this configuration. |
| siret | string (14) | null | From request | The 14-digit SIRET number. null if not provided in the request. |
| vatRegime | FranceVatRegime | From request | The assigned VAT regime. Governs all subsequent PPF reporting cadences. |
| enabled | boolean | From request | true if the France e-reporting module is active and PPF onboarding was triggered. |
| declarantRoleCode | string | null | From request | Declarant role in Flux 10. null if not provided. |
| dynamicEdiEnabled | boolean | false | Dynamic EDI mode flag. Always false unless explicitly set. |
| ppfIdInstance | string | null | null | PPF-assigned instance identifier. Always null on initial creation; populated after onboarding completes. |
| ppfActivationDate | LocalDate | null | null | Date the company became active on PPF. null on creation. |
| ppfStatus | FrancePpfStatus | PENDING | Always PENDING on creation, regardless of enabled. Transitions to ACTIVE once PPF onboarding is confirmed. |
| ppfMaille | FrancePpfMaille | null | null | PPF addressability granularity. null on creation; set by the PPF onboarding response. |
| createdTime | LocalDateTime | Now | Timestamp of this creation operation. ISO 8601, second precision. |
| updatedTime | LocalDateTime | Now | Equals createdTime on initial creation. |
Enum Values
FranceVatRegime — VAT Regime
| Value | Full Name | Transaction Report Frequency | Payment Report Frequency |
|---|---|---|---|
| RRN_M | Régime Réel Normal — Mensuel | Décadaire (10-day, 3×/month) | Monthly |
| RRN_T | Régime Réel Normal — Trimestriel | Monthly | Monthly |
| RSI | Régime Simplifié d'Imposition | Monthly | Monthly |
| FB | Franchise en Base de TVA | Bi-monthly | Bi-monthly |
declarantRoleCode — Declarant Role
| Value | French Term | Description |
|---|---|---|
| SE | Vendeur | Seller — the company issues invoices and submits Flux 10 transaction reports as the invoice sender. |
| BY | Acheteur | Buyer — the company receives invoices and reports as the invoice recipient. |
FrancePpfStatus — PPF Registration Status (read-only in response)
| Value | Description |
|---|---|
| PENDING | Default on creation. Onboarding initiated but not yet confirmed by PPF. |
| ACTIVE | PPF onboarding complete; report submissions are permitted. |
| CLOSED | PPF registration closed; new submissions are blocked. |
FrancePpfMaille — Addressability Granularity (read-only in response)
| Value | Description |
|---|---|
| SIREN | Registered at SIREN level (9 digits) in PPF annuaire. |
| SIRET | Registered at establishment level via SIRET (14 digits). |
| SUFFIXE | Identified by a suffix appended to SIRET; for specific sub-units. |
| CODE_ROUTAGE | Identified via a custom routing code; for large corporate groups. |
All error responses share the following structure:
{
"errorMessage": "<human-readable message>",
"errorType": "<error type key>",
"errorTitle": "<HTTP status name>",
"errorId": "<trace UUID>",
"status": 404,
"timestamp": "2026-06-20T17:26:56.155059",
"path": "/reporting/FR/config"
}
400 - Bad Request
Returned when a France configuration record already exists for this companyId.
{
"errorMessage": "France configuration already exists for this company. Use update instead.",
"errorType": "BAD_REQUEST",
"errorTitle": "BAD_REQUEST",
"status": 400,
"timestamp": "2026-06-20T17:26:56.155059",
"path": "/reporting/FR/config"
}
Condition: A France configuration record already exists for this companyId. This endpoint is a one-time setup call; updates must use PUT /reporting/FR/config/{companyId}.
400 - Bad Request: Body Field Validation Failure
Returned when a required field is missing or a field fails its validation constraint.
{
"errorMessage": "size must be between 14 and 14, must match \"\\d{14}\"",
"errorType": "VALIDATION_ERROR",
"errorTitle": "BAD_REQUEST",
"status": 400,
"timestamp": "2026-06-20T17:26:56.155059",
"path": "/reporting/FR/config"
}
Condition: A required field is missing (companyId, vatRegime) or a field fails its constraint — siret is not exactly 14 digits, or declarantRoleCode is outside the 2-3 character range.
400 - Bad Request: Company SIREN / VAT Validation Failure
Returned when the company record in Docnova is missing its SIREN or VAT number is invalid.
{
"errorMessage": "Company taxNumber (SIREN) is required for France configuration",
"errorType": "BAD_REQUEST",
"errorTitle": "BAD_REQUEST",
"status": 400,
"timestamp": "2026-06-20T17:26:56.155059",
"path": "/reporting/FR/config"
}
Condition: The company record in Docnova is missing its taxNumber (SIREN must be 9 digits) or its vatNumber does not match the French format (FR + 2 alphanumeric + 9 digits). This validation runs before the config record is created.
401 - Unauthorized
Returned when the R-Auth header is missing, malformed, or the JWT token is expired.
{
"errorMessage": "Not authorized for this action",
"errorType": "NOT_AUTHORITY",
"errorTitle": "UNAUTHORIZED",
"status": 401,
"timestamp": "2026-06-20T17:26:56.155059",
"path": "/reporting/FR/config"
}
Condition: The R-Auth header is missing, malformed, or the JWT exp claim has passed.
404 - Not Found
Returned when the companyId in the request body does not match any company record in the Docnova system.
{
"errorMessage": "Company not found!",
"errorType": "NOT_FOUND_COMPANY",
"errorTitle": "NOT_FOUND",
"errorId": "3c3904d7-0c6a-4f9b-a756-...",
"status": 404,
"timestamp": "2026-06-20T17:26:56.155059",
"path": "/reporting/FR/config"
}
Condition: The companyId in the request body does not match any company record in the Docnova system.
500 - Internal Server Error
Returned when an unexpected runtime exception occurs while processing the request.
{
"errorMessage": "An unexpected error occurred",
"errorType": "RUNTIME_ERROR",
"errorTitle": "INTERNAL_SERVER_ERROR",
"status": 500,
"timestamp": "2026-06-20T17:26:56.155059",
"path": "/reporting/FR/config"
}
Condition: Unexpected runtime exception — database connectivity failure, JPA transaction error, or PPF annuaire onboarding call failure after the record has been saved.