France API integration

This page is for integrators who connect an ERP or middleware to xTool over the public API (/api/v2/..., x-api-key header).

France configuration (Annuaire / QAS registration, company identifiers, tax-report mode) is managed in the web UI only. There is no public /api/v2/france/... endpoint. After the configuration is Active, all invoice exchange, payments, and tax-report reads go through the standard document / transaction / payment APIs.

Related pages:

• Practical request examples: Send and receive invoices
• QAS setup: Test Environment
• Concepts: Transactions, Payments, Tax reports
• OpenAPI: API Reference

Integration model

France API work is built on standard xTool entities. Use the exact names below — they match the API resources.

Object model:

flowchart TD
    Document --> Transaction
    Transaction --> Events["Transaction Event[]"]
    Events --> Files["Transaction Event File[]"]
    Transaction --> Actions["Transaction Action[]"]

• Transaction type: send.france or receive.france
• Actions: buyer lifecycle + payment_sent on receive.france; payment_received on send.france

Transaction Action ≠ Transaction Event.
You POST a Transaction Action. For buyer lifecycle actions, xTool records a matching Transaction Event (for example action france.invoice.approve → event france.invoice.approved). Action france.invoice.payment_sent (receive.france) marks payment as transmitted. Action france.invoice.payment_received (send.france) creates a Payment allocated to the document (same as POST /api/v2/payments). On B2B domestic, these map to CDV lifecycle codes (see below); B2C and B2B cross-border may not use CDV.

See also Transactions.

Transaction, events, actions, and files

This section is the core object model for France lifecycle tracking.

Transaction

A Transaction is one send or receive attempt for one document on one channel.

1
2
3

GET /api/v2/transactions/{transaction_id}?include=events&include=actions&include=status_log
GET /api/v2/transactions?document_id={document_id}
GET /api/v2/transactions?transaction_type=receive.france

One document can have multiple transactions (resend, receive, other channels). Always follow the specific France transaction you care about.

Transaction Event

A Transaction Event is a historical record of something that already happened on that transaction. Clients never create events.

1
2

GET /api/v2/transactions/{transaction_id}/events
GET /api/v2/transaction-events/{transaction_event_id}

include=events on the transaction get also loads nested event files.

France transaction event types

CDV codes (204–212) come from the domestic B2B lifecycle (CDAR / AFNOR XP Z12-012). They apply to B2B domestic flows. B2C and B2B cross-border use different reporting paths and may not produce these CDV lifecycle codes; xTool still records the same transaction event types when the channel reports the corresponding status.

Timing depends on domestic vs cross-border scenarios and provider processing. Poll and process new event ids only.

When the channel delivers a lifecycle notification (CDAR / ApplicationResponse) for B2B domestic, xTool prefers the CDV code in the XML (ProcessConditionCode / ResponseCode) over the provider invoice state. That is what distinguishes e.g. full approval (205) from partial approval (206).

Transaction Event File

A Transaction Event File is a stored file attached to a Transaction Event (for example the invoice XML that was sent or received, or a related acknowledgement payload).

Files appear nested under events when you list/get events. Download content separately:

1

GET /api/v2/transaction-event-files/{transaction_event_file_id}/download

Typical usage:

1. Poll transaction with include=events
2. Find the event of interest (for example france.invoice.receive or france.invoice.send)
3. Read files[].id / filename / content_type
4. Download each needed file by id

There is no create/update/delete of event files via the public client API.

Transaction Action

A Transaction Action is a command you ask xTool to perform on an existing transaction. Today France buyer actions exist only on receive.france.

1
2

GET /api/v2/transactions/{transaction_id}/actions
POST /api/v2/transactions/{transaction_id}/actions

There is no get-by-id endpoint for a single action. Use the list, or include=actions on the transaction get.

CDV codes → actions (B2B domestic)

CDV codes apply to B2B domestic only (CDAR / AFNOR XP Z12-012). B2C and B2B cross-border may not use them. Codes without an action are reported by the channel only.

Earlier channel statuses such as 200 (Déposée), 202 (Reçue), and 203 (Mise à disposition) are also B2B domestic CDV codes; xTool does not expose client actions for them.

France action types → resulting events

Rules:

• Submitting the same lifecycle action twice for one transaction returns conflict (409)
• Wait for action status to become completed / failed, and for the matching event to appear
• Payment sent (receive.france) only updates channel status; it does not create a Payment
• Payment received (send.france) creates the Payment immediately and syncs to the provider

Authentication and organisation scope

1

x-api-key: <your-api-key>

The API key is scoped to an organisation. Every document, transaction, payment, and tax report you see belongs to that organisation.

Checklist:

1. Create an API key in the web UI with permission to send via France (and to read documents / transactions / payments as needed).
2. Call /api/v2/... with that key.
3. Ensure the organisation has at least one Active France configuration (web UI → Channels → France).

France configuration and which account sends

France configuration is not selected in the send request body. On send.france, xTool:

1. Takes the document’s organisation
2. Loads Active France configurations for that organisation (with a provider account id)
3. Matches the document sender (metadata.sender_id, typically the supplier endpoint / SIREN) to configuration siren / siret / cin_value
4. If no match, falls back to the first Active configuration with an account

Practical rules:

• Put the seller identifiers in the invoice so they match the configuration you intend to send from
• One organisation may have several France configurations (for example two QAS companies for send/receive tests)
• Reception-only mode (annuaire_only) cannot send invoices

Configuration lifecycle (NEW → … → DIRECTORY_PENDING / SCHEDULED → ACTIVE) is web + background jobs. API exchange requires Active.

Formats

Preferred for France channel tests and production-like flows:

France CIUS models require France-specific fields such as document.profile_id (billing mode, for example S1).

Domestic B2B send typically expects EUR, a short enough invoice number, and a French buyer routing id (PIN / endpoint) where required. Validation failures return before or during prepare.

Upload options:

1
2
3

POST /api/v2/documents/upload/xml?direction=outbound&require_valid=true
Content-Type: application/xml
x-api-key: <your-api-key>

1
2
3

POST /api/v2/documents/upload/model?direction=outbound&require_valid=true
Content-Type: application/json
x-api-key: <your-api-key>

Keep the returned document id.

Example France CIUS UBL (test)

Use this body for POST /api/v2/documents/upload/xml?direction=outbound&require_valid=true in the xTool test environment, then POST .../send with { "transaction_type": "send.france" }.

Before upload:

1. Replace seller SIREN 256685928 with the Active France configuration SIREN you send from (QAS number from your Chorus Pro dataset — see Test Environment).
2. Replace buyer SIREN 346628948 with another QAS company that is also registered / Active as receiver (second France configuration, or a counterparty in QAS).
3. Align EndpointID, PartyLegalEntity/CompanyID, and VAT CompanyID (FR… + SIREN) with those numbers.
4. Use a unique cbc:ID for each send.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
    xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
    xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:peppol:france:billing:cius:1.0</cbc:CustomizationID>
    <cbc:ProfileID>S1</cbc:ProfileID>
    <cbc:ID>FA-2026-0001</cbc:ID>
    <cbc:IssueDate>2026-07-28</cbc:IssueDate>
    <cbc:DueDate>2026-08-28</cbc:DueDate>
    <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
    <cbc:Note>FA-2026-0001 - Test Company A, SIREN 256685928</cbc:Note>
    <cbc:Note>#PMT#Credit transfer</cbc:Note>
    <cbc:Note>#PMD#FA-2026-0001</cbc:Note>
    <cbc:Note>#AAB#Paiement a 30 jours par virement bancaire.</cbc:Note>
    <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
    <cbc:BuyerReference>TEST-BUYER-B</cbc:BuyerReference>
    <cac:AccountingSupplierParty>
        <cac:Party>
            <cbc:EndpointID schemeID="0225">256685928</cbc:EndpointID>
            <cac:PartyName>
                <cbc:Name>Test Company A</cbc:Name>
            </cac:PartyName>
            <cac:PostalAddress>
                <cbc:StreetName>1 Rue de Test</cbc:StreetName>
                <cbc:CityName>Paris</cbc:CityName>
                <cbc:PostalZone>75001</cbc:PostalZone>
                <cbc:CountrySubentity>Ile-de-France</cbc:CountrySubentity>
                <cac:Country>
                    <cbc:IdentificationCode>FR</cbc:IdentificationCode>
                </cac:Country>
            </cac:PostalAddress>
            <cac:PartyTaxScheme>
                <cbc:CompanyID>FR16256685928</cbc:CompanyID>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:PartyTaxScheme>
            <cac:PartyLegalEntity>
                <cbc:RegistrationName>Test Company A</cbc:RegistrationName>
                <cbc:CompanyID schemeID="0002">256685928</cbc:CompanyID>
            </cac:PartyLegalEntity>
            <cac:Contact>
                <cbc:ElectronicMail>company-a@example.test</cbc:ElectronicMail>
            </cac:Contact>
        </cac:Party>
    </cac:AccountingSupplierParty>
    <cac:AccountingCustomerParty>
        <cac:Party>
            <cbc:EndpointID schemeID="0225">346628948</cbc:EndpointID>
            <cac:PartyName>
                <cbc:Name>Test Company B</cbc:Name>
            </cac:PartyName>
            <cac:PostalAddress>
                <cbc:StreetName>2 Rue de Test</cbc:StreetName>
                <cbc:CityName>Lyon</cbc:CityName>
                <cbc:PostalZone>69001</cbc:PostalZone>
                <cbc:CountrySubentity>Auvergne-Rhone-Alpes</cbc:CountrySubentity>
                <cac:Country>
                    <cbc:IdentificationCode>FR</cbc:IdentificationCode>
                </cac:Country>
            </cac:PostalAddress>
            <cac:PartyTaxScheme>
                <cbc:CompanyID>FR05346628948</cbc:CompanyID>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:PartyTaxScheme>
            <cac:PartyLegalEntity>
                <cbc:RegistrationName>Test Company B</cbc:RegistrationName>
                <cbc:CompanyID schemeID="0002">346628948</cbc:CompanyID>
            </cac:PartyLegalEntity>
            <cac:Contact>
                <cbc:ElectronicMail>account-b@example.test</cbc:ElectronicMail>
            </cac:Contact>
        </cac:Party>
    </cac:AccountingCustomerParty>
    <cac:Delivery>
        <cbc:ActualDeliveryDate>2026-07-29</cbc:ActualDeliveryDate>
    </cac:Delivery>
    <cac:PaymentMeans>
        <cbc:PaymentMeansCode name="Credit transfer">30</cbc:PaymentMeansCode>
        <cbc:PaymentID>FA-2026-0001</cbc:PaymentID>
        <cac:PayeeFinancialAccount>
            <cbc:ID>FR7630006000011234567890189</cbc:ID>
            <cbc:Name>Test Company A</cbc:Name>
            <cac:FinancialInstitutionBranch>
                <cbc:ID>AGRIFRPP</cbc:ID>
            </cac:FinancialInstitutionBranch>
        </cac:PayeeFinancialAccount>
    </cac:PaymentMeans>
    <cac:PaymentTerms>
        <cbc:Note>Paiement a 30 jours par virement bancaire.</cbc:Note>
    </cac:PaymentTerms>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="EUR">260.00</cbc:TaxAmount>
        <cac:TaxSubtotal>
            <cbc:TaxableAmount currencyID="EUR">1300.00</cbc:TaxableAmount>
            <cbc:TaxAmount currencyID="EUR">260.00</cbc:TaxAmount>
            <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>20.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:TaxCategory>
        </cac:TaxSubtotal>
    </cac:TaxTotal>
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="EUR">1300.00</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="EUR">1300.00</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="EUR">1560.00</cbc:TaxInclusiveAmount>
        <cbc:PayableAmount currencyID="EUR">1560.00</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
    <cac:InvoiceLine>
        <cbc:ID>1</cbc:ID>
        <cbc:InvoicedQuantity unitCode="DAY">7.0</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">700.00</cbc:LineExtensionAmount>
        <cac:Item>
            <cbc:Description>Architecture review services</cbc:Description>
            <cbc:Name>Architecture review</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>20.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="EUR">100.0</cbc:PriceAmount>
        </cac:Price>
    </cac:InvoiceLine>
    <cac:InvoiceLine>
        <cbc:ID>2</cbc:ID>
        <cbc:InvoicedQuantity unitCode="DAY">3.0</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">600.00</cbc:LineExtensionAmount>
        <cac:Item>
            <cbc:Description>API integration services</cbc:Description>
            <cbc:Name>API integration</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>20.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="EUR">200.0</cbc:PriceAmount>
        </cac:Price>
    </cac:InvoiceLine>
</Invoice>

Detected / expected format: france_cius.invoice.1_0.xml_ubl.en16931.

Step A — Upload

Upload CIUS XML or a JSON model (see formats above).

Step B — Send

1
2
3

POST /api/v2/documents/{document_id}/send
Content-Type: application/json
x-api-key: <your-api-key>

1

{ "transaction_type": "send.france" }

Store transaction.id.

Step C — Poll the transaction

Recommended poll:

1

GET /api/v2/transactions/{transaction_id}?include=events&include=status_log

Also useful:

Suggested polling:

• Interval: 5–30 seconds while transaction status is processing
• Stop when the transaction reaches completed or failed
• Persist last seen Transaction Event ids so you only process new events
• When you need payloads, download Transaction Event Files by files[].id

Typical outbound Transaction Events

Exact timing depends on scenario (domestic vs cross-border) and provider processing. Some tax-report events may appear later.

Step D — Optional payment

1

POST /api/v2/payments

Allocate to the document id (not the transaction id). For outbound invoices, POST /api/v2/transactions/{transaction_id}/actions with { "type": "france.invoice.payment_received" } creates the same kind of payment for that transaction's document; the matching france.invoice.payment_received event usually appears after channel notification (on B2B domestic, CDV 212). For inbound invoices, use france.invoice.payment_sent to mark payment as transmitted without creating a Payment (on B2B domestic, CDV 211).

Inbound integration pattern

Inbound documents are created by xTool when the channel delivers them. Your job is to discover, store, and respond.

Discovery

1
2
3

GET /api/v2/documents?direction=inbound
GET /api/v2/transactions?transaction_type=receive.france
GET /api/v2/transactions?document_id={document_id}

Pattern:

1. Poll inbound documents and/or receive.france transactions on a schedule
2. Deduplicate by document id
3. Fetch content once, then drive ERP posting

Read content

1
2
3

GET /api/v2/documents/{document_id}?include=model&include=status_log
GET /api/v2/documents/{document_id}/xml
GET /api/v2/documents/{document_id}/model

Optional:

1

POST /api/v2/documents/{document_id}/ack

1

{ "ack": true }

Inspect receive transaction

1

GET /api/v2/transactions/{transaction_id}?include=events&include=actions&include=status_log

Transaction Event france.invoice.receive typically carries the inbound invoice as Transaction Event Files. Download them via /api/v2/transaction-event-files/{id}/download.

Buyer response (Transaction Actions)

Only on receive.france:

1

POST /api/v2/transactions/{transaction_id}/actions

1

{ "type": "france.invoice.approve" }

1
2
3
4
5

{
  "type": "france.invoice.refuse",
  "reason": "Incorrect amount",
  "reason_code": null
}

Other buyer lifecycle actions: france.invoice.acknowledge, france.invoice.partially_approve, france.invoice.dispute.

Then poll Transaction Events until the matching lifecycle event appears (for example france.invoice.approved or france.invoice.refused) on both receiver and sender sides as the network propagates. Also check the Transaction Action status (processing → completed / failed).

Payments API (France-relevant rules)

Rules of thumb:

• currency is required on create (use EUR for typical France domestic flows)
• Allocations target document_id + amount
• PATCH amount does not rewrite allocations unless you also send allocations
• Partial payments are normal: multiple payments over time for one invoice

Tax reports API

Read-only:

1
2

GET /api/v2/tax-reports
GET /api/v2/tax-reports/{tax_report_id}

Reports list sources (document, payment, …). You do not create tax reports via API; they appear from France processing (sometimes delayed for aggregated / cross-border scenarios).

Endpoint map

Documents

Transactions / Transaction Events / Transaction Actions / Transaction Event Files

There is no get-by-id for a single Transaction Action.

Payments / tax reports

See tables above.

Error handling

Always log transaction_id, document_id, Transaction Event types, and Transaction Action ids for support.

Recommended implementation checklist

1. Web setup — Active France configuration(s); note SIREN/SIRET used as seller/buyer
2. Auth — API key with France send (+ read) rights
3. Outbound worker — upload → send.france → poll Transaction / Transaction Events / Event Files → optional Payment
4. Inbound worker — poll inbound / receive.france → fetch document XML/model and/or Transaction Event Files → ERP → Transaction Actions (approve / refuse / …) → optional Payment
5. Reporting — periodically GET /api/v2/tax-reports and reconcile sources to documents/payments
6. Idempotency — store external invoice number ↔ xTool document id; ignore duplicate inbound ids
7. Observability — persist Transaction Event timeline (and action outcomes) per document for audits

For copy-paste HTTP examples of each step, use Send and receive invoices.