Migration von v1 auf v2

Der gesamte Funktionsumfang der ersten API-Version ist in der zweiten verfügbar. v2 übernimmt die Möglichkeiten von v1 und ergänzt sie um neue Methoden, ein einheitliches Formatmodell und einheitliche Codes. Im Folgenden: Was sich geändert hat und wie Sie Ihre Anbindung migrieren.

Wesentliche Änderungen:

API-Methoden — Pfade und Bezeichnungen der Endpoints haben sich geändert. Ersetzen Sie v1-Aufrufe durch die entsprechenden v2-Methoden (siehe Mapping-Tabelle unten).
Formatkonzept und JSON-Modell — In v2 wurde das Formatkonzept eingeführt: ein einheitliches Basisdokumentmodell und Formatcodes. Struktur und Feldnamen im JSON (Dokumentmodell) weichen von v1 ab — siehe Mapping der Felder und Gruppen.
Formatcodes, Dokument- und Transaktionsstatus — In v2 werden andere Codes für Dokumentformate, Dokumentstatus und (bei Transaktionen) Typen und Status verwendet. Ersetzen Sie beim Migrieren die alten Werte durch die neuen (siehe Mapping-Tabellen).

Siehe auch Versionsrichtlinie und API-Referenz.

1. API-Methoden-Mapping (v1 → v2)

In der Tabelle sind die v1-Methoden und die zugehörigen v2-Methoden aufgeführt. Alle v2-Pfade haben das Präfix /api/v2/.

In v1 bildeten Utility Services (Konvertierung, Validierung und PDF ohne Speicherung) eine eigene Gruppe. Alle diese Methoden sind in v2 unter Format API und PDF API verfügbar (siehe Tabelle „Utility Services (v1)“ unten).

Dokumente

v1 (Methode und Pfad)	v2 (Methode und Pfad)
`GET /api/v1/documents` — Dokumentenliste	`GET /api/v2/documents` — Liste mit Filtern, Sortierung, Paginierung
`POST /api/v1/documents/upload/xml` — XML hochladen	`POST /api/v2/documents/upload/xml` — XML hochladen
`POST /api/v1/documents/upload/json` — JSON (Modell) hochladen	`POST /api/v2/documents/upload/model` — Modell hochladen (neues JSON, siehe Abschnitt 2)
`GET /api/v1/documents/{id}/xml` — XML-Inhalt	`GET /api/v2/documents/{document_id}/xml`
`GET /api/v1/documents/{id}/json` — JSON-Inhalt (Modell)	`GET /api/v2/documents/{document_id}/model` — v2-Modell (andere Feldstruktur)
`GET /api/v1/documents/{id}/status` — aktueller Status	Enthalten in `GET /api/v2/documents/{document_id}` (Dokumentdetails)
`GET /api/v1/documents/{id}/status-log` — Statusverlauf	Enthalten in `GET /api/v2/documents/{document_id}` mit `include=status_log`
`PUT /api/v1/documents/{id}/send-peppol` — per Peppol senden	`POST /api/v2/documents/{document_id}/send` mit Body `transaction_type: "send.peppol"`
`POST /api/v1/documents/upload-and-send-peppol/xml`	Upload per `POST /api/v2/documents/upload/xml`, danach `POST /api/v2/documents/{id}/send`
`POST /api/v1/documents/upload-and-send-peppol/json`	Upload per `POST /api/v2/documents/upload/model`, danach `POST /api/v2/documents/{id}/send`

Konvertierung/Validierung (Invoice → Format API)

v1 (Methode und Pfad)	v2 (Methode und Pfad)
`POST /api/v1/invoice/convert/json-to-xml` — Modell → XML	`POST /api/v2/format/transform/model-to-xml` (Format im Body; Formatcodes siehe Abschnitt 3)
`POST /api/v1/invoice/convert/xml-to-json` — XML → Modell	`POST /api/v2/format/transform/xml-to-model` (Format aus XML erkannt oder angegeben)
Validierung bei convert mit `validate=true`	`POST /api/v2/format/validate/model` oder `POST /api/v2/format/validate/xml`

PDF

v1 (Methode und Pfad)	v2 (Methode und Pfad)
`POST /api/v1/pdf/create-zugferd` — XML in PDF einbetten (ZUGFeRD)	Format API nutzen: Modell → PDF oder XML → PDF (Factur-X/ZUGFeRD-Format) oder Dokument hochladen und PDF abrufen
`POST /api/v1/pdf/merge` — PDFs zusammenführen	`POST /api/v2/pdf/merge`

Utility Services (v1) — vollständiges Mapping

Alle Methoden von V1 Utility Services (Konvertierung, Validierung, PDF) sind in v2 über Format API und PDF API verfügbar:

v1 (V1 Utility Services)	v2 (Gruppe und Methode)
`POST /api/v1/invoice/convert/json-to-xml`	Format API: `POST /api/v2/format/transform/model-to-xml`
`POST /api/v1/invoice/convert/xml-to-json`	Format API: `POST /api/v2/format/transform/xml-to-model`
`POST /api/v1/invoice/convert/json-to-zugferd`	Format API: `POST /api/v2/format/transform/model-to-pdf` (Factur-X/ZUGFeRD-Format, siehe Abschnitt 3)
`POST /api/v1/invoice/convert/xml-to-zugferd`	Format API: `POST /api/v2/format/transform/xml-to-pdf` (Factur-X/ZUGFeRD)
`POST /api/v1/invoice/convert/xml-to-idoc`	Format API: `POST /api/v2/format/convert/xml/{target_format}` (target: `sap.invoice.idoc`)
`POST /api/v1/invoice/convert/idoc-to-xml`	Format API: `POST /api/v2/format/convert/model/{target_format}` (IDOC → Ziel-XML-Format; siehe API-Referenz zu unterstützten Formaten)
`POST /api/v1/invoice/validate/json`	Format API: `POST /api/v2/format/validate/model`
`POST /api/v1/invoice/validate/xml`	Format API: `POST /api/v2/format/validate/xml`
`POST /api/v1/pdf/create-zugferd`	Format API: `POST /api/v2/format/transform/xml-to-pdf` oder `model-to-pdf` mit Factur-X/ZUGFeRD-Format
`POST /api/v1/pdf/merge`	PDF API: `POST /api/v2/pdf/merge`

2. Formatkonzept und JSON-Feld-Mapping (Dokumentmodell)

In v2 wurde ein einheitliches Formatkonzept eingeführt: Basisdokumentmodell (xtool base), Formatcodes und transform/validate/convert-Operationen. Das JSON-Dokumentmodell in v2 weicht von v1 ab: Feldnamen und Gruppenstruktur haben sich geändert. Unten eine einheitliche Mapping-Tabelle: verschachtelte Felder per Punkt, Array-Elemente per [i] (z. B. notes[i].note_text, items[i].seller_id).

v1 (Feld/Pfad)	v2 (Feld/Pfad)
`invoice`	zusammengeführt in `document` (und References-Vererbung)
`invoice.invoice_number`	`document.number`
`invoice.payment_terms`	`document.terms`
`invoice.buyer_reference`	`document.customer_reference`
`company`	`supplier`
`company.address_line`	`supplier.address_line_1`
`company.address_line2`	`supplier.address_line_2`
`company.address_line3`	`supplier.address_line_3`
`company.party_id`	`supplier.ids[i].value`
`company.party_scheme`	`supplier.ids[i].scheme`
`company.party_ids`	`supplier.ids`
`company.party_endpoint_id`	`supplier.endpoint_id.value`
`company.party_endpoint_scheme`	`supplier.endpoint_id.scheme`
`company.legal_registration_id`	`supplier.legal_registration_id.value`
`company.legal_registration_scheme`	`supplier.legal_registration_id.scheme`
`company.party_tax_id`	`supplier.tax_id.value`
`company.party_tax_scheme`	`supplier.tax_id.scheme`
`customer.address_line`	`customer.address_line_1`
`customer.address_line2`	`customer.address_line_2`
`customer.address_line3`	`customer.address_line_3`
`customer.party_id`	`customer.id.value`
`customer.party_scheme`	`customer.id.scheme`
`customer.party_endpoint_id`	`customer.endpoint_id.value`
`customer.party_endpoint_scheme`	`customer.endpoint_id.scheme`
`customer.legal_registration_id`	`customer.legal_registration_id.value`
`customer.legal_registration_scheme`	`customer.legal_registration_id.scheme`
`delivery.party_name`	`delivery.name`
`delivery.party_id`	`delivery.id.value`
`delivery.party_scheme`	`delivery.id.scheme`
`delivery.delivery_date`	`delivery.date`
`delivery.address_line`	`delivery.address_line_1`
`delivery.address_line2`	`delivery.address_line_2`
`delivery.address_line3`	`delivery.address_line_3`
`tax_agent`	`tax_representative`
`payee.party_id`	`payee.id.value`
`payee.party_scheme`	`payee.id.scheme`
`payee.legal_registration_id`	`payee.legal_registration_id.value`
`payee.legal_registration_scheme`	`payee.legal_registration_id.scheme`
`totals.invoice_item_subtotal`	`totals.item_subtotal`
`totals.invoice_subtotal`	`totals.subtotal`
`totals.invoice_total`	`totals.total`
`totals.invoice_discount`	`totals.discount`
`totals.invoice_charge`	`totals.charge`
`totals.invoice_paid`	`totals.paid`
`totals.invoice_round`	`totals.round`
`totals.invoice_balance`	`totals.payable`
`totals.invoice_tax_total`	`totals.tax_total`
`taxes[i].tax_amount`	`taxes[i].amount`
`taxes[i].tax_percent`	`taxes[i].percent`
`taxes[i].tax_code`	`taxes[i].code`
`taxes[i].tax_scheme`	`taxes[i].scheme`
`taxes[i].tax_currency_code`	`taxes[i].currency_code`
`taxes[i].tax_exemption_reason`	`taxes[i].exemption_reason`
`taxes[i].tax_exemption_reason_code`	`taxes[i].exemption_reason_code`
`notes[i].note_text`	`notes[i].text`
`notes[i].note_subject_code`	`notes[i].subject_code`
`additional_documents[i].document_id`	`additional_documents[i].id.value`
`additional_documents[i].document_scheme`	`additional_documents[i].id.scheme`
`additional_documents[i].document_uri`	`additional_documents[i].uri`
`additional_documents[i].document_code`	`additional_documents[i].type_code`
`additional_documents[i].document_description`	`additional_documents[i].description`
`additional_documents[i].document_filename`	`additional_documents[i].filename`
`additional_documents[i].document_mime_code`	`additional_documents[i].mime_code`
`additional_documents[i].document_content`	`additional_documents[i].content`
`preceding_invoices`	`preceding_documents`
`preceding_invoices[i].invoice_number`	`preceding_documents[i].number`
`preceding_invoices[i].invoice_date`	`preceding_documents[i].issue_date`
`bank_details`	`payment_details`
`bank_details[i].payment_method_code`	`payment_details[i].method_code`
`bank_details[i].payment_method_name`	`payment_details[i].method_name`
`bank_details[i].payment_id`	`payment_details[i].remittance_information`
`bank_details[i].payment_mandate_id`	`payment_details[i].direct_debit_mandate_id`
`bank_details[i].payer_financial_account`	`payment_details[i].direct_debit_payer_account`
`items[i].seller_id`	`items[i].supplier_item_id`
`items[i].buyer_id`	`items[i].customer_item_id`
`items[i].standard_id`	`items[i].standard_item_id.value`
`items[i].standard_scheme`	`items[i].standard_item_id.scheme`
`items[i].base_quantity`	`items[i].price_quantity`
`items[i].base_unit_code`	`items[i].price_unit_code`
`items[i].gross_price` / `gross_diff` / `gross_diff_sign`	`items[i].price_discount_charge` (Objekt: sign, base_amount, amount)
`items[i].document_reference`	`items[i].document_reference.id.value`
`items[i].document_reference_scheme`	`items[i].document_reference.id.scheme`
`items[i].document_reference_code`	`items[i].document_reference.type_code`
`items[i].invoice_period_start`	`items[i].period_start_date`
`items[i].invoice_period_end`	`items[i].period_end_date`
`items[i].item_discounts_and_charges`	`items[i].discounts_charges`
`items[i].sub_items[j].*` (entsprechende Felder)	`items[i].sub_items[j].*` — dieselben Umbenennungen (supplier_item_id, document_reference.id, period_start_date, discounts_charges usw.)

Vollständige Beschreibung des v2-Modells und Beispiele: Formate, Modellverständnis und Basis-Modellbeispiel.

3. Dokumentformat-Codes und Status

Dokumentformat-Codes (v1 → v2)

In v1 wurden für den Parameter format / file_format Werte wie xrechnung_3_ubl, peppol_bis_3_ubl usw. verwendet. In v2 gelten Codes aus einer einheitlichen Formatliste im Stil quelle.typ.version.darstellung[.variante].

v1 (file_format / legacy)	v2 (format code)
`xrechnung_3_ubl`	`xrechnung.invoice.3_0.xml_ubl`
`xrechnung_3_ubl_extension`	`xrechnung.invoice.3_0.xml_ubl.extension`
`xrechnung_3_ubl_credit_note`	`xrechnung.credit_note.3_0.xml_ubl`
`xrechnung_3_cii`	`xrechnung.invoice.3_0.xml_cii`
`peppol_bis_3_ubl`	`peppol_bis_billing.invoice.3_0.xml_ubl`
`peppol_bis_3_ubl_credit_note`	`peppol_bis_billing.credit_note.3_0.xml_ubl`

Die vollständige v2-Formatliste finden Sie in der Formate-Dokumentation und in der API (z. B. unterstützte Formate für transform/convert).

Dokumentstatus (v1 → v2)

In v1 wurden in Antworten Status-Strings wie uploaded, sending_peppol_success, receiving_peppol_error usw. verwendet. In v2 sind die Status vereinheitlicht: upload.completed, send.completed, receive.failed usw.

v1 (legacy document status)	v2 (document status)
`uploaded`	`upload.completed`
`uploading_error`	`upload.failed`
`receiving_peppol`	`receive.processing`
`receiving_peppol_success`	`receive.completed`
`receiving_peppol_error`	`receive.failed`
`sending_email`	`send.processing`
`sending_email_sending`	`send.processing`
`sending_email_success`	`send.completed`
`sending_email_error`	`send.failed`
`sending_peppol`	`send.processing`
`sending_peppol_preparing`	`send.processing`
`sending_peppol_sending`	`send.processing`
`sending_peppol_result_processing`	`send.processing`
`sending_peppol_post_processing`	`send.processing`
`sending_peppol_success`	`send.completed`
`sending_peppol_error`	`send.failed`
`sevdesk_exporting`	`import.processing`

Authentifizierung

Unverändert: API-Key im Header x-api-key. Der Key muss Berechtigungen (api_methods) für die genutzten v2-Methoden haben. Siehe API-Keys und Logs.

Schrittweise Migration (Empfehlung)

Neuen API-Key mit Berechtigungen für die benötigten v2-Methoden anlegen (documents, format, transactions, organisations, auth, peppol lookup, pdf nach Bedarf).
v1-Aufrufe durch v2 ersetzen: Dokumentenliste → GET /api/v2/documents; XML-Upload → POST /api/v2/documents/upload/xml; JSON-Upload → Modell an v2 anpassen (siehe Abschnitt 2) und POST /api/v2/documents/upload/model nutzen; Dokument/Modell/XML/Status abrufen → entsprechende v2-GETs; Peppol-Versand → POST /api/v2/documents/{id}/send mit transaction_type: "send.peppol". Statt POST /api/v1/invoice/convert/json-to-xml und xml-to-json → POST /api/v2/format/transform/model-to-xml und xml-to-model (Formatcodes siehe Abschnitt 3); Validierung → POST /api/v2/format/validate/model oder validate/xml. PDF-Zusammenführung → POST /api/v2/pdf/merge; ZUGFeRD-Erstellung → über Format API (model-to-pdf / xml-to-pdf) mit dem passenden Format.
Im Code alte Format- und Statuscodes durch die neuen ersetzen (Tabellen in Abschnitt 2 und 3).
Integration in einer Testumgebung prüfen, danach Produktivverkehr auf v2 umstellen. Siehe Einrichtung und Peppol (Testnetz).

Zuerst testen

Integration zuerst gegen die Testumgebung ausführen, bevor Produktion auf v2 umgestellt wird.

Hilfe

Endpoint-Details: API-Referenz.
Fragen und Probleme: Support.