FacturaX.app — API Docs

Autenticación

Todas las peticiones deben incluir una API key en la cabecera X-API-Key o un JWT en Authorization: Bearer <token>. Las API keys se crean desde el dashboard o via POST /keys.

Autenticación con API Key: Incluye la cabecera X-API-Key: fct_xxxxxxxxxxxx en cada petición. Ideal para integraciones server-to-server.

Autenticación con JWT: Obtén un token con POST /auth/login e inclúyelo como Authorization: Bearer <token>. Los tokens tienen validez de 72 horas.

EJEMPLO

# 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]"

POST /auth/login Obtener JWT de acceso

Body (JSON)

Campo	Tipo	Requerido	Descripción
email	string	requerido	Email de la cuenta
password	string	requerido	Contraseña (mínimo 8 caracteres)

Respuesta

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type":   "bearer",
  "user": {
    "id":        1,
    "email":     "[email protected]",
    "full_name": "Juan García",
    "plan":      "pro"
  }
}

Códigos de respuesta

200Login correcto. Devuelve el JWT.

401Email o contraseña incorrectos.

403Email no verificado.

Extracción de facturas

El endpoint principal. Acepta una factura en PDF, PNG o JPG y devuelve todos los campos extraídos en JSON, junto con verificaciones antifraude y categorización contable PGC automática.

POST /extract Extraer datos de una factura AUTH

Request — multipart/form-data

Campo	Tipo	Requerido	Descripción
file	file	requerido	Factura en PDF, PNG o JPG. Máximo 20MB. Soporta multipágina y escaneados.

Ejemplo

CURL

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

JAVASCRIPT

const fd = new FormData();
fd.append('file', file);

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

Respuesta

JSON

{
  "vendor_name":     "Iberdrola S.A.U.",
  "vendor_vat":      "A95758389",
  "invoice_number":  "FAC-2024-0312",
  "invoice_date":    "2024-03-15",
  "due_date":        "2024-04-15",
  "currency":        "EUR",
  "subtotal":        154.90,
  "tax":             32.53,
  "total":           187.43,
  "iban":            "ES7621000813610123456789",
  "line_items": [
    {
      "description": "Consumo eléctrico marzo",
      "quantity":    1,
      "unit_price":  154.90,
      "total":       187.43
    }
  ],
  "confidence_score": 0.97,
  "warnings":         [],
  "accounting": {
    "account_code":  "628",
    "account_label": "Suministros",
    "type":          "gasto",
    "confidence":    "alta"
  },
  "fraud_checks": {
    "duplicate":        { "detected": false },
    "vat_verification": { "valid": true, "status": "verified" },
    "iban_check":       { "detected": false }
  },
  "_log_id": 42
}

Códigos de respuesta

200Extracción completada. Devuelve el JSON completo.

400Tipo de archivo no permitido.

401API key o JWT inválido.

413Archivo demasiado grande (máx. 20MB).

429Cuota agotada para este plan.

GET /history Historial de extracciones AUTH

Query params

Campo	Tipo	Requerido	Descripción
limit	integer	opcional	Número de resultados (por defecto 50, máx. 100)

Códigos de respuesta

200Lista de extracciones con resultado JSON y metadatos.

Facturae XML 3.2.2

Convierte el JSON extraído al formato Facturae 3.2.2, el estándar oficial español para facturación electrónica requerido por la Ley Crea y Crece. Compatible con FACe y la Administración Pública.

POST /convert-to-facturae Generar XML Facturae (devuelve JSON) AUTH

Body (JSON)

Campo	Tipo	Requerido	Descripción
invoice_data	object	requerido	JSON del resultado de /extract
seller_info	object	opcional	Datos adicionales del emisor: name, vat, address, city, zip
buyer_info	object	opcional	Datos del receptor: name, vat, address, city, zip
sign	boolean	opcional	Firmar con XAdES-BES (requiere p12_b64)
p12_b64	string	opcional	Certificado .p12 en base64 para firma XAdES

Respuesta

JSON

{
  "xml":      "<?xml version=\"1.0\"?><fe:Facturae ...>",
  "version": "3.2.2",
  "signed":  false,
  "filename": "facturae_FAC-2024-0312.xsig"
}

POST /convert-to-facturae/download Descargar .xsig directamente AUTH

Mismo body que /convert-to-facturae pero devuelve el archivo XML directamente con Content-Disposition: attachment.

CURL

curl -X POST https://api.facturax.app/convert-to-facturae/download \
  -H "X-API-Key: fct_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"invoice_data": {...}}' \
  -o factura.xsig

Antifraude

Gestiona los IBANs de confianza de tus proveedores y confirma o descarta alertas de duplicados. Las verificaciones antifraude se ejecutan automáticamente en cada extracción.

GET /vendors Listar proveedores con IBAN registrado AUTH

Respuesta

JSON

{
  "vendors": [
    {
      "vendor_vat":   "A95758389",
      "trusted_iban": "ES7621000813610123456789",
      "last_seen":    "2024-03-15 10:32:00"
    }
  ]
}

PUT /vendors/{vendor_vat}/iban Actualizar IBAN de confianza de un proveedor AUTH

Path params

Campo	Tipo	Descripción
vendor_vat	string	CIF/NIF del proveedor (ej: A95758389)

Body (JSON)

Campo	Tipo	Descripción
iban	string	Nuevo IBAN de confianza (sin espacios)

Categorización contable

Asigna automáticamente la cuenta del Plan General Contable español usando reglas deterministas + IA con el PGC completo embebido.

POST /categorize Categorizar una factura según el PGC AUTH

Body (JSON)

Campo	Tipo	Requerido	Descripción
vendor_name	string	opcional	Nombre del emisor
vendor_vat	string	opcional	CIF/NIF del emisor
line_items	array	opcional	Líneas de la factura con description
total	number	opcional	Importe total (influye en gasto vs inversión)

Respuesta

JSON

{
  "account_code":  "628",
  "account_label": "Suministros",
  "type":          "gasto",
  "type_label":    "Gasto del ejercicio",
  "reasoning":    "Iberdrola es un proveedor de suministros eléctricos.",
  "confidence":   "alta",
  "method":       "regla",
  "suggestions":  []
}

API Keys

Gestiona las API keys para integraciones externas. Disponible en planes Pro y Business.

POST /keys Crear nueva API key JWT

Body (JSON)

Campo	Tipo	Requerido	Descripción
name	string	requerido	Nombre descriptivo (ej: "Mi ERP")
plan	string	opcional	"free" o "pro". Por defecto "free".

Importante: La API key solo se muestra una vez al crearla. Guárdala en un lugar seguro.

Webhooks

Recibe notificaciones HTTP en tiempo real cuando se procesa una factura. Cada petición incluye una firma HMAC-SHA256 para verificar autenticidad.

Verificación de firma: Cada webhook incluye la cabecera X-Factura-Signature: sha256=HASH. Verifica que el hash coincide con HMAC-SHA256(payload, tu_secret) para confirmar que la petición es auténtica.

VERIFICACIÓN EN NODE.JS

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

POST /webhooks Crear webhook AUTH

Body (JSON)

Campo	Tipo	Requerido	Descripción
url	string	requerido	URL HTTPS donde recibirás los eventos
events	array	opcional	[""] para todos, o ["invoice.extracted"]. Por defecto [""].
secret	string	opcional	Secret para firmar. Si no se provee, se genera automáticamente.

Payload del webhook

JSON

{
  "event":     "invoice.extracted",
  "timestamp": 1710500000,
  "data": {
    "log_id":         42,
    "filename":       "factura.pdf",
    "vendor_name":    "Iberdrola S.A.U.",
    "vendor_vat":     "A95758389",
    "invoice_number": "FAC-2024-0312",
    "total":          187.43,
    "confidence":     0.97,
    "accounting": { "account_code": "628" },
    "fraud_checks": { "duplicate": { "detected": false } }
  }
}

DELETE /webhooks/{id} Eliminar webhook AUTH

Códigos de respuesta

200Webhook eliminado correctamente.

404Webhook no encontrado.

API Reference

Autenticación

Body (JSON)

Respuesta

Códigos de respuesta

Extracción de facturas

Request — multipart/form-data

Ejemplo

Respuesta

Códigos de respuesta

Query params

Códigos de respuesta

Facturae XML 3.2.2

Body (JSON)

Respuesta

Antifraude

Respuesta

Path params

Body (JSON)

Categorización contable

Body (JSON)

Respuesta

API Keys

Body (JSON)

Webhooks

Body (JSON)

Payload del webhook

Códigos de respuesta