Migrationsleitfaden v2026-03-02 → v2026-04-20

Dieser Leitfaden hilft Ihnen bei der Aktualisierung von X-B2B-API-Version: 2026-03-02 auf X-B2B-API-Version: 2026-04-20. Er konzentriert sich auf das, was Sie ändern müssen, nicht nur darauf, was sich geändert hat.

Changelog Die vollständige Liste der Ergänzungen und Korrekturen finden Sie im Changelog von v2026-04-20.

Auf einen Blick

Was sich geändert hat	Müssen Sie handeln?
Gutschriften und Korrekturen verwenden eine neue invoice_references-Struktur	Ja — betrifft alle Integrationen, die korrektive Rechnungen erstellen oder lesen
payment_method_info aus Rechnungsantworten entfernt	Ja — entfernen Sie jeden Code, der dieses Feld liest
Tippfehler clasification_code_scheme in Rechnungspositionen-Antworten behoben	Ja — aktualisieren Sie den Feldnamen, wenn Sie ihn lesen
Neue Validierung beim Erstellen von Untergeordneten Kontakten (Zweigstellen)	Ja — nur wenn Sie tin_value bei Kontakten mit parent_id setzen
Neue Validierung beim Erstellen von Rechnungen mit einem Inline-Kontakt	Ja — stellen Sie sicher, dass tin_value oder cin_value immer enthalten ist
Neue Felder in Rechnungs-, Konto- und Peppol-Transport-Antworten	Nur wenn Ihr Code bei unerwarteten JSON-Feldern fehlschlägt
Peppol-Transport: pending_peppol_directory_publish ersetzt	Nur wenn Sie dieses Feld lesen
TIN-Verifizierungs-Endpunkt (neu)	Nein — Opt-in-Funktion
Neue Kontofelder (routing_codes, auto_remittance, etc.)	Nein — Opt-in
KSeF-Ergänzungen	Nein — nur relevant für polnische KSeF-Integrationen

---

Änderungen, die Handlungsbedarf erfordern

1. Gutschriften und Korrekturen: flache Felder durch invoice_references ersetzen

Dies ist die bedeutendste Änderung. Die einzelnen Korrekturfelder bei Rechnungen wurden durch ein einziges invoice_references-Array ersetzt. Wenn Ihre Integration korrektive Rechnungen (Gutschriften, Korrekturen) erstellt oder liest, müssen Sie sowohl Ihre Anfragen als auch Ihre Antwortverarbeitung aktualisieren.

Die folgenden Felder werden nicht mehr gesendet oder zurückgegeben:

Entferntes Feld	Ersetzt durch invoice_references[].
amended_number	number
amended_date	date
amended_invoicing_period_start	invoicing_period_start (nur senden, nicht zurückgegeben)
amended_invoicing_period_end	invoicing_period_end (nur senden, nicht zurückgegeben)
amend_reason	reason
amend_code_tax	tax_correction_code
correction_method	correction_method

Jeder Eintrag in invoice_references erfordert einen reference_type. Verwenden Sie "amend" für korrektive Rechnungen, die auf eine Originalrechnung verweisen.

Ihre Anfrage aktualisieren (Erstellen/Aktualisieren):

Vorher (v2026-03-02)

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "amended_number": "INV-2026-042",
    "amended_date": "2026-02-10",
    "amend_reason": "Price correction"
  }
}

Nachher (v2026-04-20)

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "invoice_references": [
      {
        "reference_type": "amend",
        "number": "INV-2026-042",
        "date": "2026-02-10",
        "reason": "Price correction"
      }
    ]
  }
}

Ihre Antwortverarbeitung aktualisieren (Lesen):

Vorher (v2026-03-02)

const originalNumber = invoice.amended_number;
const reason = invoice.amend_reason;

Nachher (v2026-04-20)

const ref = invoice.invoice_references.find(
  (r) => r.reference_type === "amend",
);
const originalNumber = ref?.number;
const reason = ref?.reason;

Betroffene Endpunkte: GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

2. payment_method_info aus Rechnungsantworten entfernt

Das Feld payment_method_info wird nicht mehr zurückgegeben. Es enthielt eine menschenlesbare, HTML-formatierte Zahlungszusammenfassung — wenn Sie es verwendet haben, wechseln Sie zu den strukturierten Feldern, die bereits in der Antwort vorhanden sind: payment_method, contact_iban, contact_bic, etc.

Betroffene Endpunkte: GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

3. Tippfehler-Korrektur im Rechnungspositions-Feldnamen: clasification_code_scheme → classification_code_scheme

Das Feld war in allen vorherigen Versionen falsch geschrieben. Die Antwort gibt nun die korrekte Schreibweise zurück. Wenn Ihr Code clasification_code_scheme (mit einem ‘s’) aus Rechnungspositions-Antworten liest, aktualisieren Sie es.

Hinweis: Das Senden der korrekten Schreibweise in Anfragen wurde bereits in allen Versionen akzeptiert — nur der Antwortschlüssel ändert sich.

Vorher (v2026-03-02)

{ "clasification_code_scheme": "..." }

Nachher (v2026-04-20)

{ "classification_code_scheme": "..." }

Betroffene Endpunkte: GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

4. Untergeordnete Kontakte (Zweigstellen): tin_value wird nun gegen den Elternkontakt validiert

Beim Erstellen oder Aktualisieren eines Kontakts, der zu einem Elternunternehmen gehört (mit parent_id), lehnt die API die Anfrage nun ab, wenn der angegebene tin_value nicht mit dem des Elternkontakts übereinstimmt. Zuvor wurde ein nicht übereinstimmender Wert stillschweigend ignoriert.

Der empfohlene Ansatz ist, tin_value beim Erstellen von Zweigstellen ganz wegzulassen — er wird automatisch vom Elternkontakt übernommen.

// Empfohlen (v2026-04-20) — eine Zweigstelle erstellen
{
  "contact": {
    "name": "Branch Office Madrid",
    "parent_id": 456
  }
}

Betroffene Endpunkte: POST /accounts/{account}/contacts, PATCH /contacts/{id}

---

5. Beim Erstellen einer Rechnung mit einem Inline-Kontakt ist nun ein Bezeichner erforderlich

Wenn Sie eine Rechnung erstellen und die Kontaktdaten inline übergeben (mit einem contact-Objekt statt einer contact_id), muss der Kontakt nun mindestens eines der Felder tin_value oder cin_value enthalten. Anfragen ohne eines der beiden werden mit 422 Unprocessable Entity abgelehnt.

Dies gilt nicht für vereinfachte Rechnungen (IssuedSimplifiedInvoice), die keinen identifizierten Kontakt erfordern.

// v2026-04-20 — tin_value oder cin_value ist erforderlich
{
  "invoice": {
    "contact": {
      "name": "Acme Corp",
      "tin_value": "B12345678",
      "tin_scheme": "9915"
    }
  }
}

Betroffene Endpunkte: POST /accounts/{account}/invoices

---

Neue Felder in bestehenden Antworten

Die folgenden Felder wurden zu bestehenden Antworten hinzugefügt. Sie sind rückwärtskompatibel — Ihre Integration funktioniert weiterhin ohne Änderungen. Wenn Ihr Code jedoch bei unerwarteten JSON-Feldern fehlschlägt, aktualisieren Sie Ihre Antwortmodelle, um diese zuzulassen.

Rechnungsantworten (GET /invoices/{id}, POST, PATCH):

• invoice_references — Array von Korrektur-/Vorauszahlungsreferenzen (siehe Abschnitt 1 oben)
• exchange_rate — der angewendete Wechselkurs, wenn die Rechnungswährung von der lokalen Steuerbehördenwährung abweicht
• exchange_date — das Datum des Wechselkurses
• order_date — Bestelldatum (ergänzt das bestehende ponumber-Feld)
• contact.cin_value, contact.cin_scheme — Unternehmensbezeichner des Rechnungskontakts

Kontoantworten (GET /accounts/{account}, GET /accounts):

• routing_codes — Objekt mit bis zu 5 zusätzlichen Unternehmensbezeichnern (cin1_value/cin1_scheme bis cin5_value/cin5_scheme)
• auto_remittance — Boolean
• skip_line_taxable_base_rounding — Boolean

Peppol-Transport-Antwort (GET /accounts/{account}/transports):

• sml_status — SML-Registrierungsstatus: "not_published", "processing" oder "published"
• peppol_directory_status — Peppol-Verzeichnis-Listungsstatus (ersetzt den alten booleschen Wert pending_peppol_directory_publish)
• reception_document_types — Liste der Dokumenttypen, die dieser Teilnehmer über Peppol empfangen kann
• standard_documents und pending_peppol_directory_publish werden nicht mehr zurückgegeben

---

Neue Funktionen in dieser Version

TIN-Verifizierung — überprüfen Sie, ob ein Unternehmensname und eine Steuernummer bei der Steuerbehörde registriert sind, bevor Sie eine Rechnung senden. Unterstützt derzeit Spanien (AEAT).

• POST /tin_verifications?country=es — eine Liste von bis zu 20.000 TIN+Name-Paaren zur Verifizierung einreichen; gibt 202 Accepted zurück, während die Verarbeitung im Hintergrund läuft
• GET /tin_verifications/{id} — die Ergebnisse abrufen, sobald die Verarbeitung abgeschlossen ist
• Abonnieren Sie das Webhook-Ereignis tin_verification.finished, um automatisch benachrichtigt zu werden

Neue Kontokonfigurationsfelder:

• routing_codes bei Konten — bis zu 5 zusätzliche Unternehmensbezeichner speichern, nützlich für Peppol-Routing
• auto_remittance — automatisch strukturierte OGM-Überweisungsreferenzen für belgische Rechnungen generieren
• skip_line_taxable_base_rounding — nützlich für Rechnungen mit vielen Positionen, bei denen sich kleine Rundungsunterschiede ansammeln; erfordert apply_taxes_per_line: true

KSeF (polnisches E-Invoicing)-Ergänzungen — wenn Ihre Integration polnische Rechnungen verarbeitet, fügt diese Version Unterstützung für Anzahlungsworkflows (ZAL, ROZ, KOR_ZAL, KOR_ROZ), kommunale und Umsatzsteuergruppen-Rechnungsstellungsszenarien sowie mehrere neue Steuerberichtsfelder hinzu. Die vollständige Liste finden Sie im Changelog.

---

Migrations-Checkliste

Verwenden Sie diese Checkliste, bevor Sie in der Produktion auf v2026-04-20 umstellen.

Korrektive Rechnungen (Gutschriften, Korrekturen):

• Ersetzen Sie die flachen Korrekturfelder (amended_number, amended_date, amend_reason, etc.) durch invoice_references in allen Anfragen zum Erstellen/Aktualisieren von Rechnungen
• Fügen Sie reference_type: "amend" bei jedem Eintrag hinzu
• Aktualisieren Sie die Antwortverarbeitung, um aus invoice_references statt aus den flachen Feldern zu lesen
• Test: Erstellen Sie eine Gutschrift, lesen Sie sie zurück und bestätigen Sie, dass das Array invoice_references vorhanden und korrekt ist

Rechnungsantwortfelder:

• Entfernen Sie jeden Code, der payment_method_info liest
• Aktualisieren Sie clasification_code_scheme → classification_code_scheme überall, wo Sie Rechnungspositions-Antworten lesen
• Bestätigen Sie, dass Ihre Antwortverarbeitung neue Felder akzeptiert: exchange_rate, exchange_date, order_date, contact.cin_value, contact.cin_scheme

Kontakte:

• Wenn Sie Kontakte mit parent_id erstellen, entfernen oder passen Sie tin_value an den Wert des Elternkontakts an
• Wenn Sie Rechnungen mit einem Inline-contact-Objekt erstellen, stellen Sie sicher, dass tin_value oder cin_value immer enthalten ist

Peppol-Transport:

• Aktualisieren Sie die Transport-Antwortverarbeitung: Ersetzen Sie pending_peppol_directory_publish durch peppol_directory_status und entfernen Sie standard_documents-Lesevorgänge
• Bestätigen Sie, dass Ihr Antwortmodell sml_status, peppol_directory_status und reception_document_types akzeptiert

Konten:

• Bestätigen Sie, dass Ihre Konto-Antwortverarbeitung die neuen Felder routing_codes, auto_remittance und skip_line_taxable_base_rounding akzeptiert

Ihre Integration testen

Wechseln Sie zunächst in Ihrer Sandbox- oder Staging-Umgebung zum neuen Versions-Header:

X-B2B-API-Version: 2026-04-20

Sie können diesen Header pro Anfrage setzen, sodass Sie gegen die Sandbox (oder das Staging) testen können, ohne Ihre Produktionskonfiguration zu berühren. Sobald Sie die obige Checkliste validiert haben, aktualisieren Sie die Version in Ihren Produktions-API-Schlüssel-Einstellungen oder Anfrage-Headern.