API Reference

{
  "xml":        "<?xml version=\"1.0\"...>",   // XML completo como string
  "xml_base64": "PD94bWwg...",             // XML en base64 para binario
  "signed":     true,                      // true si lleva firma XAdES-BES
  "source":     "pdf",                     // "pdf" o "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" }
  },
  "warnings":   [],
  "confidence": 0.97,                   // Solo en modo PDF
  "filename":   "facturae_F2024-001.xml",
  "meta": {
    "version":   "3.2.2",
    "standard":  "Facturae",
    "signature": "XAdES-BES"
  }
}

# Extrae todos los datos de una factura PDF
curl -X POST https://api.facturax.app/extract \
  -H "X-API-Key: fct_tu_api_key" \
  -F "file=@factura.pdf"

import requests

API_KEY = "fct_tu_api_key"

with open("factura.pdf", "rb") as f:
    res = requests.post(
        "https://api.facturax.app/extract",
        headers={"X-API-Key": API_KEY},
        files={"file": ("factura.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('factura.pdf'), 'factura.pdf');

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

import requests

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

# Paso 1 — Extraer datos del PDF
with open("factura.pdf", "rb") as f:
    r1 = requests.post(f"{BASE}/extract", headers=HEADERS,
                        files={"file": ("factura.pdf", f, "application/pdf")})
r1.raise_for_status()
invoice_data = r1.json()

# Comprobar confianza antes de continuar
if invoice_data["confidence_score"] < 0.7:
    print("Confianza baja — revisar manualmente", invoice_data["warnings"])

# Paso 2 — Generar y descargar Facturae XML firmado
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("factura_firmada.xml", "wb") as out:
    out.write(r2.content)

print("✓ Facturae firmado guardado en factura_firmada.xml")

{
  "error_code": "QUOTA_EXCEEDED",   // código máquina-legible — estable entre versiones
  "detail":     "Cuota agotada. 150/150 usadas este mes."  // mensaje humano — puede cambiar
}

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()          # error transitorio — reintentar
    elif code == "QUOTA_EXCEEDED":
        alert_team("Añadir créditos")  # no reintentar — acción humana
    elif code == "RATE_LIMIT_EXCEEDED":
        wait = response.headers.get("Retry-After", 60)
        time.sleep(int(wait))           # esperar Retry-After y reintentar
    elif code in {"AUTH_INVALID_KEY", "AUTH_REQUIRED"}:
        raise ConfigError("Revisar API key") # nunca reintentar

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 — esperando {wait}s")
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()
    raise Exception("Rate limit persistente tras 3 reintentos")

# Para batches: procesar con delay entre llamadas
facturas = [...]  # lista de dicts con datos de factura
for factura in facturas:
    resultado = convert_with_retry(factura, "fct_tu_api_key")
    time.sleep(1)  # 1s entre llamadas → máx 60/min, nunca toca el límite

import requests

def procesar_factura(pdf_path: str) -> dict:
    # 1. Extraer datos
    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. Alertar si confianza baja o fraude detectado
    if data.get("confidence_score", 1) < 0.75:
        alert_revisar(pdf_path, data["warnings"])

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

    # 3. Cuenta PGC asignada automáticamente
    cuenta = data["accounting"]["account_code"]   # ej: "628"

    # 4. Generar Facturae firmado si es para AAPP
    if es_para_administracion(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("facturas/*.pdf")[:50]
handles = [("files", (open(f, "rb"))) for f in files]

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

# Polling hasta completar
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']} procesadas")
    if status["status"] == "done": break
    time.sleep(3)

from flask import Flask, request
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "tu_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 "Firma inválida", 401

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

# Con API Key
curl -X POST https://api.facturax.app/extract \
  -H "X-API-Key: fct_tu_api_key" \
  -F "[email protected]"

# Con JWT
curl -X POST https://api.facturax.app/extract \
  -H "Authorization: Bearer eyJhbGci..." \
  -F "[email protected]"

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)
  );
}