API Reference

{
  "xml":        "<?xml version=\"1.0\"...>",   // Full XML as string
  "xml_base64": "PD94bWwg...",             // Base64-encoded XML for binary use
  "signed":     true,                      // true if signed with XAdES-BES
  "source":     "pdf",                     // "pdf" or "json"
  "invoice": {
    "vendor_name":   "Iberdrola S.A.U.",
    "vendor_vat":    "A95758389",
    "invoice_number":"F2024-001",
    "invoice_date":  "2024-06-15",
    "subtotal":      100.00,
    "tax":           21.00,
    "total":         121.00,
    "iban":          "ES21 0049...",
    "accounting":   { "account_code": "628", "account_label": "Suministros" // Utilities (Spanish PGC account) }
  },
  "warnings":   [],
  "confidence": 0.97,                   // Only in PDF mode
  "filename":   "facturae_F2024-001.xml",
  "meta": {
    "version":   "3.2.2",
    "standard":  "Facturae",
    "signature": "XAdES-BES"
  }
}

# Extract all data from a PDF invoice
curl -X POST https://api.facturax.app/extract \
  -H "X-API-Key: fct_your_api_key" \
  -F "file=@invoice.pdf"

import requests

API_KEY = "fct_your_api_key"

with open("invoice.pdf", "rb") as f:
    res = requests.post(
        "https://api.facturax.app/extract",
        headers={"X-API-Key": API_KEY},
        files={"file": ("invoice.pdf", f, "application/pdf")},
    )

data = res.json()
print(data["vendor_name"], data["total"], data["confidence_score"])

import fs from 'fs';
import FormData from 'form-data';
import fetch from 'node-fetch';

const fd = new FormData();
fd.append('file', fs.createReadStream('invoice.pdf'), 'invoice.pdf');

const res = await fetch('https://api.facturax.app/extract', {
  method: 'POST',
  headers: { 'X-API-Key': 'fct_your_api_key', ...fd.getHeaders() },
  body: fd,
});
const data = await res.json();
console.log(data.vendor_name, data.total);

import requests

API_KEY = "fct_your_api_key"
BASE    = "https://api.facturax.app"
HEADERS = {"X-API-Key": API_KEY}

# Step 1 — Extract data from the PDF
with open("invoice.pdf", "rb") as f:
    r1 = requests.post(f"{BASE}/extract", headers=HEADERS,
                        files={"file": ("invoice.pdf", f, "application/pdf")})
r1.raise_for_status()
invoice_data = r1.json()

# Check confidence before continuing
if invoice_data["confidence_score"] < 0.7:
    print("Low confidence — review manually", invoice_data["warnings"])

# Step 2 — Generate and download signed Facturae XML
r2 = requests.post(f"{BASE}/convert-to-facturae/download",
                    headers={**HEADERS, "Content-Type": "application/json"},
                    json={"invoice_data": invoice_data, "sign": True})
r2.raise_for_status()

with open("signed_invoice.xml", "wb") as out:
    out.write(r2.content)

print("✓ Signed Facturae saved to signed_invoice.xml")

{
  "error_code": "QUOTA_EXCEEDED",   // machine-readable code — stable across versions
  "detail":     "Quota exceeded. 150/150 used this month."  // human message — may change
}

RETRYABLE = {"EXTRACTION_FAILED", "SERVICE_ERROR", "XML_BUILD_FAILED"}

def handle_error(response):
    err = response.json()
    code = err.get("error_code", "UNKNOWN")

    if code in RETRYABLE:
        retry_with_backoff()          # transient error — retry
    elif code == "QUOTA_EXCEEDED":
        alert_team("Add credits")  # do not retry — needs human action
    elif code == "RATE_LIMIT_EXCEEDED":
        wait = response.headers.get("Retry-After", 60)
        time.sleep(int(wait))           # wait Retry-After then retry
    elif code in {"AUTH_INVALID_KEY", "AUTH_REQUIRED"}:
        raise ConfigError("Check API key") # never retry

import requests, time

def convert_with_retry(invoice_data, api_key, max_retries=3):
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
    for attempt in range(max_retries):
        r = requests.post("https://api.facturax.app/convert",
                          headers=headers, json=invoice_data)
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", 60))
            print(f"Rate limit — waiting {wait}s")
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()
    raise Exception("Persistent rate limit after 3 retries")

# For batches: process with a delay between calls
invoices = [...]  # list of dicts with invoice data
for invoice in invoices:
    result = convert_with_retry(invoice, "fct_your_api_key")
    time.sleep(1)  # 1s between calls → max 60/min, never hits the limit

import requests

def process_invoice(pdf_path: str) -> dict:
    # 1. Extract data
    with open(pdf_path, "rb") as f:
        res = requests.post(
            "https://api.facturax.app/extract",
            headers={"X-API-Key": API_KEY},
            files={"file": (pdf_path, f, "application/pdf")}
        )
    data = res.json()

    # 2. Alert if low confidence or fraud detected
    if data.get("confidence_score", 1) < 0.75:
        alert_review(pdf_path, data["warnings"])

    fraud = data.get("fraud_checks", {})
    if fraud.get("iban_check", {}).get("detected"):
        alert_iban_fraud(data["vendor_name"], data["iban"])

    # 3. PGC account assigned automatically
    account = data["accounting"]["account_code"]   # e.g.: "628"

    # 4. Generate signed Facturae if invoiced to a Public Administration
    if is_for_public_administration(data["buyer_vat"]):
        r2 = requests.post(
            "https://api.facturax.app/convert-to-facturae/download",
            headers={"X-API-Key": API_KEY},
            json={"invoice_data": data, "sign": True}
        )
        with open(pdf_path.replace(".pdf", ".xml"), "wb") as out:
            out.write(r2.content)

    return data

import requests, time, glob

files   = glob.glob("invoices/*.pdf")[:50]
handles = [("files", (open(f, "rb"))) for f in files]

# Create background job — responds immediately
res = requests.post("https://api.facturax.app/batch/job",
                    headers={"X-API-Key": API_KEY},
                    files=handles)
job_id = res.json()["job_id"]

# Poll until complete
while True:
    status = requests.get(f"https://api.facturax.app/batch/job/{job_id}",
                          headers={"X-API-Key": API_KEY}).json()
    print(f"{status['processed']}/{status['total']} processed")
    if status["status"] == "done": break
    time.sleep(3)

from flask import Flask, request
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret"

@app.route("/webhook", methods=["POST"])
def webhook():
    sig      = request.headers.get("X-Factura-Signature", "")
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(), request.data, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        return "Invalid signature", 401

    data = request.json()
    # Process the event
    print(data["event"], data["data"]["vendor_name"])
    return "", 200

# With API Key
curl -X POST https://api.facturax.app/extract \
  -H "X-API-Key: fct_your_api_key" \
  -F "file=@invoice.pdf"

# With JWT
curl -X POST https://api.facturax.app/extract \
  -H "Authorization: Bearer eyJhbGci..." \
  -F "file=@invoice.pdf"

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}