Migrationsleitfaden v2025-01-01 → v2025-10-13

Dieser Leitfaden hilft Ihnen bei der Aktualisierung von X-B2B-API-Version: 2025-01-01 auf X-B2B-API-Version: 2025-10-13. 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 v2025-10-13.

Ihre Integration aktualisieren

1. Basis-URL aktualisieren: Ändern Sie Ihre API-Basis-URL von app.b2brouter.net oder app-staging.b2brouter.net zu api.b2brouter.net bzw. api-staging.b2brouter.net.

2. Versions-Header hinzufügen: Fügen Sie den Header X-B2B-API-Version: 2025-10-13 in allen Anfragen ein, oder konfigurieren Sie die Standardversion in den API-Schlüssel-Einstellungen Ihrer Gruppe.

3. Formaterweiterungen entfernen: Entfernen Sie .json- oder .xml-Erweiterungen aus allen Endpunkt-Pfaden. Alle Antworten sind standardmäßig JSON.

4. Pfadsegmente aktualisieren:

• Ersetzen Sie /projects/ durch /accounts/ in allen Pfaden
• Ersetzen Sie /clients/ durch /contacts/ in allen Pfaden
• Entfernen Sie das Präfix /users/ aus Codelisten-Endpunkten
• Entfernen Sie das Präfix /api/v1/ aus Verzeichnis- und Steuerbericht-Endpunkten

5. Paginierungsverarbeitung aktualisieren: Aktualisieren Sie Ihren Code, um Paginierungsdaten aus dem meta-Objekt statt aus Root-Level-Eigenschaften zu lesen:

Alt (v2025-01-01)

const totalCount = response.total_count;
const offset = response.offset;
const limit = response.limit;

Neu (v2025-10-13)

const totalCount = response.meta.total_count;
const offset = response.meta.offset;
const limit = response.meta.limit;

6. Eigenschaftsnamen aktualisieren: Ersetzen Sie alle Verweise auf client durch contact in Ihrem Code zur Verarbeitung von Anfragen und Antworten:

Alt (v2025-01-01)

// Anfrage-Body
{
  "invoice": {
    "client_id": 123,
    "client": {
      "name": "Client Name",
      "taxcode": "9920:ESD29766391"
    }
  }
}

// Antwort-Body
{
  "invoice": {
    "id": 123,
    "client": { ... }
  }
}

Neu (v2025-10-13)

// Anfrage-Body
{
  "invoice": {
    "contact_id": 123,
    "contact": {
      "name": "Contact Name",
      "tin_scheme": "9920",
      "tin_value": "ESD29766391"
    }
  }
}

// Antwort-Body
{
  "invoice": {
    "id": 123,
    "contact": { ... }
  }
}

7. Rechnungslisten konsolidieren: Ersetzen Sie separate Endpunkte zur Rechnungsauflistung durch den konsolidierten Endpunkt /accounts/{account}/invoices mit dem Parameter type:

• Für empfangene Rechnungen: GET /accounts/{account}/invoices?type=ReceivedInvoice
• Für Selbstrechnungen: GET /accounts/{account}/invoices?type=IssuedSelfInvoice
• Für vereinfachte Rechnungen: GET /accounts/{account}/invoices?type=IssuedSimplifiedInvoice

8. Steuerberichte aktualisieren: Ersetzen Sie alte veraltete Steuerbericht-Endpunkte durch die neuen konsolidierten Endpunkte unter /accounts/{account}/tax_reports und /tax_reports/{id}. Weitere Details finden Sie in der neuen Steuerbericht-API.

9. Vollständige Antworten verarbeiten: Aktualisieren Sie Ihren Code, um vollständige Ressourcendarstellungen zu verarbeiten, die von PUT-, DELETE- und POST-Operationen zurückgegeben werden, anstatt leerer 204-Antworten.

10. XML-Unterstützung entfernen: Wenn Ihre Integration auf XML-Antworten basierte, konvertieren Sie Ihren Code auf die ausschließliche Verarbeitung von JSON-Antworten.

11. Veraltete Rechnungsattribute aktualisieren: Ersetzen Sie veraltete Rechnungsattribute durch ihre standardisierten Alternativen:

Alt (v2025-01-01)

{
  "invoice": {
    "contact_person": "John Doe",
    "state": "accepted",
    "customer_party_identification": "12345",
    "accounting_cost": "DEPT-001",
    "iban": "ES6000000000000000000000",
    "bic": "ABCDESMMXXX",
    "num_contracte": "CONTRACT-2024",
    "organ_gestor": "ORG-001",
    "oficina_comptable": "OFF-001"
  }
}

Neu (v2025-10-13)

{
  "invoice": {
    "customer_contact_person": "John Doe",
    // state entfernt - stattdessen POST /invoices/{id}/mark_as verwenden
    "contact": {
      "party_identification": "12345"
    },
    "buyer_accounting_reference": "DEPT-001",
    "bank_account": {
      "iban": "ES6000000000000000000000",
      "bic": "ABCDESMMXXX"
    },
    "contract_number": "CONTRACT-2024",
    "managing_unit": "ORG-001",
    "accounting_unit": "OFF-001"
  }
}

12. Kontakt-/Client-Attribute aktualisieren: Ersetzen Sie veraltete Kontaktattribute durch ihre standardisierten Alternativen:

Alt (v2025-01-01)

{
  "contact": {
    "old_channel": "peppol",
    "taxcode": "9920:ESD29766391",
    "contact": "John Doe",
    "bank_account": "ES6000000000000000000000",
    "company_identifier": "A12345678",
    "transport_type": "peppol",
    "document_type": "xml.ubl.invoice.bis3",
    "posta_elettronica_certificata": "pec@example.it",
    "codice_destinatario": "ABC1234"
  }
}

Neu (v2025-10-13)

{
  "contact": {
    "transport_type_code": "peppol",
    "tin_scheme": "9920",
    "tin_value": "ESD29766391",
    "contact_person": "John Doe",
    "bank_account_number": "ES6000000000000000000000",
    "cin_value": "A12345678",
    "document_type_code": "xml.ubl.invoice.bis3",
    "certified_email": "pec@example.it",
    "recipient_code": "ABC1234"
  }
}

13. Routing-Codes aktualisieren: Routing-Code-Felder (cin1_value, cin1_scheme, …, cin5_value, cin5_scheme) werden nicht mehr als Top-Level-Kontaktattribute akzeptiert. Sie müssen innerhalb eines routing_codes-Wrappers gesendet werden:

Alt (v2025-01-01)

{
  "contact": {
    "name": "Ajuntament de Girona",
    "cin1_value": "L01170792",
    "cin1_scheme": "8014",
    "cin2_value": "L01170792",
    "cin2_scheme": "8014",
    "cin3_value": "L01170792",
    "cin3_scheme": "8014"
  }
}

Neu (v2025-10-13)

{
  "contact": {
    "name": "Ajuntament de Girona",
    "routing_codes": {
      "cin1_value": "L01170792",
      "cin1_scheme": "8014",
      "cin2_value": "L01170792",
      "cin2_scheme": "8014",
      "cin3_value": "L01170792",
      "cin3_scheme": "8014"
    }
  }
}

In Antworten werden Routing-Codes ebenfalls innerhalb des routing_codes-Objekts zurückgegeben.

14. Rechnungsstatusänderungen aktualisieren: Ersetzen Sie direkte state-Attribut-Aktualisierungen durch den mark_as-Endpunkt:

Alt (v2025-01-01)

PUT /invoices/{id}.json
{
  "invoice": {
    "state": "accepted"
  }
}

Neu (v2025-10-13)

POST /invoices/{id}/mark_as
{
  "state": "accepted"
}

Ihre Migration testen

Wir empfehlen, Ihre Integration in der Staging-Umgebung (api-staging.b2brouter.net) gründlich zu testen, bevor Sie in die Produktion wechseln. Der Header X-B2B-API-Version ermöglicht es Ihnen, die neue Version zu testen, ohne Ihre aktuelle Integration zu beeinflussen.