Generate Invoice

Generate a ZUGFeRD/Factur-X compliant PDF invoice conforming to EN 16931.

Endpoint

POST https://api.envoice.dev/v1/generate

Headers

Header	Required	Description
X-API-Key	Yes	Your API key
Content-Type	Yes	application/json

Request Body

{
  "template": "minimal",
  "locale": "en",
  "accentColor": "#8b5cf6",
  "footerText": "Thank you for your business!",
  "logo": {
    "base64": "data:image/png;base64,...",
    "widthMm": 30
  },
  "invoice": {
    "number": "2026-001",
    "date": "2026-01-15",
    "dueDate": "2026-02-15",
    "currency": "EUR",
    "typeCode": "380",
    "buyerReference": "PO-12345",
    "note": "Project Alpha Q1",
    "seller": {
      "name": "Acme GmbH",
      "tradingName": "Acme Solutions",
      "vatId": "DE123456789",
      "street": "Hauptstraße 1",
      "city": "Berlin",
      "postalCode": "10115",
      "country": "DE",
      "email": "billing@acme.de",
      "phone": "+49 30 12345678"
    },
    "buyer": {
      "name": "Customer AG",
      "vatId": "DE987654321",
      "street": "Kundenweg 42",
      "city": "München",
      "postalCode": "80331",
      "country": "DE"
    },
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 8,
        "unit": "HUR",
        "unitPrice": 150.00,
        "vatRate": 19.0,
        "vatCategory": "S"
      }
    ],
    "payment": {
      "meansCode": "58",
      "iban": "DE89 3704 0044 0532 0130 00",
      "bic": "COBADEFFXXX",
      "accountName": "Acme GmbH",
      "reference": "INV-2026-001",
      "terms": "Net 30 days"
    }
  }
}

Parameters

Root Level

Field	Type	Required	Description
template	string	No	minimal, classic, or compact. Default: minimal
locale	string	No	en, de, fr, es, it. Default: en
accentColor	string	No	Hex color code. Default: #8b5cf6
footerText	string	No	Custom footer text
logo	object	No	Logo configuration
invoice	object	Yes	Invoice data

Logo

Field	Type	Required	Description
base64	string	Yes	Base64-encoded image (PNG, JPEG, SVG)
widthMm	number	No	Logo width in mm. Default: 30

Invoice Object

Field	Type	Required	EN 16931	Description
number	string	Yes	BT-1	Invoice number
date	string	Yes	BT-2	Invoice date (YYYY-MM-DD)
dueDate	string	No	BT-9	Due date (YYYY-MM-DD)
currency	string	No	BT-5	ISO 4217 code. Default: EUR
typeCode	string	No	BT-3	Document type code (380=Invoice, 381=Credit Note). Default: 380
buyerReference	string	No	BT-10	Buyer's reference (e.g. PO number)
note	string	No	BT-22	Invoice note / project reference
seller	object	Yes	BG-4	Seller information
buyer	object	Yes	BG-7	Buyer information
items	array	Yes	BG-25	Line items (min 1)
payment	object	No	BG-16	Payment information

Invoice Number

The invoice number (BT-1) must be unique and is used as the primary identifier.

Invoice Date

The invoice date (BT-2) in ISO 8601 format: YYYY-MM-DD

Due Date

The payment due date (BT-9) in ISO 8601 format: YYYY-MM-DD

Currency

ISO 4217 currency code (BT-5). Supported: EUR, USD, GBP, CHF, etc.

Address Object (Seller/Buyer)

Field	Type	Required	EN 16931	Description
name	string	Yes	BT-27/BT-44	Legal name
tradingName	string	No	BT-28/BT-45	Trading name (if different)
vatId	string	Seller: Yes	BT-31/BT-48	VAT identification number
street	string	No	BT-35/BT-50	Street address
city	string	Yes	BT-37/BT-52	City
postalCode	string	No	BT-38/BT-53	Postal code
country	string	Yes	BT-40/BT-55	ISO 3166-1 alpha-2 code
email	string	No	BT-43/BT-58	Email address
phone	string	No	BT-42/BT-57	Phone number

Line Item Object

Field	Type	Required	EN 16931	Description
description	string	Yes	BT-153	Item description
quantity	number	Yes	BT-129	Quantity
unit	string	Yes	BT-130	Unit code (UN/ECE Rec 20)
unitPrice	number	Yes	BT-146	Net price per unit
vatRate	number	Yes	BT-152	VAT rate (e.g., 19.0 for 19%)
vatCategory	string	No	BT-151	VAT category code (S, Z, E, AE, K, G, O, L, M). Default: S

VAT Category Codes

Code	Description
S	Standard rate
Z	Zero rated
E	Exempt
AE	Reverse charge
K	Intra-community supply
G	Export outside EU
O	Outside scope of VAT
L	Canary Islands
M	Ceuta and Melilla

Payment Object

Field	Type	Required	EN 16931	Description
meansCode	string	No	BT-81	Payment means code (30=Bank transfer, 58=SEPA). Default: 58
iban	string	No	BT-84	IBAN
bic	string	No	BT-86	BIC/SWIFT code
accountName	string	No	BT-85	Account holder name
reference	string	No	BT-83	Payment reference
terms	string	No	BT-20	Payment terms description

Payment Means Codes

Code	Description
30	Credit transfer
58	SEPA credit transfer
59	SEPA direct debit

Response

Success (200)

{
  "pdf_base64": "JVBERi0xLjcK...",
  "filename": "invoice-2026-001.pdf",
  "validation": {
    "status": "valid",
    "profile": "EN16931",
    "version": "2.3.2"
  },
  "account": {
    "remaining": 499,
    "plan": "starter"
  }
}

Error (400/422)

{
  "error": "validation_failed",
  "message": "Invoice validation failed",
  "details": [
    {
      "path": "$.invoice.seller.vatId",
      "code": "REQUIRED",
      "message": "Seller VAT ID is required",
      "expected": "string (e.g. DE123456789)"
    }
  ],
  "docs": "https://docs.envoice.dev/api/generate#address-object"
}

Example

curl -X POST https://api.envoice.dev/v1/generate \
  -H "X-API-Key: env_sandbox_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "minimal",
    "invoice": {
      "number": "2026-001",
      "date": "2026-01-15",
      "seller": {
        "name": "Acme GmbH",
        "vatId": "DE123456789",
        "city": "Berlin",
        "country": "DE"
      },
      "buyer": {
        "name": "Customer AG",
        "city": "München",
        "country": "DE"
      },
      "items": [{
        "description": "Consulting",
        "quantity": 8,
        "unit": "HUR",
        "unitPrice": 150,
        "vatRate": 19
      }]
    }
  }'

EN 16931 Compliance

This API generates invoices compliant with:

• EN 16931 - European standard for electronic invoicing
• ZUGFeRD 2.3 - German e-invoice standard (PDF/A-3 with embedded XML)
• Factur-X 1.0 - French equivalent of ZUGFeRD

All generated PDFs include embedded XML metadata that can be extracted and processed automatically by accounting software.