Migration from v1 to v2

All first-version API functionality is available in the second. v2 preserves v1 capabilities and adds new methods, a unified format model, and consistent codes. Below is what changed and how to migrate your integration.

Main changes:

API methods — Endpoint paths and names have changed. Replace v1 calls with the corresponding v2 methods (see the mapping table below).
Format concept and JSON model — v2 introduces the format concept: a single base document model and format codes. The structure and field names in the JSON (document model) differ from v1 — see the field and group mapping.
Format codes, document and transaction statuses — v2 uses different codes for document formats, document statuses, and (for transactions) types and statuses. Replace old values with new ones when migrating (see the mapping tables).

See also Versioning policy and API reference.

1. API method mapping (v1 → v2)

The table lists v1 methods and their v2 counterparts. All v2 paths use the prefix /api/v2/.

In v1, Utility Services (conversion, validation, and PDF operations without persisting data) were a separate group. All these methods are available in v2 under Format API and PDF API (see the "Utility Services (v1)" table below).

Documents

v1 (method and path)	v2 (method and path)
`GET /api/v1/documents` — list documents	`GET /api/v2/documents` — list with filters, sort, pagination
`POST /api/v1/documents/upload/xml` — upload XML	`POST /api/v2/documents/upload/xml` — upload XML
`POST /api/v1/documents/upload/json` — upload JSON (model)	`POST /api/v2/documents/upload/model` — upload model (new JSON, see section 2)
`GET /api/v1/documents/{id}/xml` — XML content	`GET /api/v2/documents/{document_id}/xml`
`GET /api/v1/documents/{id}/json` — JSON content (model)	`GET /api/v2/documents/{document_id}/model` — v2 model (different field structure)
`GET /api/v1/documents/{id}/status` — current status	Included in `GET /api/v2/documents/{document_id}` (document details)
`GET /api/v1/documents/{id}/status-log` — status log	Included in `GET /api/v2/documents/{document_id}` with `include=status_log`
`PUT /api/v1/documents/{id}/send-peppol` — send via Peppol	`POST /api/v2/documents/{document_id}/send` with body `transaction_type: "send.peppol"`
`POST /api/v1/documents/upload-and-send-peppol/xml`	Upload via `POST /api/v2/documents/upload/xml`, then `POST /api/v2/documents/{id}/send`
`POST /api/v1/documents/upload-and-send-peppol/json`	Upload via `POST /api/v2/documents/upload/model`, then `POST /api/v2/documents/{id}/send`

Conversion/validation (Invoice → Format API)

v1 (method and path)	v2 (method and path)
`POST /api/v1/invoice/convert/json-to-xml` — model → XML	`POST /api/v2/format/transform/model-to-xml` (format in body; format codes see section 3)
`POST /api/v1/invoice/convert/xml-to-json` — XML → model	`POST /api/v2/format/transform/xml-to-model` (format detected from XML or provided)
Validation when convert with `validate=true`	`POST /api/v2/format/validate/model` or `POST /api/v2/format/validate/xml`

PDF

v1 (method and path)	v2 (method and path)
`POST /api/v1/pdf/create-zugferd` — embed XML in PDF (ZUGFeRD)	Use Format API: model → PDF or XML → PDF (Factur-X/ZUGFeRD format), or upload document and get PDF
`POST /api/v1/pdf/merge` — merge PDFs	`POST /api/v2/pdf/merge`

Utility Services (v1) — full mapping

All V1 Utility Services methods (conversion, validation, PDF) are available in v2 via Format API and PDF API:

v1 (V1 Utility Services)	v2 (group and method)
`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, see section 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 → target XML format; see API reference for supported formats)
`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` or `model-to-pdf` with Factur-X/ZUGFeRD format
`POST /api/v1/pdf/merge`	PDF API: `POST /api/v2/pdf/merge`

2. Format concept and JSON field mapping (document model)

v2 introduces a unified format concept: base document model (xtool base), format codes, and transform/validate/convert operations. The JSON document model in v2 differs from v1: field names and group structure have changed. Below is a single mapping table: nested fields use dot notation, array elements use [i] (e.g. notes[i].note_text, items[i].seller_id).

v1 (field/path)	v2 (field/path)
`invoice`	merged into `document` (and References inheritance)
`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` (object: 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].*` (same fields)	`items[i].sub_items[j].*` — same renames (supplier_item_id, document_reference.id, period_start_date, discounts_charges, etc.)

For the full v2 model and examples, see Formats, Model understanding, and Base model example.

3. Document format codes and statuses

Document format codes (v1 → v2)

In v1, the format / file_format parameter used values like xrechnung_3_ubl, peppol_bis_3_ubl, etc. In v2, codes follow a single format list in the style source.type.version.representation[.variant].

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`

For the full v2 format list, see the formats documentation and the API (e.g. supported formats for transform/convert).

Document statuses (v1 → v2)

In v1, responses used string statuses like uploaded, sending_peppol_success, receiving_peppol_error, etc. In v2, statuses are unified: upload.completed, send.completed, receive.failed, etc.

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`

Authentication

Same as before: API key in the x-api-key header. The key must have permissions (api_methods) for the v2 methods you use. See API keys and permissions.

Step-by-step migration (recommendation)

Create a new API key with permissions for the v2 methods you need (documents, format, transactions, organisations, auth, peppol lookup, pdf as needed).
Replace v1 calls with v2: document list → GET /api/v2/documents; upload XML → POST /api/v2/documents/upload/xml; upload JSON → adapt the model to v2 (see section 2) and use POST /api/v2/documents/upload/model; get document/model/XML/status → corresponding v2 GETs; send via Peppol → POST /api/v2/documents/{id}/send with transaction_type: "send.peppol". Instead of POST /api/v1/invoice/convert/json-to-xml and xml-to-json use POST /api/v2/format/transform/model-to-xml and xml-to-model (format codes see section 3); validation → POST /api/v2/format/validate/model or validate/xml. PDF merge → POST /api/v2/pdf/merge; ZUGFeRD creation → via Format API (model-to-pdf / xml-to-pdf) with the appropriate format.
In your code, replace old format and status codes with the new ones (tables in sections 2 and 3).
Test the integration in a test environment, then switch production traffic to v2. See Setup and Peppol (test network).

!!! tip "Test first" Run your integration against the test environment before switching production to v2.

Help

Endpoint details: API reference.
Questions and issues: Support.