Rechnungen senden und empfangen

Sobald Ihre Frankreich-Konfiguration in der xTool-Web-App den Status Active hat, können Sie Rechnungen über die API austauschen.

Alle Beispiele unten nutzen die öffentliche API (Header x-api-key). Die Frankreich-Konfiguration selbst wird nur in der Web-UI verwaltet — es gibt keinen Endpunkt /api/v2/france/....

Womit Sie arbeiten

Actions ≠ Events. Sie erzeugen Actions. xTool speichert Events als Historie.

Voraussetzungen

1. Status der Frankreich-Konfiguration ist Active (Web-UI → Channels → France).
2. Zum Senden von Rechnungen darf die Konfiguration nicht nur Empfang sein (annuaire_only).
3. API-Schlüssel mit Berechtigung zum Versand über Frankreich.

Unterstützte Formate für den Frankreich-Kanal:

Rechnung senden (Outbound)

1. Dokument hochladen

Option A — XML

1
2
3

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

Body: rohes France-CIUS-XML (oder anderes unterstütztes Format). Vollständiges Testbeispiel: API-Integration — Beispiel France CIUS UBL.

Option B — JSON-Modell

1
2
3

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

1
2
3
4
5
6
7
8
9

{
  "format": "xtool.invoice.1_0",
  "document": { "id": "FA-2026-0019", "issue_date": "2026-08-10" },
  "supplier": { "...": "..." },
  "customer": { "...": "..." },
  "items": [],
  "taxes": [],
  "totals": { "...": "..." }
}

Für France-CIUS-Modelle setzen Sie "format": "france_cius.invoice.1_0.xml_ubl.en16931" und geben Sie die erforderlichen Frankreich-Felder an (z. B. document.profile_id).

Die Antwort enthält die Dokument-id. Behalten Sie sie für den nächsten Schritt.

2. Über Frankreich senden

1
2
3

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

1
2
3

{
  "transaction_type": "send.france"
}

Die Antwort enthält die angelegte Transaktion (id, type, status).

Typische Prüfungen auf der Sendeseite, wenn etwas fehlschlägt:

• Frankreich-Konfiguration ist Active und hat ein Provider-Konto
• Dokument ist gültig
• Format unterstützt den Frankreich-Kanal
• Rechnungsregeln (z. B. Währung EUR, Länge der Rechnungsnummer, Käufer-PIN wo erforderlich)

3. Transaktion verfolgen

1
2

GET /api/v2/transactions/{transaction_id}?include=events&include=status_log
x-api-key: <your-api-key>

Oder nur Events auflisten:

1

GET /api/v2/transactions/{transaction_id}/events

Eine an ein Event angehängte Datei herunterladen:

1

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

Ein einzelnes Event abrufen:

1

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

Häufige Event-Typen auf der Sendeseite:

Diese Events können Sie nicht selbst anlegen — sie erscheinen im Lauf des Prozesses.

Rechnung empfangen (Inbound)

Eingehende Rechnungen werden von xTool angelegt, wenn der Frankreich-Kanal sie liefert. Ihre Integration findet und verarbeitet sie.

1. Eingehende Dokumente finden

1
2

GET /api/v2/documents?direction=inbound
x-api-key: <your-api-key>

Oder Frankreich-Empfangs-Transaktionen finden (optional nach Dokument filtern):

1
2

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

2. Rechnung 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

Optionale Bestätigung:

1

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

1

{ "ack": true }

3. Empfangs-Transaktion prüfen

1

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

Der Empfangs-Transaktionstyp ist receive.france. Das Event france.invoice.receive trägt typischerweise die eingehenden Rechnungsdateien.

Genehmigen, ablehnen, anfechten oder Zahlung erfassen

Käufer-Lifecycle-Actions (acknowledge / approve / partially_approve / dispute / refuse / payment_sent) sind nur bei receive.france verfügbar.

Wo unten CDV-Codes stehen, gelten sie für den B2B-Inland-Lifecycle (CDAR). B2C und B2B grenzüberschreitend nutzen dieselben xTool-Actions/Events, erzeugen diese CDV-Codes aber möglicherweise nicht.

Zahlung gesendet (france.invoice.payment_sent, receive.france) markiert die Zahlung im Kanal als übermittelt. Es wird kein Payment-Entity erstellt.

Zahlung empfangen (france.invoice.payment_received, send.france) erstellt eine Zahlung mit Zuordnung zum Transaktionsdokument (wie POST /api/v2/payments mit einer Allocation). Betrag und Währung kommen standardmäßig aus dem zahlbaren Dokumentbetrag; optional können amount, currency und paid_at übergeben werden.

1
2
3

POST /api/v2/transactions/{transaction_id}/actions
Content-Type: application/json
x-api-key: <your-api-key>

Zur Kenntnis nehmen (CDV 204, B2B Inland)

1
2
3

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

Genehmigen (CDV 205, B2B Inland)

1
2
3

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

Teilweise genehmigen (CDV 206, B2B Inland — amount und reason Pflicht; amount_code optional, Default MAPTTC)

1
2
3
4
5
6

{
  "type": "france.invoice.partially_approve",
  "amount": "500.00",
  "reason": "Partial delivery accepted",
  "amount_code": "MAPTTC"
}

Anfechten (CDV 207, B2B Inland)

1
2
3
4

{
  "type": "france.invoice.dispute",
  "reason": "Incorrect line items"
}

Ablehnen (reason ist Pflicht; reason_code ist optional)

1
2
3
4
5

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

Zahlung gesendet (nur receive.france — CDV 211, B2B Inland)

1
2
3

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

Zahlung empfangen (nur send.france — CDV 212, B2B Inland)

1
2
3

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

Optionale Überschreibungen für Zahlung empfangen:

1
2
3
4
5
6

{
  "type": "france.invoice.payment_received",
  "amount": "1000.00",
  "currency": "EUR",
  "paid_at": "2026-08-14T12:00:00Z"
}

Vorhandene Actions auflisten:

1

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

Bei Erfolg für Käufer-Lifecycle-Actions speichert xTool ein passendes Event (z. B. france.invoice.approved oder france.invoice.refused). Versuchen Sie nicht, diese Events über die API anzulegen.

Zahlung erfassen

Zahlungen sind eigene Entitäten. Ordnen Sie sie dem Rechnungsdokument zu, damit xTool den Zahlungsstatus an den Frankreich-Provider synchronisieren kann, wenn für dieses Dokument eine Transaktion send.france existiert.

Als Shortcut können Sie auch die Action france.invoice.payment_received oben verwenden; sie erstellt eine Zahlung für ein ausgehendes Rechnungsdokument.

1
2
3

POST /api/v2/payments
Content-Type: application/json
x-api-key: <your-api-key>

Beispiel Teilzahlung:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "direction": "incoming",
  "amount": "300.00",
  "currency": "EUR",
  "paid_at": "2026-08-09T00:00:00Z",
  "allocations": [
    {
      "document_id": "invoice-document-uuid",
      "amount": "300.00"
    }
  ]
}

Spätere Zahlung für den Rest:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "direction": "incoming",
  "amount": "700.00",
  "currency": "EUR",
  "paid_at": "2026-08-15T00:00:00Z",
  "allocations": [
    {
      "document_id": "invoice-document-uuid",
      "amount": "700.00"
    }
  ]
}

Weitere Zahlungs-Endpunkte:

Nach Erfassung des Zahlungseingangs bei einer ausgehenden Rechnung erwarten Sie Event france.invoice.payment_received auf der zugehörigen Transaktion. Mehr dazu: Zahlungen.

Steuerberichte

Steuerberichte werden von xTool aus der Frankreich-Verarbeitung erzeugt. Die API ist für Clients nur lesend:

1
2

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

Jeder Bericht kann Quellen auflisten (document, payment, …).

Wie die Meldung zu Szenarien passt:

Mehr dazu: Steuerberichte.

Kurzreferenz

Outbound-Checkliste

1. Frankreich-Konfiguration Active (Web-UI)
2. POST /api/v2/documents/upload/xml oder /upload/model
3. POST /api/v2/documents/{id}/send mit { "transaction_type": "send.france" }
4. GET /api/v2/transactions/{tx_id}?include=events pollen
5. Optional: POST /api/v2/payments mit Zuordnungen

Inbound-Checkliste

1. GET /api/v2/documents?direction=inbound und/oder GET /api/v2/transactions?transaction_type=receive.france
2. XML / Modell abrufen; optional ack
3. POST /api/v2/transactions/{tx_id}/actions — genehmigen, ablehnen oder andere Käufer-Lifecycle-Actions
4. Optional: Zahlungen und Tax-Report-GETs

Nützliche Includes

1

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

include=events lädt auch Event-Dateien an verschachtelten Events.

Ausführlicher Integratoren-Leitfaden (Auth, Account-Matching, Polling, Endpunkt-Übersicht): API-Integration.