Generate Invoice

Generate EU-compliant electronic invoices in 9 different formats conforming to EN 16931.

Endpoint

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

Supported Formats

Format	Output	Description
auto	Varies	Auto-detect best format
zugferd	PDF + XML	ZUGFeRD 2.3 (Germany)
facturx	PDF + XML	Factur-X 1.0 (France)
xrechnung	PDF + XML	XRechnung 3.0 (German B2G)
ubl	XML	UBL 2.1 (OASIS standard)
cii	XML	UN/CEFACT CII
peppol	XML	Peppol BIS Billing 3.0
fatturapa	XML	FatturaPA (Italy)
pdf	PDF	Plain PDF (no XML)

See Invoice Formats for detailed information.

Headers

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

Request Body

{
  "template": "minimal",
  "locale": "en",
  "customization": {
    "accent_color": "#8b5cf6",
    "footer_text": "Thank you for your business!"
  },
  "invoice": {
    "number": "2026-001",
    "date": "2026-01-15",
    "due_date": "2026-02-15",
    "currency": "EUR",
    "notes": "Project Alpha Q1",
    "seller": {
      "name": "Acme GmbH",
      "vat_id": "DE123456789",
      "street": "Hauptstraße 1",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE",
      "email": "billing@acme.de",
      "phone": "+49 30 12345678"
    },
    "buyer": {
      "name": "Customer AG",
      "street": "Kundenweg 42",
      "city": "München",
      "postal_code": "80331",
      "country": "DE"
    },
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 8,
        "unit": "HUR",
        "unit_price": 150.00,
        "vat_rate": 19.0
      }
    ],
    "payment": {
      "iban": "DE89 3704 0044 0532 0130 00",
      "bic": "COBADEFFXXX",
      "terms": "Net 30 days"
    }
  }
}

Parameters

Root Level

Field	Type	Required	Description
format	string	No	Invoice format (see above). Default: auto
profile	string	No	minimum, basic_wl, basic, en16931, extended. Default: en16931
template	string	No	minimal, classic, or compact. Default: minimal
locale	string	No	en, de, fr, es, it. Default: en
customization	object	No	PDF customization options
invoice	object	Yes	Invoice data

Customization

Field	Type	Required	Description
logo_base64	string	No	Base64-encoded image (PNG, JPEG, SVG)
logo_width_mm	number	No	Logo width in mm. Default: 40
footer_text	string	No	Custom footer text
accent_color	string	No	Hex color code. Default: #8b5cf6

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)
due_date	string	No	BT-9	Due date (YYYY-MM-DD)
currency	string	No	BT-5	ISO 4217 code. Default: EUR
notes	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
leitweg_id	string	No	-	XRechnung: German routing ID
buyer_reference	string	No	BT-10	Peppol: Purchase order reference
tipo_documento	string	No	-	FatturaPA: IT document type (TD01, TD04)

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
vat_id	string	Seller: Yes	BT-31/BT-48	VAT identification number
street	string	No	BT-35/BT-50	Street address
city	string	No	BT-37/BT-52	City
postal_code	string	No	BT-38/BT-53	Postal code
country	string	No	BT-40/BT-55	ISO 3166-1 alpha-2 code. Default: DE
email	string	No	BT-43/BT-58	Email address
phone	string	No	BT-42/BT-57	Phone number
peppol_id	string	No	-	Peppol: Participant ID (e.g., 0088:123...)
codice_fiscale	string	No	-	FatturaPA: Italian tax code (11/16 chars)
codice_destinatario	string	No	-	FatturaPA: SDI recipient code (7 chars)
pec	string	No	-	FatturaPA: IT certified email

Line Item Object

Field	Type	Required	EN 16931	Description
description	string	Yes	BT-153	Item description
quantity	number	Yes	BT-129	Quantity
unit	string	No	BT-130	Unit code (UN/ECE Rec 20). Default: C62
unit_price	number	Yes	BT-146	Net price per unit
vat_rate	number	No	BT-152	VAT rate (e.g., 19.0 for 19%). Default: 19.0
natura	string	No	-	FatturaPA: IT VAT exemption code (N1-N7)

Payment Object

Field	Type	Required	EN 16931	Description
iban	string	No	BT-84	IBAN
bic	string	No	BT-86	BIC/SWIFT code
terms	string	No	BT-20	Payment terms description

Response

Success (200)

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

Error (400/422)

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

Example

curl -X POST https://api.thelawin.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",
        "vat_id": "DE123456789",
        "city": "Berlin",
        "country": "DE"
      },
      "buyer": {
        "name": "Customer AG",
        "city": "München",
        "country": "DE"
      },
      "items": [{
        "description": "Consulting",
        "quantity": 8,
        "unit": "HUR",
        "unit_price": 150,
        "vat_rate": 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.