# thelawin.dev API Documentation

> Developer-first ZUGFeRD/Factur-X API. JSON in, EU-compliant PDF/A-3 out.

## Quick Start (Demo Key, no account needed)

```bash
curl -s -X POST https://api.thelawin.dev/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: env_sandbox_demo" \
  -d '{"invoice":{"number":"001","date":"2026-01-15","seller":{"name":"Acme GmbH","country":"DE"},"buyer":{"name":"Customer AG"},"items":[{"description":"Service","quantity":1,"unit_price":100}]}}'
```

## API Base URL

https://api.thelawin.dev

## Authentication

```
X-API-Key: env_sandbox_demo       (demo, no account, watermarked)
X-API-Key: env_sandbox_xxxxx      (sandbox, 100 credits/month, watermarked)
X-API-Key: env_live_xxxxx         (production, paid plan, no watermark)
```

No API key = sandbox mode (unlimited, watermarked).

## Endpoints

### POST /v1/generate
Generate EU-compliant e-invoices. 1 credit per call.

Formats: zugferd, facturx, xrechnung, ubl, cii, peppol, fatturapa, pdf, auto

Request:
```json
{
  "format": "zugferd",
  "profile": "en16931",
  "template": "minimal",
  "locale": "de",
  "invoice": {
    "number": "RE-2026-001",
    "date": "2026-01-15",
    "seller": { "name": "...", "country": "DE", "vat_id": "DE123456789" },
    "buyer": { "name": "...", "country": "DE" },
    "items": [{ "description": "...", "quantity": 1, "unit_price": 100, "vat_rate": 19 }],
    "payment": { "iban": "DE89370400440532013000", "terms": "Net 30" }
  }
}
```

Response: `{ "pdf_base64": "...", "filename": "...", "format": { "format_used": "zugferd", "profile": "EN16931" } }`

### POST /v1/validate
Validate invoice JSON without generating PDF. Free, no credits used.

Request: Same as /v1/generate.
Response: `{ "valid": true, "format": { "format_used": "zugferd" }, "errors": [] }`

### POST /v1/retrieve
Extract invoice data from existing PDF/XML (ZUGFeRD, Factur-X, XRechnung, UBL, Peppol, FatturaPA). 1 credit per call. NOT OCR — requires embedded e-invoice XML.

Request: `{ "data_base64": "...", "content_type": "application/pdf", "include_source_xml": false }`
Response: `{ "valid": true, "format": { "detected_format": "zugferd" }, "invoice": { ... }, "transaction_id": "tx_..." }`

### GET /v1/account
Check remaining credits and plan info.
Response: `{ "remaining": 450, "plan": "starter" }`

### POST /mcp
Model Context Protocol (JSON-RPC 2.0) for AI agents.
Tools: thelawin_generate, thelawin_validate

## Formats

| Format | Output | Standard | Use Case |
|--------|--------|----------|----------|
| zugferd | PDF+XML | ZUGFeRD 2.4 | Germany B2B |
| facturx | PDF+XML | Factur-X 1.0.8 | France |
| xrechnung | PDF+XML | XRechnung 3.0.2 | German B2G |
| ubl | XML | UBL 2.1 | OASIS standard |
| cii | XML | UN/CEFACT | Cross-industry |
| peppol | XML | Peppol BIS 3.0 | EU cross-border |
| fatturapa | XML | FatturaPA 1.2.2 | Italy SDI |
| pdf | PDF | - | Non-EU |
| auto | Varies | - | Auto-detect by country |

## Format-Specific Fields

- XRechnung: `leitweg_id`, `buyer_reference`
- Peppol: `seller.peppol_id`, `buyer.peppol_id`, `buyer_reference`
- FatturaPA: `tipo_documento`, `seller.codice_fiscale`, `buyer.codice_destinatario`

## Templates

- minimal: Clean, modern (1-15 items)
- classic: Traditional with borders (1-20 items)
- compact: Dense, multi-page (15-50+ items)

## SDKs (all 8 official, install from GitHub)

- TypeScript: `npm install github:steviee/thelawin-clients#path:typescript`
- Python: `pip install git+https://github.com/steviee/thelawin-clients.git#subdirectory=python`
- Ruby: `gem install thelawin` (RubyGems)
- Kotlin: GitHub/JitPack
- Java: GitHub/JitPack
- Swift: SPM from `https://github.com/steviee/thelawin-clients.git`
- Dart: Git dependency
- C#: Local build

Source: https://github.com/steviee/thelawin-clients

## Integrations

- n8n: https://docs.thelawin.dev/integrations/n8n
- Zapier: https://docs.thelawin.dev/integrations/zapier
- Make.com: https://docs.thelawin.dev/integrations/make
- AI Agents: https://docs.thelawin.dev/integrations/ai-agents
- Stripe: https://docs.thelawin.dev/integrations/stripe
- Shopify: https://docs.thelawin.dev/integrations/shopify
- DATEV: https://docs.thelawin.dev/integrations/datev

## Credits

- /generate: 1 credit
- /retrieve: 1 credit
- /validate: FREE

Plans: Sandbox (100/mo, watermark, free), Starter (500/mo, 9.50 EUR), Pro (2000/mo, 24.50 EUR). 50% beta discount.

## Error Codes

- 401: Invalid API key
- 402: Quota exceeded
- 422: Validation failed (see errors[].path for JSON path)
- 429: Rate limited

## Links

- Main: https://thelawin.dev
- Docs: https://docs.thelawin.dev
- API Reference: https://docs.thelawin.dev/api/generate
- Get API Key: https://thelawin.dev/signup
- Status: https://status.thelawin.dev
- GitHub: https://github.com/steviee/thelawin-clients