Generate Invoice

POST /v1/generate

Generate a ZUGFeRD 2.3 / Factur-X compliant PDF invoice from structured JSON data.

Request Body

Parameter Type Required Description
template string No minimal (default), classic, or compact
locale string No en (default), de, fr, es, it
invoice object Yes Invoice data (see below)
customization object No PDF customization (logo, footer)

Invoice Object

The invoice object contains all invoice data according to EN 16931. Fields marked as required are mandatory for ZUGFeRD/Factur-X compliance.

Field Type Required EN 16931 Description
number string Yes BT-1 Invoice number (e.g., "2026-001")
date string Yes BT-2 Invoice date (ISO 8601: YYYY-MM-DD)
due_date string No BT-9 Due date (ISO 8601: YYYY-MM-DD)
type_code string No BT-3 Invoice type: 380 (Invoice, default), 381 (Credit Note), 384 (Corrected Invoice)
currency string No BT-5 ISO 4217 code (default: EUR)
buyer_reference string No* BT-10 Buyer reference / Purchase Order Number (required for B2G)
seller object Yes BG-4 Seller/supplier address
buyer object Yes BG-7 Buyer/customer address
items array Yes BG-25 Line items (min. 1)
payment object No BG-16 Payment information
note string No BT-22 Free-text invoice note

EN 16931 Reference: The EN 16931 column shows the Business Term (BT) or Business Group (BG) identifier from the European e-invoicing standard. Learn more about EN 16931

Address Object (seller/buyer)

Address objects are used for both seller (BG-4) and buyer (BG-7) information. The seller's VAT ID is strongly recommended for tax compliance.

Field Type Required EN 16931 Description
name string Yes BT-27/BT-44 Legal name of the party
trading_name string No BT-28/BT-45 Trading name (if different from legal name)
street string No BT-35/BT-50 Street name and house number
additional_line string No BT-36/BT-51 Additional address line
city string No BT-37/BT-52 City name
postal_code string No BT-38/BT-53 Postal/ZIP code
country string No BT-40/BT-55 ISO 3166-1 alpha-2 code (default: DE)
vat_id string No* BT-31/BT-48 VAT identification number (e.g., DE123456789)
tax_number string No BT-32 Seller tax registration number (seller only)
email string No BT-43/BT-58 Contact email address
phone string No BT-42/BT-57 Contact phone number

Note: For B2B invoices within the EU, the seller's vat_id is required for VAT reverse charge. For B2G invoices, additional fields like buyer_reference may be mandatory.

Line Item Object

Each invoice must contain at least one line item (BG-25). Line items represent the goods or services being invoiced.

Field Type Required EN 16931 Description
description string Yes BT-153 Item name/description
quantity number Yes BT-129 Invoiced quantity (e.g., 8)
unit string No BT-130 UN/ECE Rec 20 code (default: C62). See Units Reference
unit_price number Yes BT-146 Net price per unit (e.g., 120.00)
vat_rate number No BT-152 VAT rate percentage (default: 19)
vat_category string No BT-151 VAT category: S (Standard), Z (Zero-rated), E (Exempt), K (Intra-community), G (Export)
seller_id string No BT-155 Seller's item identifier (SKU)
buyer_id string No BT-156 Buyer's item identifier
global_id string No BT-157 Global trade item number (GTIN/EAN)

Payment Object

Payment information (BG-16) for the invoice. While optional, providing bank details improves payment processing.

Field Type Required EN 16931 Description
means_code string No BT-81 Payment means code: 30 (Credit transfer), 58 (SEPA), 59 (SEPA Direct Debit)
iban string No BT-84 Payment account IBAN
bic string No BT-86 Payment service provider BIC/SWIFT
account_name string No BT-85 Payment account name
reference string No BT-83 Remittance information / payment reference
terms string No BT-20 Payment terms text (e.g., "Payment within 14 days")

Example Request

{
  "template": "minimal",
  "locale": "de",
  "invoice": {
    "number": "2026-001",
    "date": "2026-01-15",
    "due_date": "2026-01-29",
    "seller": {
      "name": "Acme GmbH",
      "street": "Musterstraße 1",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE",
      "vat_id": "DE123456789",
      "email": "rechnung@acme.de"
    },
    "buyer": {
      "name": "Customer AG",
      "street": "Kundenweg 42",
      "city": "München",
      "postal_code": "80331",
      "country": "DE"
    },
    "items": [
      {
        "description": "Software Development",
        "quantity": 40,
        "unit": "HUR",
        "unit_price": 120.00,
        "vat_rate": 19
      },
      {
        "description": "Project Management",
        "quantity": 8,
        "unit": "HUR",
        "unit_price": 95.00,
        "vat_rate": 19
      }
    ],
    "payment": {
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "terms": "Payment within 14 days"
    }
  },
  "customization": {
    "logo_base64": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
    "logo_width_mm": 35,
    "footer_text": "CEO: John Doe | HRB 12345 | District Court Berlin"
  }
}

Response

{
  "pdf_base64": "JVBERi0xLjcKJeLjz9MKNSAwIG9...",
  "filename": "rechnung-2026-001.pdf",
  "validation": {
    "status": "valid",
    "profile": "EN16931",
    "version": "2.3"
  },
  "account": {
    "remaining": 459,
    "plan": "starter"
  }
}