API-Referenz

← zurück zu billxml · Spezifikation: openapi.json · FR · EN · DE

Authentifizierung

Senden Sie Ihren Schlüssel als Authorization: Bearer bx_… oder X-API-Key. Schlüssel kommen mit Ihrem Abo; Nutzungszähler pro Schlüssel, pro Tag, pro Endpunkt.

POST /v1/validate

Body: raw XML (UBL Invoice/CreditNote or CII) or a Factur-X PDF. Optional ?profile=auto|peppol|xrechnung|en16931. The response lists every failed rule with its id, message and XPath location.

curl -X POST https://billxml.com/v1/validate \
  -H "Authorization: Bearer bx_YOUR_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

{
  "format": "UBL", "syntax": "UBL-Invoice",
  "valid": false,
  "error_count": 1,
  "rulesets": [{
    "id": "en16931-ubl", "version": "1.3.16", "status": "fail",
    "errors": [{
      "rule": "BR-CO-25",
      "message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
      "location": "/*:Invoice[1]"
    }]
  }]
}

POST /v1/convert?target=…

Targets: ubl (CII in, UBL 2.1 out), cii (UBL in, CII out), json-ubl (simple JSON in, UBL out), factur-x (CII in, PDF/A-3 with embedded XML out; optional &pdf= base64 visual layer). Output: {"xml": "…"} or {"pdf_base64": "…"}.

GET /v1/formats · GET /v1/usage

/v1/formats is public. /v1/usage returns your key's daily counters.

Kostenlosen Key erstellen — ohne Karte, ohne Bindung: 50 validate- + 50 convert-Aufrufe pro Tag. Danach Upgrade auf Starter (die 429-Antwort enthält den Link).

curl -X POST https://billxml.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"sie@firma.de"}'

{
  "key": "bx_…",
  "plan": "free",
  "daily": { "validate": 50, "convert": 50 }
}

Die E-Mail dient nur der Limitierung der Key-Erstellung (gehasht gespeichert, nie im Klartext).

Fehler