API reference

← back to billxml · machine spec: openapi.json · FR · EN · DE

Authentication

Send your key as Authorization: Bearer bx_… or X-API-Key. Keys come with your subscription; usage counters are per key, per day, per endpoint.

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.

Create a free key — no card, no commitment: 50 validate + 50 convert calls per day. Beyond that, upgrade to Starter (the 429 response carries the link).

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

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

The email is used only to rate-limit key creation (stored hashed, never in clear).

Errors