Validate Invoice Data
/v1/validate
Pre-validate invoice data before generating PDFs. Catch errors early without consuming generation quota.
/v1/generate, but returns validation results instead of generating a PDF/XML. Think of it as a pre-flight check.
What Gets Validated
Required fields, data types, format constraints (dates, currency codes, email)
Line item totals match, VAT calculations correct, payment terms valid
ZUGFeRD 2.3, Factur-X 1.0, XRechnung 3.0, Peppol BIS 3.0 compliance checks
Country codes (ISO 3166), currency codes (ISO 4217), unit codes (UN/ECE Rec 20)
Request Body
Accepts the same parameters as /v1/generate. See the Invoice Object reference for the complete parameter list.
| Parameter | Type | Required | Description |
|---|---|---|---|
template |
string | No | minimal (default), classic, or compact |
format |
string | No | auto (default), zugferd, facturx, xrechnung, etc. |
locale |
string | No | en, de, fr, es, it (auto-detects if omitted) |
invoice |
object | Yes | Invoice data with number, date, seller, buyer, items, etc. |
Example Request
curl -X POST https://api.thelawin.dev/v1/validate \
-H "Content-Type: application/json" \
-H "X-API-Key: env_sandbox_YOUR_KEY" \
-d '{
"format": "zugferd",
"invoice": {
"number": "RE-2026-001",
"date": "2026-01-15",
"due_date": "2026-02-14",
"currency": "EUR",
"seller": {
"name": "ACME GmbH",
"address": "Hauptstraße 1",
"zip": "10115",
"city": "Berlin",
"country": "DE",
"vat_id": "DE123456789"
},
"buyer": {
"name": "Tech Corp Ltd",
"address": "Baker Street 221B",
"zip": "NW1 6XE",
"city": "London",
"country": "GB"
},
"items": [
{
"name": "Professional Consulting",
"quantity": 8,
"unit": "HUR",
"unit_price": 150.00,
"vat_rate": 19
}
]
}
}'Response
| Field | Type | Description |
|---|---|---|
valid |
boolean | Whether invoice data is valid and ready for PDF generation |
errors |
array | Validation errors with field, code, and message |
warnings |
array | Non-critical warnings (e.g., missing optional fields) |
metadata |
object | Detected format, locale, and validation level used |
Success Response (Valid Invoice)
{
"valid": true,
"errors": [],
"warnings": [],
"metadata": {
"format": "zugferd",
"locale": "de",
"validation_level": "EN16931",
"response_time_ms": 42
}
}Error Response (Invalid Invoice)
When validation fails, the errors array contains detailed information including the JSON path to the problematic field.
{
"valid": false,
"errors": [
{
"field": "invoice.seller.vat_id",
"code": "INVALID_VAT_FORMAT",
"message": "VAT ID format invalid for country DE. Expected: DE + 9 digits",
"details": {
"provided": "DE12345",
"expected_pattern": "DE[0-9]{9}"
}
},
{
"field": "invoice.items[0].unit",
"code": "INVALID_UNIT_CODE",
"message": "Unit code 'HR' is not valid. Did you mean 'HUR' (hour)?",
"details": {
"provided": "HR",
"suggestions": ["HUR", "DAY", "MON"]
}
},
{
"field": "invoice.due_date",
"code": "INVALID_DATE",
"message": "Due date must be after invoice date",
"details": {
"invoice_date": "2026-01-15",
"due_date": "2026-01-10"
}
}
],
"warnings": [
{
"field": "invoice.buyer.email",
"code": "MISSING_OPTIONAL",
"message": "Buyer email is recommended for better customer experience"
}
],
"metadata": {
"format": "zugferd",
"locale": "de",
"validation_level": "EN16931",
"response_time_ms": 38
}
}Error Codes
Common validation error codes returned by this endpoint. For the complete list, see Error Reference.
| Code | Description |
|---|---|
MISSING_REQUIRED_FIELD |
Required field is missing (e.g., invoice.number, invoice.date) |
INVALID_FORMAT |
Field format is incorrect (e.g., date not ISO 8601, invalid email) |
INVALID_VAT_FORMAT |
VAT ID doesn't match country-specific pattern |
INVALID_UNIT_CODE |
Unit code not found in UN/ECE Recommendation 20 |
INVALID_CURRENCY_CODE |
Currency code not found in ISO 4217 |
INVALID_COUNTRY_CODE |
Country code not found in ISO 3166-1 alpha-2 |
CALCULATION_MISMATCH |
Line item totals don't match (quantity × unit_price ≠ net_amount) |
BUSINESS_RULE_VIOLATION |
EN 16931 business rule violated (e.g., due date before invoice date) |
Use Cases
Pre-Flight Check
Validate invoice data before generating PDFs. Catch errors early without consuming generation quota.
Real-Time Feedback
Provide instant validation feedback in invoice forms. Guide users to fix errors before submission.
Batch Validation
Validate hundreds of invoices before bulk generation. Identify and fix issues across entire batches.
Development Testing
Test invoice templates and integrations without generating PDFs. Faster iteration during development.
Performance & Quota
Typical response time: 20-50ms (faster than /v1/generate since no PDF rendering).
Frequently Asked Questions
Can I validate invoice data without an API key?
No. The /v1/validate endpoint requires authentication via X-API-Key header, just like /v1/generate. However, validation requests don't count against your quota, so you can validate freely in sandbox mode.
Does validation guarantee successful PDF generation?
Yes, with rare exceptions. If validation returns "valid": true, the subsequent /v1/generate call should succeed, unless:
- • Your quota is exhausted (validation doesn't check quota)
- • Network/timeout issues occur
- • You modify the data between validation and generation
What's the difference between errors and warnings?
Errors (blocking): Must be fixed before PDF generation succeeds. Examples: missing required fields, invalid formats, business rule violations.
Warnings (non-blocking): Best practice recommendations. PDF generation proceeds, but you might want to address these for better compliance or UX. Examples: missing optional email, missing buyer reference.
Can I validate existing PDFs for ZUGFeRD compliance?
Not yet. The /v1/validate endpoint currently validates invoice data (JSON) before generation. PDF validation (checking existing PDFs for compliance) is planned for a future release.