Validation

Every generated invoice is automatically validated against ZUGFeRD 2.4 / Factur-X 1.0.8 standards.

Automatic Validation

When you generate an invoice, the response includes validation information:

{
  "pdf_base64": "...",
  "validation": {
    "status": "valid",
    "profile": "EN16931",
    "version": "2.3.2"
  }
}

Validation Status

Status	Description
valid	Invoice meets all ZUGFeRD/Factur-X requirements
invalid	Invoice has validation errors

Profiles

ZUGFeRD 2.4 supports multiple conformance profiles:

Profile	Description	Use Case
MINIMUM	Basic information only	Simple invoices
BASIC	Basic invoice data	Small businesses
EN16931	Full EU standard	B2G invoices (required)
EXTENDED	Additional fields	Complex requirements

thelawin.dev always generates EN16931 profile invoices to ensure maximum compatibility.

Validating Existing PDFs

You can also validate existing PDF files using the /v1/validate endpoint:

curl -X POST https://api.thelawin.dev/v1/validate \
  -H "X-API-Key: env_sandbox_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_base64": "JVBERi0xLjcK..."
  }'

Response

{
  "valid": true,
  "profile": "EN16931",
  "version": "2.3.2",
  "errors": [],
  "warnings": [
    {
      "code": "BR-CL-10",
      "message": "Currency code should be from ISO 4217"
    }
  ]
}

Common Validation Errors

Missing Required Fields

{
  "valid": false,
  "errors": [
    {
      "code": "BR-02",
      "path": "$.invoice.seller.vatId",
      "message": "Seller VAT identifier is required"
    }
  ]
}

Invalid VAT ID Format

{
  "valid": false,
  "errors": [
    {
      "code": "BR-CO-09",
      "path": "$.invoice.seller.vatId",
      "message": "VAT identifier must match country format"
    }
  ]
}

Invalid Unit Code

{
  "valid": false,
  "errors": [
    {
      "code": "BR-CL-23",
      "path": "$.invoice.items[0].unit",
      "message": "Unit code must be from UN/ECE Recommendation 20"
    }
  ]
}

See Unit Codes for valid unit codes.

Best Practices

1. Always check validation status - Even in sandbox mode, ensure your invoices are valid
2. Use correct VAT formats - Match the VAT ID format to the country (e.g., DE123456789 for Germany)
3. Include required fields - Seller name, address, and VAT ID are always required
4. Use standard unit codes - See Unit Codes for the complete list