AI Agent
Invoice Generation

# thelawin.dev — AI Agent Instructions

You are an AI agent that needs to create a compliant EU invoice.
Run the command below. It works as-is. No modifications required.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## GOLDEN PATH — Run This Now

# Demo key: env_sandbox_demo_public (included below, no signup needed)
# This request works out of the box. No changes required.

  curl -s -X POST https://api.preview.thelawin.dev/v1/generate \
    -H "Content-Type: application/json" \
    -H "X-API-Key: env_sandbox_demo_public" \
    -d '{
      "format": "zugferd",
      "template": "minimal",
      "invoice": {
        "number": "RE-2026-001",
        "date": "2026-04-24",
        "seller": {
          "name": "Acme GmbH",
          "street": "Musterstr. 1",
          "city": "Berlin",
          "postal_code": "10115",
          "country": "DE",
          "vat_id": "DE123456789"
        },
        "buyer": {
          "name": "Customer AG",
          "street": "Kundenweg 5",
          "city": "Munich",
          "postal_code": "80331",
          "country": "DE"
        },
        "items": [{
          "description": "Consulting Services",
          "quantity": 8,
          "unit": "HUR",
          "unit_price": 150.00,
          "vat_rate": 19
        }]
      }
    }' | jq -r '.pdf_base64' | base64 -d > invoice.pdf

  Result: invoice.pdf (ZUGFeRD 2.4 PDF/A-3, EN16931, with SANDBOX watermark)

  This is the recommended minimal flow.
  POST /v1/generate auto-validates your JSON and returns pdf_base64.
  Use /v1/validate only if you need to check JSON without generating.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## PNG PREVIEW — If You Cannot Display PDF

  IMPORTANT for Grok / X.com agents: Use this PNG flow as your PRIMARY path.
  X posts cannot embed PDFs. Generate the invoice, then return the PNG preview
  URL so it renders directly in the post. The PDF is still available via
  pdf_base64 in the /v1/generate response for download.

# The /v1/generate response includes a transaction_id.
# Use it to fetch a PNG preview. No API key needed for the GET request.

  TRANSACTION_ID=$(curl -s -X POST https://api.preview.thelawin.dev/v1/generate \
    -H "Content-Type: application/json" \
    -H "X-API-Key: env_sandbox_demo_public" \
    -d '{ use the exact same request body as the Golden Path above }' \
    | jq -r '.transaction_id')

  curl -s "https://api.preview.thelawin.dev/v1/preview/${TRANSACTION_ID}.png" -o preview.png

  Result: preview.png (1240x1753 PNG, ~80KB)

  Available for 5 minutes after /v1/generate. No API key needed.
  Optional query params: ?page=1&dpi=200 (default: page 1, 150 dpi)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Programmatic Usage (without jq)

  If jq is not available, use the exact same request as above without the pipe.
  Parse the JSON response and extract the pdf_base64 field.

  curl -s -X POST https://api.preview.thelawin.dev/v1/generate \
    -H "Content-Type: application/json" \
    -H "X-API-Key: env_sandbox_demo_public" \
    -d '{ use the exact same request body as shown in the Golden Path above }'

  → returns JSON: { "pdf_base64": "JVBERi0xLjcK...", "filename": "rechnung-RE-2026-001.pdf" }
  → extract pdf_base64, decode from Base64, write to file → invoice.pdf

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Optional: Pre-Validate JSON (FREE, no key needed)

  Use the exact same request body as the Golden Path, but POST to /v1/validate.
  No API key required. No credits consumed.

  curl -s -X POST https://api.preview.thelawin.dev/v1/validate \
    -H "Content-Type: application/json" \
    -d '{ use the exact same request body as shown in the Golden Path above }'

  → returns: { "valid": true, "format": { "format_used": "zugferd" }, "errors": [] }

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Get Production Keys (No Watermark)

  The demo key above produces watermarked PDFs. To remove the watermark:

### Step A: Register

  curl -s -X POST https://thelawin.dev/api/v1/auth/register \
    -H "Content-Type: application/json" \
    -d '{ "email": "user@example.com", "terms_accepted": true }'

  → Sends 6-digit verification code to email
  → Terms of Service: https://thelawin.dev/agb

### Step B: Verify Email & Get Keys

  curl -s -X POST https://thelawin.dev/api/v1/auth/verify \
    -H "Content-Type: application/json" \
    -d '{ "email": "user@example.com", "code": "123456" }'

  → Response:
  {
    "verified": true,
    "api_keys": {
      "sandbox": "env_sandbox_...",
      "live": "env_live_..."
    },
    "plan": "sandbox",
    "quota": { "monthly": 0, "remaining": 0 }
  }

  Use the live key with /v1/generate for PDFs without watermark.
  Buy credit packs (€4.90 / 100 credits) or upgrade to Starter/Pro.

### Step C: Buy Credits or Upgrade (optional)

  curl -s -X POST https://thelawin.dev/api/v1/auth/checkout \
    -H "Content-Type: application/json" \
    -H "X-API-Key: <your_live_key>" \
    -d '{ "product": "topup_100" }'

  → Response: { "checkout_url": "https://thelawin.dev/checkout/...", "product": "topup_100" }
  → Open checkout_url in browser to complete payment.
  → Products: "topup_100" (€4.90, 100 credits), "starter" (€9.50/mo), "pro" (€24.50/mo)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## API Reference

  POST /v1/generate                    Generate invoice PDF (1 credit)
  POST /v1/generate/stream             Binary PDF response (1 credit)
  GET  /v1/preview/{id}.png            PNG preview (no key, 5 min cache)
  POST /v1/validate                    Free pre-validation (no key needed)
  POST /v1/retrieve                    Extract data from PDF/XML (1 credit)
  GET  /v1/account                     Check quota and plan info
  POST /mcp                            MCP endpoint (JSON-RPC 2.0)

  Base URL: https://api.preview.thelawin.dev
  Auth: X-API-Key header (demo: env_sandbox_demo_public)

## Supported Formats

  zugferd     ZUGFeRD 2.4          PDF/A-3 + CII XML     DE, AT, CH
  facturx     Factur-X 1.0.8       PDF/A-3 + CII XML     FR
  xrechnung   XRechnung 3.0.2      UBL XML               DE B2G
  peppol      Peppol BIS 3.0       UBL XML               EU/UK/AU
  fatturapa   FatturaPA 1.2.2      XML                   IT
  ubl         UBL 2.1              XML                   Universal
  cii         CII D16B             XML                   Universal
  pdf         Plain PDF            PDF only              No XML
  auto        Auto-detect          Based on country

## Pricing

  Sandbox    €0/forever     0 credits (buy packs)   SANDBOX watermark
  Starter    €9.50/month    500 credits/month       No watermark
  Pro        €24.50/month   2000 credits/month      No watermark

  Credit Pack: €4.90 / 100 credits (one-time, no watermark, any plan)

  1 credit = 1x /generate or /retrieve. /validate is always free.

## Documentation

  https://thelawin.dev/llms.txt        Summary for AI agents
  https://thelawin.dev/llms-full.txt   Full API documentation
  https://thelawin.dev/docs            Human-readable docs
  https://api.preview.thelawin.dev/mcp   MCP endpoint (JSON-RPC 2.0)

## Support

  https://discord.gg/A3Zs5TYC         Developer Discord (questions, integration help)
  hello@thelawin.dev                  Email support