Référence API

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

Authentification

Envoyez votre clé via Authorization: Bearer bx_… ou X-API-Key. Les clés viennent avec votre abonnement ; les compteurs d'utilisation sont par clé, par jour, par point d'entrée.

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.

Créez une clé gratuite — sans carte, sans engagement : 50 appels validate + 50 appels convert par jour. Au-delà, passez à Starter (réponse 429 avec le lien).

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

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

L'email sert uniquement à limiter les créations de clés (stocké haché, jamais en clair).

Erreurs