Finance API V1 und V2

Die Ironfang Finance API hat zwei Versionen, die nebeneinander laufen. V1 unter /finance/v1 bleibt unverändert: Seine Clients behalten ihre Peppol-Strukturen, und V1 liefert nie ein Ergebnis von V2. V2 unter /finance/v2 validiert mehr Familien und Formate und meldet genau, was geprüft wurde. Nichts muss umziehen: Eine Integration mit V1 funktioniert weiter, und V2 validiert jede Familie, Peppol eingeschlossen.

Welche API was abdeckt

GET /finance/v2/einvoices/rulesets listet genau auf, welche Familie, Variante, Syntax, welchen Dokumenttyp und Prüfumfang jedes aktive Release von V2 abdeckt; nichts anderes wird unterstützt. Mehr dazu in den Leitfäden der Familien: XRechnung und ZUGFeRD / Factur-X.

Anfragen

Beide Versionen nehmen das Dokument als Body der Anfrage an, mit der Auswahl über Query-Parameter, oder als multipart/form-data mit einem Teil document und einem optionalen Teil options, der dieselbe Auswahl als JSON enthält. Bei Multipart-Anfragen werden Query-Parameter nicht gelesen, und ein unbekannter oder wiederholter Parameter oder Teil ergibt in beiden 400 malformed_request.

Ergebnisse

Ein Ergebnis von V1 hat das Schema financewolf/einvoice/validation-result/v1, ein Ergebnis von V2 ironfang/finance/einvoice/validation-result/v2. Beide melden outcome valid oder invalid für eine abgeschlossene Validierung, allein nach den fatalen Befunden entschieden; alles, was ein Ergebnis verhindert hat, ist in beiden ein Problem mit outcome: indeterminate, und nichts wird berechnet. Die Felder, die sich unterscheiden:

operation_id, status, counts, findings_summary, timing und usage gibt es in beiden. counts zählt in V2 zusätzlich Befunde mit information.

Befunde

In beiden ist message eine der festen Meldungen von Ironfang: Die offiziellen Regeltexte werden nicht wiederholt, weil sie Rechnungswerte enthalten können. rule_id ist die offizielle Kennung, unverändert.

Gespeicherte Ergebnisse

GET /finance/v2/einvoices/results listet Validierungen und Erzeugungen über V1 und Validierungen über V2 gemeinsam auf, jeweils mit der API, über die sie entstanden sind (api_version), dem Schema ihres gespeicherten Dokuments (result_schema) und ihrer Familie, und kann nach jedem davon filtern. GET /finance/v2/einvoices/results/{id} liefert jedes davon in dem Schema, in dem es entstanden ist, und DELETE löscht beide Arten. Die eigene Liste von V1 zeigt nur Ergebnisse von V1, und das Lesen eines Ergebnisses von V2 über V1 ergibt 404: Ein Ergebnis von V2 ist kein Dokument, das das Schema von V1 beschreibt. Ergebnisse werden in beiden 30 Tage aufbewahrt.

Webhook-Events und Zustellungen

Ein abgeschlossener Vorgang reiht ein Event ein, das an jedes aktivierte Webhook- oder S3-Ziel zugestellt und auf dieselbe Weise signiert wird, gleich über welche API der Vorgang lief. Ein Vorgang über V1 sendet financewolf/einvoice/event/v1, dessen result_url unter /finance/v1 liegt. Ein Vorgang über V2 sendet ironfang/finance/einvoice/event/v2, dessen result_url unter /finance/v2 liegt und dessen data zusätzlich family, variant und scope des Ergebnisses enthält. Ein Empfänger, der beide annimmt, sollte nach schema unterscheiden.

GET /finance/v2/einvoices/deliveries listet Zustellungen beider Arten auf, jede mit ihrer api_version und ihrem Event, wie es eingereiht wurde, und kann nach api_version filtern. POST /finance/v2/einvoices/deliveries/{id}/retry wiederholt eine fehlgeschlagene Zustellung beider Arten. Liste, Abruf und Wiederholung von Zustellungen in V1 sehen nur Zustellungen von Events aus V1.

Jobs und Batches

POST /finance/v2/einvoices/jobs reiht eine Validierung über V2 ein und POST /finance/v2/einvoices/batches 1 bis 100 gemeinsam, alle oder keine. Jeder Job enthält document_base64, seinen media_type und die synchronen options. Ein Dokument, das die synchrone Validierung ablehnen würde, wird schon bei der Annahme mit demselben Problem abgelehnt, und nichts wird eingereiht oder berechnet. Ergebnis, Nutzung und Event eines Jobs sind genau die einer synchronen Validierung.

Jobs von V1 und V2 teilen sich die Warteschlange jeder Organisation: höchstens 100 nicht abgeschlossene Jobs und 25 MiB ihrer Dokumente, verschlüsselt aufbewahrt, bis sie abgeschlossen sind, höchstens 24 Stunden. Die Job- und Batch-Listen von V1 zeigen nur Arbeit aus V1; die von V2 zeigen beides.

Was beide gemeinsam haben

• API-Schlüssel der Ironfang-Plattform (Authorization: Bearer) mit denselben Berechtigungen: finance:einvoices:write zum Validieren, finance:einvoices:read zum Lesen.
• Anonyme Validierung ohne Schlüssel: Nichts wird gespeichert, und es gelten strengere Ratenbegrenzungen.
• Ein optionaler Idempotency-Key bei authentifizierten Anfragen: Derselbe Key und dieselbe Anfrage liefern das erste Ergebnis und werden nicht erneut berechnet. Die Keys von V2 gehören V2 allein, getrennt von denen von V1.
• Probleme nach RFC 9457 als application/problem+json; unterscheiden Sie nach code.
• Ein Finance-Kontingent: Eine abgeschlossene Validierung über eine der beiden APIs ist ein Vorgang.
• Hochgeladene Dokumente werden bei der synchronen Validierung nicht gespeichert.

Die Verträge: V1 und V2.

Beispiel

Eine Peppol-Rechnung über beide APIs, dann eine XRechnung und ein PDF nach ZUGFeRD / Factur-X, die nur V2 validiert.

# V1: a Peppol BIS Billing 3 invoice (UBL).
curl --fail-with-body --silent --show-error \
  "https://api.ironfang.uk/finance/v1/einvoices/validate?ruleset=latest&profile=peppol-bis-billing-3" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: peppol-invoice-0001" \
  --data-binary @peppol-invoice.xml

# V2: the same invoice. The same release runs on the same engine; the
# answer is the V2 result, with the family named instead of a profile.
curl --fail-with-body --silent --show-error \
  "https://api.ironfang.uk/finance/v2/einvoices/validate?ruleset=latest&family=peppol-bis-billing-3" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: peppol-invoice-0001-v2" \
  --data-binary @peppol-invoice.xml

# V2: an XRechnung invoice (UBL or CII). Only V2 validates XRechnung.
curl --fail-with-body --silent --show-error \
  "https://api.ironfang.uk/finance/v2/einvoices/validate?ruleset=latest&family=xrechnung" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: xrechnung-invoice-0001" \
  --data-binary @xrechnung-invoice.xml

# V2: a ZUGFeRD / Factur-X hybrid PDF. Only V2 takes a PDF.
curl --fail-with-body --silent --show-error \
  "https://api.ironfang.uk/finance/v2/einvoices/validate?family=zugferd-facturx" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @zugferd-invoice.pdf