Transaktionen

Eine Transaktion ist eine Sende- oder Empfangsoperation für ein Dokument über einen einzelnen Kanal. Sie wird erstellt, wenn Sie einen Versand auslösen oder wenn ein Dokument empfangen wird.

Nutzen Sie Transaktionen, um diesen Zustellversuch nachzuverfolgen: in Bearbeitung, abgeschlossen oder fehlgeschlagen. Ein Dokument kann mehrere Transaktionen haben (erster Versand, erneuter Versand, Empfang auf einem anderen Kanal usw.).

Siehe auch Dokumentenmodell und Status-Lebenszyklus.

Transaktionstypen

Typen kombinieren Richtung (Senden / Empfangen) und Kanal:

Typ	Wann erstellt	Kanal
`send.email`	Sie senden das Dokument per E-Mail	E-Mail
`receive.email`	Dokument per E-Mail empfangen	E-Mail
`send.peppol`	Sie senden über Peppol	Peppol
`receive.peppol`	Dokument über Peppol empfangen	Peppol
`send.ksef`	Sie senden über KSeF	KSeF
`receive.ksef`	Dokument über KSeF empfangen	KSeF
`send.france`	Sie senden über den Frankreich-Kanal	Frankreich
`receive.france`	Dokument über den Frankreich-Kanal empfangen	Frankreich

Details zu Senden/Empfangen in Frankreich: Rechnungen senden und empfangen.

Lebenszyklus einer Transaktion

Jede Transaktion hat einen Status (z. B. initial → processing → completed oder failed). Der Dokumentenstatus folgt in der Regel diesem Schritt (z. B. send.processing, dann send.completed oder send.failed). Siehe Status-Lebenszyklus.

Events und Actions

Transaktionen können mehr als nur einen Status bereitstellen:

Konzept	Bedeutung	Wer legt es an
Event	Etwas, das bereits geschehen ist (gesendet, empfangen, akzeptiert, …)	xTool / Kanal
Action	Etwas, das Sie xTool ausführen lassen (z. B. eingehende Frankreich-Rechnung genehmigen oder ablehnen)	Sie (API / Web)

Events sind Historie. Actions sind Befehle. Erfolgreiche Actions erzeugen später typischerweise passende Events.

Käufer-Actions für Frankreich heute:

Action-Typ	Body	Typisches Folge-Event
`france.invoice.acknowledge`	`{ "type": "france.invoice.acknowledge" }`	`france.invoice.acknowledged`
`france.invoice.approve`	`{ "type": "france.invoice.approve" }`	`france.invoice.approved`
`france.invoice.partially_approve`	`{ "type": "...", "amount": "...", "reason": "..." }`	`france.invoice.partially_approved`
`france.invoice.dispute`	`{ "type": "france.invoice.dispute", "reason": "..." }`	`france.invoice.disputed`
`france.invoice.refuse`	`{ "type": "france.invoice.refuse", "reason": "..." }`	`france.invoice.refused`
`france.invoice.payment_sent`	`{ "type": "france.invoice.payment_sent" }` (`receive.france`)	`france.invoice.payment_sent`
`france.invoice.payment_received`	`{ "type": "...", "amount"?: "...", "currency"?: "...", "paid_at"?: "..." }` (`send.france`)	Erstellt eine Zahlung; Event `france.invoice.payment_received`

Metadaten

Bei Frankreich-Transaktionen (send.france / receive.france) kann die API client-sichere Metadaten bereitstellen, z. B.:

{
  "invoice_state": "..."
}

Interne Provider-Kennungen werden in der öffentlichen API-Antwort nicht zurückgegeben.

API-Übersicht

Methode	Pfad	Hinweise
`GET`	`/api/v2/transactions`	Liste. Filter nach `document_id`, `transaction_type`, `transaction_status`
`GET`	`/api/v2/transactions/{transaction_id}`	Einzelabruf. Optional `include=status_log`, `events`, `actions`
`GET`	`/api/v2/transactions/{transaction_id}/events`	Events auflisten (inkl. Event-Dateien)
`GET`	`/api/v2/transaction-events/{transaction_event_id}`	Ein Event abrufen (inkl. Dateien)
`GET`	`/api/v2/transaction-event-files/{transaction_event_file_id}/download`	Event-Datei herunterladen
`GET`	`/api/v2/transactions/{transaction_id}/actions`	Actions auflisten
`POST`	`/api/v2/transactions/{transaction_id}/actions`	Action anlegen

include=events beim Transaktionsabruf lädt auch verschachtelte Event-Dateien.

Es gibt keinen Endpunkt zum Abruf einer einzelnen Action per ID. Nutzen Sie die Actions-Liste oder include=actions beim Transaktionsabruf.

Beispiel — Transaktion mit verschachtelten Daten:

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

Beispiel — Transaktionen für ein Dokument:

1	`GET /api/v2/transactions?document_id={document_id}`

Bezug zum Dokumentenstatus

Der Dokumentenstatus spiegelt den letzten Schritt im Dokumentlebenszyklus wider. Um eine konkrete Sende- oder Empfangsoperation zu prüfen, öffnen Sie diese Transaktion (bei Bedarf mit status_log / events).

Wo Sie Transaktionen einsehen können

Web — Nutzung → Transaktionen (Filter nach Status, Typ, Datum). Siehe Nutzung.
API — Endpunkte in der Tabelle oben.