API-Nutzung

Es gibt zwei gültige Integrationsmuster. In der Praxis ist Option 1 meist einfacher: Sie validieren und beheben Konvertierungsprobleme bevor ein Dokument angelegt wird, und im Dokumentenbestand liegt nur UBL.

Allgemeine Rahmenbedingungen

Platzhalter in den Beispielen

Format-Kennungen

• IDoc-Eingabe (Dokumentation / Erkennung): sap.invoice.idoc
• Ziel-UBL (Pfadsegment target_format): peppol_bis_billing.invoice.3_0.xml_ubl

API-Zugang prüfen

Prüfen Sie, ob der Schlüssel gültig ist:

1
2

curl -X GET "https://xtool.invoice-portal.de/api/v2/auth/me" \
  -H "x-api-key: <api_key>"

Option 1 (empfohlen): konvertieren → hochladen → senden → Status abfragen

Ablauf: IDoc → Peppol BIS UBL (eigenständige Konvertierung), dann UBL hochladen, Versand mit send.peppol, Status des Dokuments abfragen.

Schritt 1 — IDoc nach Peppol BIS Billing UBL konvertieren

Endpunkt: POST /v2/format/convert/xml/{target_format}

Für Peppol BIS Billing Invoice 3.0 UBL setzen Sie target_format auf peppol_bis_billing.invoice.3_0.xml_ubl. Senden Sie den Roh-IDoc-XML-Text als Request-Body. Optionaler Query validate=true validiert die Ausgabe.

1
2
3
4
5

curl -X POST "https://xtool.invoice-portal.de/api/v2/format/convert/xml/peppol_bis_billing.invoice.3_0.xml_ubl?validate=true" \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/xml" \
  --data-binary "@idoc.xml" \
  -o converted.xml

Erfolg: HTTP 200, Antworttext ist XML (application/xml) im Zielformat.

Schritt 2 — Konvertiertes UBL als Dokument hochladen

Endpunkt: POST /v2/documents/upload/xml?direction=outbound

1
2
3
4

curl -X POST "https://xtool.invoice-portal.de/api/v2/documents/upload/xml?direction=outbound" \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/xml" \
  --data-binary "@converted.xml"

Speichern Sie aus der JSON-Antwort die Dokument-ID als DOCUMENT_ID.

Schritt 3 — Dokument über Peppol senden

Endpunkt: POST /v2/documents/{document_id}/send

Transaktionstyp send.peppol:

1
2
3
4

curl -X POST "https://xtool.invoice-portal.de/api/v2/documents/<DOCUMENT_ID>/send" \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"transaction_type": "send.peppol"}'

Die Antwort enthält ein Transaktions-Objekt (u. a. id, type, status).

Schritt 4 — Dokumentstatus abfragen

Endpunkt: GET /v2/documents/{document_id}?include=status_log

1
2

curl -X GET "https://xtool.invoice-portal.de/api/v2/documents/<DOCUMENT_ID>?include=status_log" \
  -H "x-api-key: <api_key>"

Wiederholen Sie die Anfrage, bis das Dokument einen Endstatus erreicht (Erfolg oder Fehler). Nutzen Sie status_log zur Fehlersuche.

Option 2: IDoc hochladen → konvertieren → Dokument aktualisieren → senden → Status abfragen

Nutzen Sie dies, wenn zuerst ein Dokumentdatensatz existieren soll (z. B. Nachvollziehbarkeit mit Original-IDoc), dessen XML Sie vor dem Versand durch das konvertierte UBL ersetzen.

Schritt 1 — IDoc-XML als Dokument hochladen

Endpunkt: POST /v2/documents/upload/xml?direction=outbound

1
2
3
4

curl -X POST "https://xtool.invoice-portal.de/api/v2/documents/upload/xml?direction=outbound" \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/xml" \
  --data-binary "@idoc.xml"

Speichern Sie die zurückgegebene ID als DOCUMENT_ID.

Schritt 2 — IDoc nach Peppol BIS Billing UBL konvertieren

Gleicher Konvertierungsaufruf wie in Option 1, Schritt 1:

1
2
3
4
5

curl -X POST "https://xtool.invoice-portal.de/api/v2/format/convert/xml/peppol_bis_billing.invoice.3_0.xml_ubl?validate=true" \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/xml" \
  --data-binary "@idoc.xml" \
  -o converted.xml

Schritt 3 — Dokument mit konvertiertem XML aktualisieren

Endpunkt: PUT /v2/documents/{document_id}/update/xml

1
2
3
4

curl -X PUT "https://xtool.invoice-portal.de/api/v2/documents/<DOCUMENT_ID>/update/xml" \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/xml" \
  --data-binary "@converted.xml"

Schlägt die XML-Validierung fehl, kann die API mit 400 und validation_error (oder gleichwertiger Fehlerlast) antworten.

Schritt 4 — Über Peppol senden

Wie Option 1, Schritt 3.

Schritt 5 — Status abfragen

Wie Option 1, Schritt 4.

Wahl zwischen Option 1 und Option 2

Bei beiden Optionen status_log am Dokument beobachten, bis Versand und ggf. Peppol-Rückmeldungen abgeschlossen sind.