E-invoice API E-invoice API: ZUGFeRD and XRechnung from JSON.

How it works

1. Your software sends POST /api/v1/einvoices with a bearer token (see Getting a bearer token) and the invoice as JSON.
2. The server checks the data, calculates missing totals and maps every value to the fields of its invoice form (by default the form zugferd).
3. The form is submitted through the normal form processing. It creates the EN 16931 XML (Cross Industry Invoice, ZUGFeRD / Factur-X profile EN 16931, written following the KoSIT rules used for XRechnung), embeds it into a PDF/A-3 and seals the PDF.
4. The PDF goes back to your software (as Base64 in JSON, or as the file itself with Accept: application/pdf) and, like the web form, by e-mail to the business owner of the form and to the e-mail addresses in the invoice (seller and buyer).

"action": "preview" stops after step 2: you receive the filled invoice form as PDF, nothing is sealed and no e-mail is sent. Use it to check a layout or your mapping.

Smallest request

Invoice number, seller, buyer and at least one line are required. The invoice date defaults to today, the currency to the form's preset (EUR on the sample form), and all totals are calculated.

curl -X POST https://forms.example.com/api/v1/einvoices \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Accept: application/pdf" \
  -o invoice.pdf -d '{
  "invoice": { "number": "2026-0042", "taxPercent": 19 },
  "seller":  { "name": "Example Supplies GmbH", "street": "Musterstrasse 1", "postCode": "10115", "town": "Berlin", "country": "DE", "vatId": "DE123456789" },
  "buyer":   { "name": "Example Hotel AG", "street": "Seestrasse 1", "postCode": "12345", "town": "Musterstadt", "country": "DE" },
  "items":   [ { "name": "Consulting (hours)", "quantity": 4, "netPrice": 120 } ]
}'

Complete example (XRechnung)

An invoice to a German public authority, with Leitweg-ID, contact data, delivery date and SEPA payment. Dates are ISO 8601 (yyyy-MM-dd; dd.MM.yyyy is accepted too), amounts are numbers with a dot as decimal separator.

{
  "action": "submit",
  "invoice": {
    "number": "2026-0042", "date": "2026-10-11", "currency": "EUR",
    "dueDate": "2026-10-25", "deliveryDate": "2026-10-09", "paymentTerms": "14 days net",
    "buyerReference": "04011000-12345-34", "buyerOrderReference": "PO-7781",
    "taxPercent": 19, "taxCategory": "S", "note": "Thank you for your order."
  },
  "seller": { "name": "Example Supplies GmbH", "contactName": "Erika Muster", "street": "Musterstrasse 1",
              "postCode": "10115", "town": "Berlin", "country": "DE", "phone": "+49 30 1234567",
              "email": "billing@example.com", "vatId": "DE123456789" },
  "buyer":  { "name": "City of Musterstadt", "contactName": "Max Beispiel", "street": "Rathausplatz 1",
              "postCode": "12345", "town": "Musterstadt", "country": "DE", "email": "invoices@example.org" },
  "payment": { "iban": "DE02120300000000202051", "bic": "BYLADEM1001", "accountName": "Example Supplies GmbH" },
  "items": [
    { "name": "Consulting (hours)", "quantity": 4, "netPrice": 120, "sellerAssignedId": "C-100" },
    { "name": "Travel flat rate", "netPrice": 80 }
  ]
}

Amounts, VAT and rounding

• Line amount = quantity × net price, rounded to 2 decimals (half away from zero), unless you send lineTotal.
• Sum of lines = sum of the line amounts; it is also the taxable amount and the total without VAT.
• VAT = sum of lines × taxPercent / 100, rounded to 2 decimals. Total = sum of lines + VAT; the amount due equals the total.
• Totals you send in totals win over the calculation, so you can pass the exact figures of your accounting system.
• One VAT rate applies to the whole invoice. For invoices with several VAT rates, send one invoice per rate or ask us about the ZUGFeRD Pro SDK.
• Numbers: 1234.5 or "1234.50". A comma is refused, so "12,50" can never become 1250.

VAT categories

• S standard rate (default). With a rate of 0 it becomes Z.
• Z zero rated goods.
• E exempt from VAT; without taxExemptionReason the reason "Steuerfreie Leistung" is used.
• AE reverse charge (exemption code VATEX-EU-AE); default reason "Steuerschuldnerschaft des Leistungsempfängers".
• G export outside the EU (VATEX-EU-G).

For E, AE and G the rate is set to 0.

Payment

With an iban the invoice carries a SEPA credit transfer (payment means code 58) with BIC and account name. Without an IBAN the payment means is "not defined" (code 1). Payment terms (paymentTerms) and due date (dueDate) are written in any case; without a due date the invoice date is used.

XRechnung checklist

Invoices to German public authorities must follow XRechnung. Send at least:

• invoice.buyerReference = the Leitweg-ID of the authority (without it the server writes a generated reference, which an authority will reject).
• seller.email and buyer.email (electronic addresses), seller.contactName, seller.phone.
• seller.vatId, complete addresses with country codes, invoice.dueDate or paymentTerms.
• Payment data (payment.iban) if the authority pays by transfer.

The XML is written following the KoSIT rules. Check your first invoices once with the KoSIT validator or a viewer of your choice.

The answer

201 Created with the submission ID, the PDF and the totals that were used:

HTTP/1.1 201 Created
{
  "submissionId": "7f3c2a9e0d5b4e1fa2c8b6d4e9f01a23",
  "formId": "zugferd",
  "action": "submit",
  "status": "submitted",
  "pdf": { "fileName": "zugferd.pdf", "contentType": "application/pdf", "size": 152331,
           "sha256": "…", "eInvoice": true, "data": "JVBERi0xLjc…" },
  "totals": { "lineTotal": 560.00, "taxTotal": 106.40, "grandTotal": 666.40, "currency": "EUR" },
  "notOnForm": [ "PaymentReference", "SellerAssignedID1", "SellerAssignedID2" ]
}

• pdf.eInvoice is true when the e-invoice XML is embedded in the PDF.
• notOnForm lists values the chosen form has no field for (they are not part of the invoice).
• With Accept: application/pdf (or "returnPdf": "binary") the answer is the PDF itself; the header X-Submission-Id carries the ID. "returnPdf": "none" leaves out the PDF data.
• "action": "preview" answers 200 with the filled, unsent invoice.

Using your own invoice form

By default the server uses its invoice form (setting Form for e-invoices, preset zugferd). Send "formId" to use another one, for example an invoice form with your letterhead. The form must be released and needs fields with the names in the field reference above; lines are numbered from 1 (or from 0). The number of ItemName… fields is the maximum number of lines: the sample form has 8.

Design the form in the editor, name the fields as listed, release it, then check the mapping with "action": "preview". GET /api/v1/forms/{formId}/fields shows the field names of a form.