Documentación de Conexión API

Bienvenido a la especificación técnica de la API de **Digitaldocu Verifactu (Broker)**. Este middleware actúa como Componente de Facturación (CF) y centraliza las obligaciones normativas españolas del **Real Decreto 1007/2023 (Reglamento Verifactu)** y de la **Ley Crea y Crece**. Permite a cualquier software ERP o sistema de facturación principal (CPF) delegar la firma de facturas, el encadenamiento criptográfico, la generación de huellas, la remisión a la AEAT / SPFE, y la gestión de firmas de declaraciones responsables sin necesidad de implementar los protocolos complejos de forma nativa.

Características Principales de la Conexión

Autenticación Simple: Uso de cabecera estándar con token API único por cliente.
Protocolo no bloqueante: Recepción asíncrona de facturas con procesamiento en cola para respuesta inmediata y tolerancia a caídas de la AEAT.
Onboarding Legal: Flujo digital automatizado para firmas de Declaración Responsable (Modelos A y B) integradas en Digitaldocu.
Doble Remisión: Redirección simultánea y selectiva de registros a la AEAT y a la Solución Pública de Facturación Electrónica (Crea y Crece).

Arquitectura y Conexión de Actores

La normativa exige que todos los sistemas informáticos de facturación (SIF) garanticen la integridad, inmutabilidad y trazabilidad de los registros. En nuestra plataforma, esto se distribuye bajo un modelo de arquitectura dividida en tres actores principales:

ERP Cliente (CPF)

Componente Principal. Captura la venta y solicita la firma al Broker mediante API.

→

Broker Verifactu (CF)
Componente de Transmisión. Firma con certificado local, encadena huellas, y gestiona colas.

→

AEAT / SPFE

Sede Electrónica. Recibe de forma inmediata y retorna códigos de validación oficiales.

1. Componente Principal de Facturación (CPF) — El ERP del Cliente

Es el sistema que interactúa con el usuario final. Al guardar o emitir una factura, el ERP **debe realizar una llamada HTTP POST** al Broker Verifactu. Debe mostrar el código QR generado y la mención "Factura verificable en la sede electrónica de la AEAT" en el documento entregado al cliente, obteniendo estos datos de vuelta a través de callbacks/webhooks.

2. Componente de Facturación Central (CF) — El Broker

Recibe las solicitudes del ERP, encola los trabajos y procesa el encadenamiento de huellas SHA-256 en base a la última factura validada del cliente. Genera los documentos XML (SOAP de Verifactu o UBL de Crea y Crece), los firma digitalmente con el certificado de firma de la empresa y los envía a los servidores gubernamentales.

3. Receptor de la Factura (En Crea y Crece)

Las facturas del emisor se suben a la Solución Pública de Facturación Electrónica (SPFE). El receptor puede recibir la notificación de forma directa, y conectarse a la API del Broker para enviar el acuse de recibo o cambios en el estado de cobro/pago.

Autenticación

Todas las solicitudes dirigidas a los endpoints de la API deben autenticarse obligatoriamente mediante una cabecera personalizada en la petición HTTP. La clave es única por cliente, la genera siempre el servidor del Broker y opera en modo servicio: identifica a la empresa ante la API, pero no da acceso al panel de administración (el panel tiene su propio login de usuario, reservado al equipo del Broker).

Estructura de la Cabecera de Autenticación

Debe incluir la siguiente cabecera HTTP en todas las peticiones:

X-API-Key: su-token-api-unico-de-empresa

Nota: Las llamadas que no incluyan la cabecera recibirán un código de estado HTTP 401 Unauthorized. Si la API Key es errónea, se responderá con un código HTTP 403 Forbidden.

Ciclo de vida de la API Key

Se entrega una única vez, al dar de alta la empresa o al regenerarla (POST /api/v1/companies/{id}/regenerate-key, sólo administración).
El Broker no almacena el valor en claro (sólo su hash SHA-256): si se pierde, no se puede recuperar — debe regenerarse.
Los listados de administración muestran únicamente una pista (api_key_hint, p. ej. ddv_a1b2…f9z4).
Regenerar la clave revoca la anterior en el acto: planifique el cambio con el cliente.

Envío de Factura Verifactu (REST JSON)

Este es el canal más sencillo para ERPs. El sistema recibe un JSON estructurado con la información comercial básica, encola el trabajo de forma inmediata y devuelve un identificador de seguimiento. El broker se encargará de transformar los campos, aplicar las huellas y enviarlo asíncronamente a la AEAT.

POST /api/v1/invoices

Parámetros de Solicitud (JSON Body)

Campo	Tipo	Obligatorio	Descripción
series	string	Opcional	La serie de la factura (e.g. "F2026"). Puede ser una cadena vacía para series principales.
number	string	Obligatorio	El número correlativo de factura dentro de la serie (e.g. "4921").
date	string	Obligatorio	Fecha de expedición en formato ISO `YYYY-MM-DD` (e.g. "2026-06-07").
amount	float	Obligatorio	Importe total de la factura en euros, impuestos incluidos (e.g. 121.00).
tax	float	Obligatorio	Desglose del importe total de IVA aplicado en la factura (e.g. 21.00).
type	string	Obligatorio	El tipo de registro. Valores permitidos: `F1` (Factura ordinaria), `F2` (Factura simplificada / ticket), `ANUL` (Anulación de factura previa).

Envío de Factura Verifactu (Facturae XML)

Si su ERP ya genera facturas electrónicas firmadas o sin firmar en el formato estándar del Ministerio de Industria (**Facturae 3.2.x**), puede enviar el archivo XML crudo directamente. El Broker lo parsea, comprueba sus datos y procesa el registro Verifactu de forma equivalente.

POST /api/v1/invoices/xml

Envío de Facturas Crea y Crece

Para empresas obligadas a operar bajo la ley **Crea y Crece**, la API permite enviar los datos de la factura en JSON (que el broker convertirá a XML UBL 2.1 estándar) o bien enviar directamente el documento XML UBL listo para la Solución Pública de Facturación Electrónica (SPFE).

POST /api/v1/creaycrece/invoices

Campos Adicionales del payload JSON

Campo	Tipo	Obligatorio	Descripción
copy_indicator	integer	Opcional	Indica el canal de copia. Utilice `1` para factura original emitida y `0` para copias informativas. (Por defecto: 1)

Registro de Estados de Pago (Crea y Crece)

La ley Crea y Crece obliga a reportar los estados de cobro y pago de las facturas emitidas para controlar la morosidad comercial. Los actores (proveedor o cliente) deben notificar al Broker los cambios de estado correspondientes.

POST /api/v1/creaycrece/payments

Parámetros del Estado de Pago

Campo	Tipo	Obligatorio	Descripción
invoice_id	integer	Obligatorio	ID interno de la factura Crea y Crece que ha cambiado de estado de pago.
status_type	string	Obligatorio	El tipo de estado de cobro/pago. Valores válidos: `PAID` (Cobrada/Pagada completamente), `REJECTED` (Factura rechazada por el destinatario), `DUE_DATE` (Fecha de vencimiento alcanzada sin cobro).
event_date	string	Obligatorio	Fecha en formato ISO `YYYY-MM-DD` en la que se produjo la transacción de pago o el rechazo.

Callback URL (Webhooks)

Dado que el procesamiento del Broker es asíncrono y en cola, no bloquea al ERP durante la llamada al endpoint. El broker enviará un **HTTP POST** con los resultados finales de validación (AEAT y SPFE) a la `callback_url` configurada para el cliente.

Esquema de Notificación del Webhook (POST)

Su servidor de callback en el ERP recibirá peticiones con el siguiente cuerpo JSON:

{
  "event": "INVOICE_VALIDATED",
  "company_nif": "B88776655",
  "series": "F2026",
  "number": "4921",
  "date": "2026-06-07",
  "amount": 121.00,
  "status": "VALIDATED",
  "aeat_response_code": "0",
  "aeat_description": "Aceptado con éxito en VERI*FACTU",
  "qr_url": "https://www2.agenciatributaria.gob.es/wlpl/SSII-FACT/VAL/SiiFactAlta?nif=B88776655&num=4921&fec=2026-06-07&imp=121.00",
  "huella_digital_sha256": "8F3A2290B551C...F012A"
}
                        

Importante: Su endpoint de callback debe responder con un código HTTP 200 OK o 204 No Content para confirmar la recepción del evento. El Broker reintentará hasta 3 veces el envío si se producen fallos de red.

Crea y Crece — Endpoints avanzados

Endpoints especializados para integraciones avanzadas con la Solución Pública de Facturación Electrónica (SPFE): pre-validación schematron EN 16931 sin persistencia, envío estructurado con mapeo automático a UBL 2.1, ingesta de Facturae 3.2.x y un canal síncrono que devuelve directamente el CSV de aceptación.

POST /api/v1/creaycrece/validate

Pre-validación del XML UBL contra el conjunto de reglas schematron EN 16931 (perfil CIUS-FACE-B2G). No persiste nada en base de datos ni encola trabajos. Útil para que el ERP detecte errores estructurales antes de emitir.

Cabeceras

Cabecera	Valor
Content-Type	`application/xml`

No requiere X-API-Key (endpoint de utilidad pública).

Cuerpo

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  ...
</Invoice>

Respuesta exitosa (200 OK)

{
  "is_valid": false,
  "flavor": "CIUS-FACE-B2G",
  "findings": [
    {
      "rule_id": "BR-CO-15",
      "severity": "fatal",
      "text": "Invoice total amount with VAT must equal the sum of line net amounts + VAT total.",
      "location": "/Invoice/cac:LegalMonetaryTotal/cbc:PayableAmount"
    }
  ],
  "fatal_count": 1,
  "warning_count": 0
}

Errores

HTTP	Cuándo ocurre
400	XML mal formado o vacío
415	Content-Type distinto de `application/xml`

POST /api/v1/creaycrece/invoices/structured

Recibe una factura en JSON estructurado siguiendo el modelo Invoice del broker, la transforma a UBL 2.1, ejecuta schematron EN 16931 y encola el trabajo de envío a la SPFE.

Cabeceras

Cabecera	Valor
X-API-Key	Clave de empresa (obligatorio)
Content-Type	`application/json`
X-Skip-Validation	`true` para omitir schematron (opcional)

Cuerpo (JSON)

{
  "series": "F2026",
  "number": "5021",
  "issue_date": "2026-06-08",
  "type_code": "380",
  "currency": "EUR",
  "seller": {
    "name": "Ofimática Digital Soluciones SLU",
    "tax_id": "B88776655",
    "address_line": "Calle Mayor 12",
    "city": "Madrid",
    "postal_code": "28013",
    "country_code": "ES"
  },
  "buyer": {
    "name": "Cliente Ejemplo SA",
    "tax_id": "A12345678",
    "address_line": "Avenida Diagonal 200",
    "city": "Barcelona",
    "postal_code": "08018",
    "country_code": "ES"
  },
  "lines": [
    {
      "line_id": "1",
      "description": "Servicios profesionales",
      "quantity": 10,
      "net_unit_price": 50.00,
      "line_net_amount": 500.00,
      "vat_category": "S",
      "vat_rate": 21.00
    }
  ],
  "payment_means_code": "30",
  "payment_iban": "ES7621000813610123456789",
  "due_date": "2026-07-08",
  "is_copy": false
}

Respuesta exitosa (202 Accepted)

{
  "job_id": 4521,
  "status": "PENDING",
  "unique_code": "B88776655-F2026-5021",
  "validated": true
}

Errores

HTTP	Cuándo ocurre
401	Falta cabecera `X-API-Key`
403	API Key inválida
409	Duplicado (mismo `unique_code`)
422	Validación schematron EN 16931 falló (incluye `findings` en el cuerpo)

POST /api/v1/creaycrece/invoices/facturae

Acepta un documento Facturae 3.2.x directamente. El broker realiza el mapeo a UBL 2.1, lanza la validación schematron y encola el envío.

Cabeceras

Cabecera	Valor
X-API-Key	Clave de empresa (obligatorio)
Content-Type	`application/xml`

Cuerpo

XML Facturae 3.2.x crudo (sin firmar o firmado XAdES).

Respuesta exitosa (202 Accepted)

{
  "job_id": 4522,
  "status": "PENDING",
  "unique_code": "B88776655-F2026-5022",
  "validated": true,
  "source_format": "facturae-3.2.x"
}

Errores

HTTP	Cuándo ocurre
400	Facturae mal formado o no soportado
409	Duplicado
422	Validación EN 16931 falló tras el mapeo

POST /api/v1/creaycrece/invoices/sync

Canal síncrono: ejecuta validación, transmisión a SPFE y devuelve directamente en la respuesta HTTP el CSV de aceptación y el código de respuesta. Útil para flujos interactivos donde no se quiere consumir el callback.

Cabeceras

Cabecera	Valor
X-API-Key	Clave de empresa (obligatorio)
Content-Type	`application/json`

Cuerpo (JSON)

Mismo modelo Invoice que /invoices/structured.

Respuesta exitosa (200 OK)

{
  "job_id": 4523,
  "status": "VALIDATED",
  "unique_code": "B88776655-F2026-5023",
  "accepted": true,
  "csv": "ABCD1234EFGH5678",
  "response_code": "0",
  "description": "Aceptada por SPFE"
}

Errores

HTTP	Cuándo ocurre
422	Validación schematron falló (no se transmite)
502	Transporte SOAP a SPFE falló (red, timeout o servicio caído)

Incidencias y contingencia SPFE

El artículo 5.6 del RD 238/2026 permite declarar una incidencia técnica con la SPFE que abre una ventana de subsanación de 4 días durante la cual los reintentos se reanchorian al momento de la subsanación.

POST /api/v1/creaycrece/incidents/subsanate

Marca la subsanación de la incidencia técnica, reanclando la ventana de 4 días y reagendando todas las facturas y pagos en estado PENDING_RETRY. Puede aplicarse a una empresa concreta o de forma global a todas.

Cabeceras

Cabecera	Valor
X-Admin-Token	Si está configurado `DASHBOARD_TOKEN` (obligatorio en ese caso)
Content-Type	`application/json`

Cuerpo (JSON)

{
  "company_id": 17,
  "window_days": 4,
  "notes": "Restablecido servicio SPFE tras incidencia AEAT del 2026-06-08."
}

Respuesta exitosa (200 OK)

{
  "subsanated_at": "2026-06-08T10:42:11Z",
  "contingency_until": "2026-06-12T10:42:11Z",
  "window_days": 4,
  "invoices_rescheduled": 23,
  "payments_rescheduled": 5,
  "scope": "company",
  "company_id": 17
}

Errores

HTTP	Cuándo ocurre
401	Falta `X-Admin-Token` cuando es obligatorio
404	`company_id` no encontrado

Autorizaciones (Apoderamiento / Colaboración Social)

Gestión de las autorizaciones vigentes que permiten al broker actuar en nombre del obligado tributario, ya sea bajo régimen de apoderamiento (representación) o de colaboración social (acuerdo AEAT).

PUT /api/v1/creaycrece/authorizations

Upsert de la autorización vigente para una empresa. Si ya existe una autorización del mismo tipo, se sustituye.

Cabeceras

Cabecera	Valor
X-Admin-Token	Obligatorio
Content-Type	`application/json`

Cuerpo (JSON)

{
  "company_id": 17,
  "kind": "APODERAMIENTO",
  "scope": "VERIFACTU,CREAYCRECE_OUT,CREAYCRECE_IN",
  "granted_at": "2026-06-08",
  "valid_until": "2028-06-08",
  "aeat_reference": "APO-2026-00012345"
}

kind admite APODERAMIENTO o COLABORACION_SOCIAL. scope es CSV con uno o varios de VERIFACTU, CREAYCRECE_OUT, CREAYCRECE_IN.

Respuesta exitosa (200 OK)

{
  "authorization_id": 42,
  "company_id": 17,
  "kind": "APODERAMIENTO",
  "scope": "VERIFACTU,CREAYCRECE_OUT,CREAYCRECE_IN",
  "granted_at": "2026-06-08",
  "valid_until": "2028-06-08",
  "aeat_reference": "APO-2026-00012345"
}

GET /api/v1/creaycrece/authorizations/{company_id}

Devuelve la autorización vigente de la empresa. Responde 404 si no existe.

Respuesta exitosa (200 OK)

{
  "authorization_id": 42,
  "company_id": 17,
  "kind": "APODERAMIENTO",
  "scope": "VERIFACTU,CREAYCRECE_OUT,CREAYCRECE_IN",
  "granted_at": "2026-06-08",
  "valid_until": "2028-06-08",
  "revoked": false
}

Errores

HTTP	Cuándo ocurre
404	Empresa sin autorización vigente

POST /api/v1/creaycrece/authorizations/{company_id}/revoke

Marca la autorización vigente como revocada (cese de la representación).

Cabeceras

Cabecera	Valor
X-Admin-Token	Obligatorio

Respuesta exitosa (200 OK)

{
  "authorization_id": 42,
  "company_id": 17,
  "revoked": true,
  "revoked_at": "2026-06-08T11:05:22Z"
}

Flujo de firma de apoderamiento

Proceso digital en tres pasos para generar y firmar el documento de apoderamiento con OTP por SMS y firma manuscrita en imagen. Al completarse, se emite automáticamente la Authorization correspondiente.

POST /api/v1/creaycrece/apoderamiento/{company_id}/draft

Genera el PDF borrador del documento de apoderamiento para revisión del representante.

Cuerpo (JSON)

{
  "scope": "VERIFACTU,CREAYCRECE_OUT,CREAYCRECE_IN",
  "valid_until": "2028-06-08"
}

Respuesta exitosa (200 OK)

Cuerpo binario PDF con cabecera Content-Type: application/pdf.

POST /api/v1/creaycrece/apoderamiento/{company_id}/otp/send

Envía un código OTP al teléfono del representante para autorizar la firma.

Cuerpo (JSON)

{
  "phone": "+34600123456"
}

Respuesta exitosa (200 OK)

{
  "company_id": 17,
  "phone": "+34600123456",
  "sent": true,
  "ttl_seconds": 300,
  "otp_code": "482910"
}

otp_code solo se devuelve cuando la variable de entorno DEBUG_RETURN_OTP=true. En producción nunca viaja en la respuesta.

POST /api/v1/creaycrece/apoderamiento/{company_id}/sign

Verifica el OTP, aplica la firma manuscrita al PDF y emite la autorización en BD.

Cuerpo (JSON)

{
  "otp_code": "482910",
  "signature_image_b64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "scope": "VERIFACTU,CREAYCRECE_OUT,CREAYCRECE_IN",
  "valid_until": "2028-06-08"
}

Respuesta exitosa (200 OK)

{
  "company_id": 17,
  "authorization_id": 42,
  "scope": "VERIFACTU,CREAYCRECE_OUT,CREAYCRECE_IN",
  "granted_at": "2026-06-08",
  "valid_until": "2028-06-08",
  "signed_pdf_path": "/storage/apoderamientos/17/2026-06-08_signed.pdf"
}

Errores

HTTP	Cuándo ocurre
400	OTP incorrecto, expirado o ya consumido
404	No existe borrador previo para la empresa

Gestión de empresas (CRUD)

Operaciones administrativas sobre el catálogo de empresas registradas en el broker. Todas las operaciones de escritura requieren X-Admin-Token.

GET /api/v1/companies

Lista todas las empresas registradas. Todas las operaciones de este bloque (lecturas incluidas) requieren credencial de administración (sesión del panel o X-Admin-Token); las API keys nunca aparecen en claro, sólo su pista api_key_hint.

Respuesta exitosa (200 OK)

[
  {
    "id": 17,
    "nif": "B88776655",
    "name": "Ofimática Digital Soluciones SLU",
    "api_key_hint": "ddv_kJ8w…Qsg4",
    "aeat_env": "TEST",
    "service_verifactu": 1,
    "service_creaycrece": 1,
    "invoice_count": 112
  }
]

POST /api/v1/companies

Alta o upsert (por NIF) de empresa. Si el NIF ya existe se actualizan sus campos.

Cabeceras

Cabecera	Valor
X-Admin-Token	Obligatorio
Content-Type	`application/json`

Cuerpo (JSON)

{
  "nif": "B88776655",
  "name": "Ofimática Digital Soluciones SLU",
  "cert_name": "B88776655.p12",
  "callback_url": "https://erp.cliente.com/hooks/verifactu",
  "aeat_env": "TEST",
  "service_verifactu": true,
  "service_creaycrece": true,
  "address": "Calle Mayor 12, 28013 Madrid",
  "rep_name": "Luis López",
  "rep_dni": "12345678Z",
  "rep_role": "Administrador único",
  "erp_name": "Digitaldocu ERP",
  "erp_version": "2026.06",
  "dr_email": "facturacion@cliente.com",
  "dr_phone": "+34600123456"
}

Respuesta exitosa (200 OK)

{
  "success": true,
  "message": "Configuración de empresa guardada.",
  "api_key": "ddv_kJ8…(sólo en altas nuevas — se muestra UNA única vez)",
  "api_key_shown_once": true
}

La api_key la genera el servidor y sólo aparece en la respuesta del alta (o de POST /api/v1/companies/{company_id}/regenerate-key). Guárdela en ese momento: el Broker no la almacena en claro y no puede volver a mostrarla.

PUT /api/v1/companies/{company_id}

Actualiza la ficha por ID. Soporta cambio de NIF: si el NIF cambia, el broker migra automáticamente todos los unique_code de las facturas Crea y Crece asociadas para preservar la trazabilidad.

Cabeceras

Cabecera	Valor
X-Admin-Token	Obligatorio
Content-Type	`application/json`

Cuerpo (JSON)

Mismo modelo CompanyConfig que el endpoint POST /companies.

Respuesta exitosa (200 OK)

{
  "success": true,
  "company_id": 17,
  "nif_changed": true,
  "old_nif": "B88776600",
  "migrated_invoices": 134
}

Errores

HTTP	Cuándo ocurre
404	`company_id` no encontrado
409	El nuevo NIF ya está en uso por otra empresa

POST /api/v1/companies/{company_id}/certificate

Sube el certificado de firma de la empresa en formato PKCS#12 (.p12 / .pfx).

Cabeceras

Cabecera	Valor
X-Admin-Token	Obligatorio
Content-Type	`multipart/form-data`

Cuerpo (multipart)

Campo	Tipo	Descripción
file	file	Archivo binario .p12 o .pfx
password	string	Contraseña del PKCS#12

Respuesta exitosa (200 OK)

{
  "success": true,
  "company_id": 17,
  "cert_subject": "CN=Ofimatica Digital, O=ODSL, C=ES",
  "valid_until": "2028-03-15"
}

GET /api/v1/companies/{company_id}/declaraciones

Devuelve el estado y los datos de las Declaraciones Responsables (Modelos A y B) de la empresa.

Respuesta exitosa (200 OK)

{
  "company_id": 17,
  "modelo_a": {
    "signed": true,
    "signed_at": "2026-05-12T09:00:00Z",
    "pdf_path": "/storage/dr/17/modelo_a.pdf"
  },
  "modelo_b": {
    "signed": false,
    "pending_since": "2026-06-01"
  }
}

Cotejo AEAT y monitorización

Endpoints de consulta para imprimir el QR de cotejo en la factura, inspeccionar los XML SOAP enviados / recibidos, leer la cola y los logs de auditoría, y verificar la integridad de la cadena de huellas SHA-256.

GET /api/v1/invoices/{invoice_id}/cotejo

Devuelve la URL pública de cotejo AEAT y el QR PNG (codificado en data URI). Útil para imprimir el QR en la factura entregada al cliente.

Respuesta exitosa (200 OK)

{
  "invoice_id": 4921,
  "aeat_env": "TEST",
  "url": "https://prewww2.aeat.es/wlpl/SSII-FACT/VAL/SiiFactAlta?nif=B88776655&num=4921&fec=2026-06-08&imp=121.00",
  "qr_data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "csv": "ABCD1234EFGH5678"
}

La URL apunta a prewww2.aeat.es cuando la empresa está en aeat_env=TEST y a www2.agenciatributaria.gob.es en PROD.

GET /api/v1/invoices

Lista facturas. Acepta el parámetro opcional ?company_id=N para filtrar.

Respuesta exitosa (200 OK)

[
  {
    "invoice_id": 4921,
    "company_id": 17,
    "series": "F2026",
    "number": "1002",
    "date": "2026-06-08",
    "amount": 121.00,
    "status": "VALIDATED"
  }
]

GET /api/v1/invoices/{invoice_id}

Detalle completo de una factura.

Cabeceras

Cabecera	Valor
X-API-Key	Obligatorio

Respuesta exitosa (200 OK)

{
  "invoice_id": 4921,
  "company_id": 17,
  "series": "F2026",
  "number": "1002",
  "date": "2026-06-08",
  "amount": 121.00,
  "tax": 21.00,
  "type": "F1",
  "status": "VALIDATED",
  "aeat_response_code": "0",
  "huella_digital_sha256": "8F3A2290B551C...F012A",
  "previous_huella_sha256": "1D04A...C0CA",
  "csv": "ABCD1234EFGH5678"
}

GET /api/v1/invoices/{invoice_id}/xml/request

Devuelve el XML SOAP enviado a la AEAT para esta factura. Cabecera Content-Type: application/xml.

GET /api/v1/invoices/{invoice_id}/xml/response

Devuelve el XML SOAP de respuesta recibido de la AEAT.

GET /api/v1/logs?company_id=N

Event log / auditoría de la empresa indicada.

Respuesta exitosa (200 OK)

[
  {
    "log_id": 9921,
    "company_id": 17,
    "timestamp": "2026-06-08T10:42:11Z",
    "event": "INVOICE_VALIDATED",
    "invoice_id": 4921,
    "detail": "Aceptado con éxito en VERI*FACTU"
  }
]

GET /api/v1/queue/stats

Contadores actuales de la cola de procesamiento.

Respuesta exitosa (200 OK)

{
  "pending": 12,
  "processing": 3,
  "validated": 1582,
  "rejected": 4
}

POST /api/v1/system/audit?company_id=N

Lanza una auditoría de integridad de la cadena de huellas SHA-256 de las facturas de la empresa. Detecta saltos, huellas rotas o registros faltantes.

Cabeceras

Cabecera	Valor
X-Admin-Token	Obligatorio

Respuesta exitosa (200 OK)

{
  "healthy": true,
  "status": "healthy",
  "message": "Cadena de huellas íntegra. 1582 registros verificados.",
  "counts": {
    "total": 1586,
    "validated": 1582
  },
  "rejected_count": 4,
  "pending_count": 0,
  "details": []
}

status puede tomar los valores healthy, warning, broken o no_data. Cuando healthy=false, details[] describe los huecos o discrepancias encontradas.