France API-Integration

Diese Seite richtet sich an Integratoren, die ein ERP oder Middleware über die öffentliche API (/api/v2/..., Header x-api-key) an xTool anbinden.

Die France-Konfiguration (Annuaire-/QAS-Registrierung, Unternehmenskennungen, Tax-Report-Modus) wird nur in der Web-UI verwaltet. Es gibt keinen öffentlichen Endpunkt /api/v2/france/.... Sobald die Konfiguration Active ist, laufen Rechnungsaustausch, Zahlungen und Tax-Report-Abrufe über die normalen Document-/Transaction-/Payment-APIs.

Verwandte Seiten:

• Praktische Request-Beispiele: Rechnungen senden und empfangen
• QAS-Setup: Testumgebung
• Konzepte: Transaktionen, Zahlungen, Steuerberichte
• OpenAPI: API Reference

Integrationsmodell

France-API-Arbeit basiert auf den normalen xTool-Entitäten. Verwenden Sie die genauen Namen unten — sie entsprechen den API-Ressourcen.

Objektmodell:

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

• Transaction-Typ: send.france oder receive.france
• Actions: Käufer-Lifecycle + payment_sent bei receive.france; payment_received bei send.france

Transaction Action ≠ Transaction Event.
Sie senden eine Transaction Action per POST. Bei Käufer-Lifecycle-Actions speichert xTool ein passendes Transaction Event (z. B. Action france.invoice.approve → Event france.invoice.approved). Action france.invoice.payment_sent (receive.france) markiert die Zahlung als übermittelt. Action france.invoice.payment_received (send.france) legt ein Payment mit Zuordnung zum Dokument an (wie POST /api/v2/payments). Bei B2B Inland entsprechen diese CDV-Lifecycle-Codes (siehe unten); bei B2C und B2B grenzüberschreitend gilt CDV möglicherweise nicht.

Siehe auch Transaktionen.

Transaction, Events, Actions und Files

Dieser Abschnitt beschreibt das zentrale Objektmodell für den France-Lebenszyklus.

Transaction

Eine Transaction ist ein Send- oder Empfangsversuch für ein Dokument auf einem Kanal.

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

Ein Dokument kann mehrere Transactions haben (Resend, Empfang, andere Kanäle). Folgen Sie immer der konkreten France-Transaction.

Transaction Event

Ein Transaction Event ist ein historischer Eintrag zu etwas, das auf dieser Transaction bereits geschehen ist. Clients legen Events nicht an.

1
2

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

include=events beim Transaction-Get lädt auch verschachtelte Event-Files.

France Transaction-Event-Typen

CDV-Codes (204–212) stammen aus dem Inland-B2B-Lifecycle (CDAR / AFNOR XP Z12-012). Sie gelten für B2B Inland. B2C und B2B grenzüberschreitend nutzen andere Meldewege und erzeugen diese CDV-Lifecycle-Codes möglicherweise nicht; xTool speichert trotzdem dieselben Transaction-Event-Typen, wenn der Kanal den entsprechenden Status meldet.

Der Zeitpunkt hängt vom Szenario (Inland vs. grenzüberschreitend) und der Provider-Verarbeitung ab. Nur neue Event-IDs verarbeiten.

Wenn der Kanal für B2B Inland eine Lifecycle-Notification (CDAR / ApplicationResponse) liefert, bevorzugt xTool den CDV-Code aus dem XML (ProcessConditionCode / ResponseCode) gegenüber dem Provider-state der Rechnung. So lassen sich z. B. volle Freigabe (205) und Teilfreigabe (206) unterscheiden.

Transaction Event File

Ein Transaction Event File ist eine gespeicherte Datei an einem Transaction Event (z. B. gesendetes/empfangenes Rechnungs-XML oder eine zugehörige Bestätigung).

Files erscheinen verschachtelt unter Events, wenn Sie Events listen/abrufen. Inhalt separat herunterladen:

1

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

Typischer Ablauf:

1. Transaction mit include=events pollen
2. Interessierendes Event finden (z. B. france.invoice.receive oder france.invoice.send)
3. files[].id / filename / content_type lesen
4. Benötigte Dateien per ID herunterladen

Es gibt kein Create/Update/Delete von Event Files über die öffentliche Client-API.

Transaction Action

Eine Transaction Action ist ein Befehl, den Sie xTool für eine bestehende Transaction ausführen lassen. France-Käufer-Actions gibt es heute nur auf receive.france.

1
2

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

Es gibt keinen Get-by-ID-Endpunkt für eine einzelne Action. Nutzen Sie die Liste oder include=actions beim Transaction-Get.

CDV-Codes → Actions (B2B Inland)

CDV-Codes gelten nur für B2B Inland (CDAR / AFNOR XP Z12-012). Bei B2C und B2B grenzüberschreitend gelten sie möglicherweise nicht. Codes ohne Action meldet nur der Kanal.

Frühere Kanalstatus wie 200 (Déposée), 202 (Reçue) und 203 (Mise à disposition) sind ebenfalls B2B-Inland-CDV-Codes; xTool stellt dafür keine Client-Actions bereit.

France Action-Typen → resultierende Events

Regeln:

• Dieselbe Lifecycle-Action zweimal für eine Transaction → Konflikt (409)
• Auf Action-status completed / failed und das passende Event warten
• Payment sent (receive.france) aktualisiert nur den Kanalstatus; es wird kein Payment erstellt
• Payment received (send.france) erstellt das Payment sofort und synchronisiert zum Provider

Authentifizierung und Organisationskontext

1

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

Der API-Schlüssel ist an eine Organisation gebunden. Alle sichtbaren Dokumente, Transaktionen, Zahlungen und Steuerberichte gehören zu dieser Organisation.

Checkliste:

1. API-Schlüssel in der Web-UI mit Berechtigung zum Versand über Frankreich anlegen (sowie Leserechte für Dokumente / Transaktionen / Zahlungen nach Bedarf).
2. /api/v2/... mit diesem Schlüssel aufrufen.
3. Sicherstellen, dass die Organisation mindestens eine Active France-Konfiguration hat (Web-UI → Channels → France).

France-Konfiguration und welcher Account sendet

Die France-Konfiguration wird nicht im Send-Request-Body gewählt. Bei send.france macht xTool Folgendes:

1. Organisation des Dokuments nehmen
2. Active France-Konfigurationen dieser Organisation laden (mit Provider-Account-ID)
3. Sender des Dokuments (metadata.sender_id, typischerweise Supplier-Endpoint / SIREN) mit siren / siret / cin_value der Konfiguration matchen
4. Ohne Treffer: Fallback auf die erste Active-Konfiguration mit Account

Praxisregeln:

• Verkäufer-Kennungen in der Rechnung so setzen, dass sie zur gewünschten Konfiguration passen
• Eine Organisation kann mehrere France-Konfigurationen haben (z. B. zwei QAS-Unternehmen für Send/Receive-Tests)
• Empfangs-only-Modus (annuaire_only) kann keine Rechnungen senden

Der Konfigurationslebenszyklus (NEW → … → DIRECTORY_PENDING / SCHEDULED → ACTIVE) läuft über Web + Hintergrundjobs. API-Austausch erfordert Active.

Formate

Bevorzugt für France-Kanal-Tests und produktionsnahe Abläufe:

France-CIUS-Modelle benötigen Frankreich-Felder wie document.profile_id (Billing-Modus, z. B. S1).

Inland-B2B-Versand erwartet typischerweise EUR, eine ausreichend kurze Rechnungsnummer und wo nötig eine französische Käufer-Routing-ID (PIN / Endpoint). Validierungsfehler treten vor oder während Prepare auf.

Upload-Optionen:

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>

Die zurückgegebene Dokument-id behalten.

Beispiel France CIUS UBL (Test)

Diesen Body für POST /api/v2/documents/upload/xml?direction=outbound&require_valid=true in der xTool-Testumgebung verwenden, danach POST .../send mit { "transaction_type": "send.france" }.

Vor dem Upload:

1. Verkäufer-SIREN 256685928 durch die SIREN Ihrer Active France-Konfiguration ersetzen (QAS-Nummer aus dem Chorus-Pro-Datensatz — siehe Testumgebung).
2. Käufer-SIREN 346628948 durch eine weitere QAS-Firma ersetzen, die ebenfalls als Empfänger registriert / Active ist (zweite France-Konfiguration oder Gegenpartei in QAS).
3. EndpointID, PartyLegalEntity/CompanyID und VAT-CompanyID (FR… + SIREN) an diese Nummern anpassen.
4. Für jeden Versand eine eindeutige cbc:ID verwenden.

  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>

Erkanntes / erwartetes Format: france_cius.invoice.1_0.xml_ubl.en16931.

Schritt A — Upload

CIUS-XML oder JSON-Modell hochladen (siehe Formate oben).

Schritt B — Senden

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

transaction.id speichern.

Schritt C — Transaktion pollen

Empfohlener Poll:

1

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

Weitere nützliche Calls:

Polling-Empfehlung:

• Intervall: 5–30 Sekunden, solange Transaction-status processing ist
• Stoppen, wenn die Transaction completed oder failed erreicht
• Zuletzt gesehene Transaction-Event-IDs speichern, nur neue Events verarbeiten
• Bei Bedarf Payloads über Transaction Event Files (files[].id) herunterladen

Typische Outbound-Transaction-Events

Der genaue Zeitpunkt hängt vom Szenario (Inland vs. grenzüberschreitend) und der Provider-Verarbeitung ab. Manche Tax-Report-Events erscheinen später.

Schritt D — Optionale Zahlung

1

POST /api/v2/payments

Zuordnung auf die Dokument-ID (nicht die Transaktions-ID). Für ausgehende Rechnungen erstellt POST /api/v2/transactions/{transaction_id}/actions mit { "type": "france.invoice.payment_received" } dieselbe Art Zahlung für das Dokument der Transaktion; das passende Event france.invoice.payment_received erscheint üblicherweise nach der Kanal-Notification (bei B2B Inland CDV 212). Für eingehende Rechnungen verwenden Sie france.invoice.payment_sent, um die Zahlung als übermittelt zu markieren, ohne ein Payment zu erstellen (bei B2B Inland CDV 211).

Inbound-Integrationsmuster

Eingehende Dokumente legt xTool an, wenn der Kanal sie liefert. Ihre Aufgabe: finden, speichern, reagieren.

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}

Muster:

1. Inbound-Dokumente und/oder receive.france-Transaktionen zeitgesteuert pollen
2. Nach Dokument-ID deduplizieren
3. Inhalt einmal abrufen, dann ERP-Buchung steuern

Inhalt lesen

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 }

Empfangs-Transaktion prüfen

1

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

Transaction Event france.invoice.receive trägt typischerweise die eingehende Rechnung als Transaction Event Files. Download über /api/v2/transaction-event-files/{id}/download.

Käuferantwort (Transaction Actions)

Nur bei 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
}

Weitere Käufer-Lifecycle-Actions: france.invoice.acknowledge, france.invoice.partially_approve, france.invoice.dispute.

Anschließend Transaction Events pollen, bis das passende Lifecycle-Event erscheint (z. B. france.invoice.approved oder france.invoice.refused) — auf Empfänger- und Senderseite, sobald das Netzwerk propagiert. Prüfen Sie auch den Transaction-Action-status (processing → completed / failed).

Payments-API (France-relevante Regeln)

Faustregeln:

• currency ist beim Anlegen Pflicht (für typische France-Inland-Flows EUR)
• Zuordnungen zielen auf document_id + amount
• PATCH des Betrags schreibt Zuordnungen nicht um, außer Sie senden auch allocations
• Teilzahlungen sind üblich: mehrere Zahlungen über die Zeit für eine Rechnung

Tax-Reports-API

Nur lesend:

1
2

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

Berichte listen Quellen (document, payment, …). Tax Reports legen Sie nicht per API an; sie entstehen aus der France-Verarbeitung (bei aggregierten / grenzüberschreitenden Szenarien ggf. verzögert).

Endpunkt-Übersicht

Documents

Transactions / Transaction Events / Transaction Actions / Transaction Event Files

Es gibt keinen Get-by-ID für eine einzelne Transaction Action.

Payments / Tax reports

Siehe Tabellen oben.

Fehlerbehandlung

Für Support immer transaction_id, document_id, Transaction-Event-types und Transaction-Action-IDs protokollieren.

Empfohlene Implementierungs-Checkliste

1. Web-Setup — Active France-Konfiguration(en); SIREN/SIRET als Verkäufer/Käufer notieren
2. Auth — API-Schlüssel mit France-Send- (+ Lese-)Rechten
3. Outbound-Worker — Upload → send.france → Transaction / Transaction Events / Event Files pollen → optional Payment
4. Inbound-Worker — Inbound / receive.france pollen → Document-XML/Modell und/oder Transaction Event Files → ERP → Transaction Actions (approve / refuse / …) → optional Payment
5. Reporting — periodisch GET /api/v2/tax-reports und Quellen mit Dokumenten/Zahlungen abgleichen
6. Idempotenz — externe Rechnungsnummer ↔ xTool-Dokument-ID speichern; doppelte Inbound-IDs ignorieren
7. Observability — Transaction-Event-Timeline (und Action-Ergebnisse) pro Dokument für Audits persistieren

Copy-Paste-HTTP-Beispiele zu jedem Schritt: Rechnungen senden und empfangen.