Sending Peppol documents in France for the companies you onboard

This guide walks through everything needed to exchange Peppol documents for a company registered in France, assuming you are integrating Recommand into your own product and onboarding French companies as your users, and that the company only sends documents over Peppol. Change any of the three answers at the top of the page to get the guide for a different situation.

What you are building

You are onboarding companies that are not your own: one Recommand team, and a company inside it for every customer you put on the network. Your customers never need a Recommand account — they see your interface, and Recommand stays behind your API calls.

That shape has a few consequences worth knowing before you write code:

• One team, many companies. There is no limit on companies per team, and billing is per team with the document volume of all companies pooled together, so the more companies you onboard the lower your price per document. See pricing per team.
• Every company is registered and verified individually. Peppol identifies companies, not platforms. Each company gets its own Peppol address and its own authorisation record.
• Verification is taken care of. Recommand hands you a URL that the company's authorised representative opens to confirm their identity. You present or forward that link; you never need to handle identity documents yourself. If you prefer to handle verification yourself, reach out to us at support@recommand.eu, we have a few other flows we can set up for you.
• You can run the whole flow under your own brand. The API is designed for white-label use, see can I whitelabel Recommand.

The Recommand dashboard shows the same teams, companies and documents your API calls produce, which is the quickest way to see what a customer is looking at while you are debugging.

Peppol in France

French domestic e-invoicing follows the French e-invoicing reform rather than plain Peppol BIS 3. Recommand covers the French specifics for you, but they do change what you send and how a company is onboarded.

What is specific to France:

• A French-accredited access point and SMP. Companies you register with country FR are automatically published on a French-accredited SMP and exchange documents through the matching access point. You do not choose or configure this: it follows from the company's country.
• A signed mandate. Before a French company can operate, its authorised representative signs a mandate that lets that accredited platform act for the company, and the file is reviewed before the company goes live. This is the one step in this guide that is not instant, so start it early.
• French document formats. Invoices and credit notes travel as French CIUS or Extended UBL, CII D22B (CIUS or Extended), or Factur-X (a PDF/A-3 with the CII XML embedded), next to plain Peppol BIS 3 UBL.
• Two processes. The same document types are published for a regulated process (urn:peppol:france:billing:regulated, transactions inside the French e-invoicing perimeter) and a non-regulated one (urn:peppol:france:billing:non-regulated, transactions outside it).
• Mandatory content. French invoices carry a billing mode and three statements (recovery costs, late-payment penalties, early-payment discount) that plain EN 16931 does not require. They go in a countrySpecific block.
• Lifecycle statuses and e-reporting. Inside the perimeter, receivers report back on the invoices they receive, and B2C or international B2B transactions have to be reported.
• Identifiers are SIREN-based. French companies are published under scheme 0225.

Create your team and API credentials

1. Sign up at app.recommand.eu/signup. The team you get is the container for every company you will onboard.
2. Create an API key on the API keys page. Note the key, the secret and your team ID.
3. Check the credentials with a request that needs no data of its own:

curl -X GET https://app.recommand.eu/api/v1/companies \
  -u key_xxx:secret_xxx

All endpoints in this guide live under https://app.recommand.eu/api/v1 and accept HTTP Basic authentication with the key as username and the secret as password. If you would rather not store a long-lived secret, JWT API keys and OAuth2 with a JWT assertion are available too, see the authentication guide.

Try it safely first

Build the whole flow against a playground team before you touch production. Playgrounds look and behave like production teams, but nothing is delivered over the real Peppol network, there are no SMP registrations, no subscription checks and no billing.

Create one from the team switcher at the top of the dashboard: Add playground, give it a name, and you are switched into it. There is no limit on how many you create.

Everything that follows in this guide is identical there: same endpoints, same validation, same webhooks (triggered by simulated inbound delivery). Register a company in the playground and use it as both sender and recipient to see a document arrive.

Three things worth knowing before you start:

• POST /:companyId/generate takes the same body as the send endpoint and returns the exact XML that sending would produce, fully validated, without transmitting, storing or billing it. It also returns the resolved documentType, doctypeId and processId, which is the quickest way to check that your country-specific fields map to the format and process you expect.
• Failure addresses. In a playground that is not connected to the Peppol Test Network, sending to 404:404 or 0208:1234567894 always fails, so you can exercise your error handling. Any other unregistered recipient is skipped without an error.
• The Peppol Test Network. For genuine end-to-end tests with real counterparties, tick Use Peppol Test Network when you create the playground. It then uses dedicated test access point and SMP endpoints while staying fully separated from production. The setting cannot be changed after creation, so make a second playground if you want both.

More detail in the getting started guide and how do I use the playground environment.

Register the company

Create one company per customer with the create company endpoint. Registration on the Peppol network happens as part of this call: identifiers and document types are set up for you, based on the company's country.

const auth =
  "Basic " + Buffer.from("key_xxx:secret_xxx").toString("base64");

const response = await fetch("https://app.recommand.eu/api/v1/companies", {
  method: "POST",
  headers: { Authorization: auth, "Content-Type": "application/json" },
  body: JSON.stringify(company),
});

const result = await response.json();
if (!result.success) throw new Error(JSON.stringify(result.errors));

const companyId = result.company.id;
const verificationUrl = result.verificationUrl; // hand this to your user

curl -X POST https://app.recommand.eu/api/v1/companies \
  -u key_xxx:secret_xxx \
  -H "Content-Type: application/json" \
  -d @company.json

The response carries a verificationUrl straight away. Keep it: the next step is to put it in front of the company's representative.

The exact identifier fields to send depend on the country, which is what the next section covers. If you would rather create identifiers and document types yourself instead of accepting the country defaults, pass skipDefaultCompanySetup: true and use the company identifiers and company document types endpoints.

French identifiers and Peppol address

In France the identifier you register decides whether your documents will pass validation later, so it is worth getting exactly right.

{
  "name": "Société de Test SAS",
  "address": "10 rue de la Paix",
  "postalCode": "75002",
  "city": "Paris",
  "country": "FR",
  "enterpriseNumber": "133512194",
  "enterpriseNumberScheme": "0002",
  "vatNumber": "FR23133512194"
}

One Peppol identifier is registered for the company:

• 0225:133512194 — the French electronic address

The company's Peppol address is therefore 0225: followed by the SIREN. French addresses may also carry a routing suffix, as in 0225:987654321_STATUTS; treat the whole string after the scheme as the identifier when a recipient gives you one.

Both SIREN (9 digits) and SIRET (14 digits) are checked with the Luhn algorithm before they are filed, and numbers that disagree with each other are refused rather than guessed at.

Registering for sending only

Because you are only looking to send invoices or other documents, register the company without recipient registration: set isSmpRecipient to false (or leave the checkbox unticked in the dashboard).

{
  "isSmpRecipient": false
}

What that means:

• The company is not published as a recipient on an SMP, so nothing is delivered to it over Peppol through your integration.
• Registration succeeds even when the company already receives its documents through another Peppol provider. The other Peppol provider will remain in charge for processing received documents for this company.
• Nothing changes for sending: outgoing documents leave through the access point as normal.

Sign the mandate and verify the company

French companies go through the same identity check as everyone else, plus two steps that are specific to France: the representative signs a mandate, and the resulting file is reviewed before the company goes live.

1. Open the verification URL (from the create-company response, the dashboard, or a fresh one from the verify company endpoint).
2. Read and sign the mandate. The verification page shows the mandate that authorises the French-accredited platform to act for the company on the Peppol network, naming the company by its SIREN and the establishment it is filed under. The representative accepts it before the identity check starts.
3. Complete the identity check. The identity verification is what signs the mandate: the proof reference is recorded on it.
4. Wait for the review. The signed mandate and the company's details are filed with the accredited platform, and the verification sits in review until that file is accepted. Only then does isVerified become true and the company start operating.

In some cases manual verification by our team will be required. If that's the case, isVerified will remain false until this manual verification is completed. The user is informed of this in the verification process.

Building verification into your onboarding

With one company you would click through this once. With many, verification is part of the flow you build: every company you register needs its own, and it is the step most likely to leave a customer stuck halfway.

Show the URL immediately. The create-company response already carries verificationUrl — no extra call needed. Put it in front of the user while they are still in your onboarding.

Ask for a fresh one when the moment has passed. Links get lost, and companies you created earlier never had one shown. The verify company endpoint starts a new verification session:

curl -X POST https://app.recommand.eu/api/v1/companies/{companyId}/verify \
  -u key_xxx:secret_xxx

The company.verification webhook fires when verification reaches a final state: verified, rejected or error. A company that comes back rejected or error and is not surfaced anywhere sits silently unusable. See working with webhooks.

Respect isVerified in your own UI. Do not let a user press send for a company that is not verified yet; this will result in an error. You should inform the user what is missing instead.

Re-verify after identifier changes. Updating a company's vatNumber or enterpriseNumber resets isVerified to false. Check the field after an update and present a new verificationUrl if it flipped.

The full mechanics are in the company verification guide.

Pick the French document format and process

A French invoice needs three decisions: the format, the process, and the mandatory French content.

The format

Name the format with doctypeId on the send request. Without it you send plain Peppol BIS 3 UBL, which is valid on the network but not what the French reform asks for inside its perimeter.

The CII and Factur-X document types carry both invoices and credit notes; the documentType field of your request decides which one it is.

Start with France UBL CIUS unless you have a reason not to. Extended is for data the CIUS does not carry, and Factur-X is for recipients who want a human-readable PDF as the carrier.

The process

Set countrySpecific.businessProcess to say which side of the French perimeter the transaction is on. The document is then sent over the matching process:

The recipient must have registered the document type for that process. Pass the processId to the verify document support endpoint to check exactly that combination rather than "any process".

The mandatory French content

French UBL, CII and Factur-X require a countrySpecific block with the billing mode and the three statements French invoices must carry. It is required for those document types and must be omitted for plain EN 16931 documents.

{
  "countrySpecific": {
    "country": "FR",
    "billingMode": "S1",
    "businessProcess": "REGULATED",
    "recoveryCostsNote": "Indemnité forfaitaire de 40 EUR pour frais de recouvrement.",
    "latePaymentPenaltiesNote": "Pénalités de retard exigibles au taux prévu dans les conditions générales de vente.",
    "earlyPaymentDiscountNote": "Aucun escompte accordé pour paiement anticipé."
  }
}

billingMode follows AFNOR XP Z12-012. The common ones are B1 (goods), S1 (services) and M1 (mixed); the full list, including already-paid, advance payment, subcontracting and multi-seller variants, is documented on the send document endpoint.

Invoicing outside France

The French formats and processes are for the French perimeter. A counterparty in another country is registered for the standard Peppol billing process, so a regulated document does not match anything they published.

For those invoices, send plain Peppol BIS 3 UBL and leave the countrySpecific block out with it, it belongs to the French document types only. The rest of the invoice is unchanged.

Send a document

One endpoint sends everything: POST /:companyId/send. The companyId is the sender, recipient is the Peppol address of the receiver, and document is the invoice or credit note as JSON. Recommand will validate the document and generate the XML.

const response = await fetch(
  `https://app.recommand.eu/api/v1/${companyId}/send`,
  {
    method: "POST",
    headers: { Authorization: auth, "Content-Type": "application/json" },
    // The body below, with doctypeId and countrySpecific where the country
    // needs them.
    body: JSON.stringify(sendRequest),
  }
);

const result = await response.json();
if (!result.success) {
  // result.errors is keyed by field path, e.g. { "buyer.vatNumber": [...] }
}

curl -X POST https://app.recommand.eu/api/v1/{companyId}/send \
  -u key_xxx:secret_xxx \
  -H "Content-Type: application/json" \
  -d @send-invoice.json

{
  "recipient": "0208:0123456789",
  "documentType": "invoice",
  "document": {
    "invoiceNumber": "INV-2026-001",
    "issueDate": "2026-08-17",
    "dueDate": "2026-09-16",
    "currency": "EUR",
    "buyer": {
      "name": "Customer Company",
      "street": "Customer Street 1",
      "city": "Antwerp",
      "postalZone": "2000",
      "country": "BE",
      "vatNumber": "BE0987654321"
    },
    "paymentMeans": [{ "iban": "BE68539007547034" }],
    "lines": [
      {
        "name": "Consulting Services",
        "quantity": "10.00",
        "unitCode": "HUR",
        "netPriceAmount": "100.00",
        "vat": { "category": "S", "percentage": "21.00" }
      }
    ]
  }
}

The seller block is filled in from the company when you leave it out, which is usually what you want: it keeps the company's registered identifiers and the document in agreement.

Things worth wiring up while you are here:

• Validation errors. Outgoing documents are always validated. A success: false response with errors keyed by field path is a document your recipient would have rejected, so surface it to the user who typed the data.
• Email fallback. Pass email.to with when: "on_peppol_failure" to fall back to email when a recipient turns out not to be reachable over Peppol, or send with recipient: null for email-only delivery. See email delivery and notifications.
• PDFs. pdfGeneration.enabled attaches a generated PDF of the document. You can also attach an existing PDF (or other files) via attachments; see adding attachments.

For a full field reference, see sending invoices and sending credit notes.

Going live

Before you switch your first real customer over, walk this list:

• A valid subscription in production. Playgrounds skip the subscription check; production does not.
• Verification handled in your UI. Show the verificationUrl at the right moment, make it forwardable, and handle the company.verification webhook so a company that comes back rejected or error does not sit silently unusable.
• isVerified respected. Do not let a user press send for a company that is not verified yet; explain what is missing instead.
• Webhook endpoint hardened. Signature verification, a fast 200, retries and idempotency on your side.
• Errors surfaced, not swallowed. Validation errors name the field that is wrong; put that in front of the person who can fix it.
• One real document, end to end. Send an invoice between two companies you control on production before letting customers in.

Before you go live in France

France adds a few checks to the list above, all of them things that only show up once real documents move:

• The mandate is accepted. isVerified is true, which for a French company means the signed mandate cleared its review. Plan this in: it is the one step that is not instant.
• The company carries the SIREN under scheme 0002. Both the documents you send and the mandate itself are built from the company's own identifiers, so a SIRET or a missing scheme surfaces as rejected documents rather than as a registration error.
• You know which side of the perimeter you are on. Regulated is the default; transactions outside it have to say so explicitly, and the counterparty has to be registered for the process you use.

If the company sends documents, two more:

• The format and process are what you meant. Check one document before the first real send: the preview in the dashboard, or generate from the API, shows the resolved doctypeId and processId.
• Invoices are in EUR, with the billing mode and the three mandatory statements filled in.

Where to get help

• Troubleshooting. Common rejections, delivery failures and validation errors are collected in the troubleshooting guide.
• Questions. The FAQ covers Peppol, addressing, VAT and billing.
• Email. support@recommand.eu:include the company ID and, for a delivery problem, the document ID.
• Discord. Join the server for release announcements and quick questions.
• Keep track of changes. New endpoints and behaviour are recorded in the changelog.

Other guides for France

• Receiving Peppol documents in France for the companies you onboard
• Sending and receiving Peppol documents in France for the companies you onboard
• Sending Peppol documents in France for your own company
• Receiving Peppol documents in France for your own company
• Sending and receiving Peppol documents in France for your own company