Billhorse API

Set your API key

Sign up at console.billhorse.com (free, no credit card) and create a key on the API-keys page.

export BILLHORSE_API_KEY="bh_live_…"

Validate a sample invoice

Use our example file (valid XRechnung 3.0) or your own XML/PDF:

# Download the sample, then validate it
curl -sO https://billhorse.com/docs/examples/xrechnung-valid.xml
curl -s -X POST https://api.billhorse.com/v1/validate \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  --data-binary @xrechnung-valid.xml

Response (abridged):

{
  "valid": true,
  "profile": { "label": "XRechnung 3.0", "en16931": true, "xrechnung": true },
  "meta": { "number": "RE-2026-0815", "grandTotal": "178.50", … },
  "findings": [],
  "counts": { "error": 0, "warning": 0, "info": 0 }
}

See what errors look like

The broken sample triggers eight findings. Every finding carries a rule id — each one has a human explanation page:

{
  "valid": false,
  "findings": [
    { "id": "BR-DE-15", "severity": "error",
      "message": "XRechnung: buyer reference (BT-10, …) is mandatory." },
    { "id": "BR-CO-16", "severity": "error",
      "expected": "178.50", "actual": "170.00", … }
  ]
}

→ billhorse.com/en/rules/br-de-15 explains the rule and the fix, in EN, DE and FR. Messages come in English by default — add ?lang=de or ?lang=fr to show them to your end users in their language.

Parse into normalized JSON

/v1/parse extracts the EN 16931 semantic model — the same JSON shape whether the input was UBL, CII or a hybrid PDF:

curl -s -X POST https://api.billhorse.com/v1/parse \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  --data-binary @rechnung.pdf

{
  "invoice": {
    "number": "RE-2026-0815", "docType": "invoice", "currency": "EUR",
    "seller": { "name": "…", "vatId": "DE123456789", "country": "DE" },
    "totals": { "netTotal": "150", "taxTotal": "28.5", "due": "178.5" },
    "lines": [ … ], "vat": [ … ]
  },
  "report": { "valid": true, … }
}

Generate & convert (preview)

Build EN 16931 XML from a JSON invoice model, or convert an existing invoice between syntaxes. Pick ?format=cii (UN/CEFACT, the syntax embedded in ZUGFeRD/Factur-X), ?format=ubl (OASIS UBL), ?format=peppol(Peppol BIS Billing 3.0, needs electronic addresses to be routable) or?format=xrechnung (XRechnung 3.0 UBL, the German KOSIT CIUS — needs a seller contact, payment means and a buyer reference/Leitweg-ID for BR-DE). Factur-X/PDF-A3 embedding is server-side; you can also try generation live in your browser on the API page.

# Generate XML from a JSON model (format=cii | ubl | peppol | xrechnung)
curl -s -X POST "https://api.billhorse.com/v1/generate?format=cii" \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  -H "Content-Type: application/json" \
  --data @invoice-model.json > invoice.xml

# Generate XRechnung 3.0 (KOSIT CIUS) or Peppol BIS 3.0
curl -s -X POST "https://api.billhorse.com/v1/generate?format=xrechnung" \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  -H "Content-Type: application/json" \
  --data @invoice-model.json > invoice-xrechnung.xml

# Convert an existing invoice (UBL / CII / hybrid PDF) to another syntax
curl -s -X POST "https://api.billhorse.com/v1/convert?format=ubl" \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  --data-binary @invoice.xml > invoice-ubl.xml