Referencia de la API

Integra la facturación electrónica Veri*Factu en tu ERP o plataforma B2B. Nosotros calculamos la criptografía, firmamos el XAdES y nos comunicamos con Hacienda. Tú solo envías un JSON.

Postman Collection OpenAPI Spec

1. Entornos y Autenticación

Nuestra API utiliza tokens Bearer. Puedes generar tus claves en la sección de API keys y Entornos. Dispones de dos entornos principales:

Sandbox (Pruebas)

POST /api/v1/sandbox/invoices

Valida esquemas matemáticos y estructuras XML sin conectar con la AEAT real ni requerir un certificado electrónico real en la bóveda.

Producción (Veri*Factu)

POST /api/v1/invoices

Reporta directamente a Hacienda. Requiere de forma obligatoria que tu Certificado esté sellado en la bóveda criptográfica.

¿No sabes cómo obtener tu certificado PEM?

Transforma de manera segura el archivo .pfx de la FNMT para integrarlo en el Vault.

Ver Guía

2. Emisión de Factura (Request)

Para emitir una factura, envía una petición POST. A continuación tienes ejemplos listos para producción en tus lenguajes favoritos:

const axios = require('axios');

async function enviarFactura() {
  try {
    const response = await axios.post('https://axiomaq-api.vercel.app/api/v1/invoices', {
      tipo_factura: "F1",
      serie: "F", 
      fecha_emision: "2026-05-30",
      external_id: "ORD-998811",
      cliente: { nif: "B12345678", nombre: "Empresa Cliente SL" },
      conceptos: [ { descripcion: "Integración VERIFACTU", importe: 100.00, iva: 21 } ]
    }, {
      headers: { 'Authorization': 'Bearer aq_live_TU_API_KEY' }
    });

    const { csv, qr_url } = response.data.data.sif;
    console.log("Factura aceptada con CSV:", csv);
  } catch (error) {
    console.error("Error fiscal:", error.response.data);
  }
}

3. Diccionario de Datos (JSON Schema)

Parámetros aceptados en el cuerpo (Body) de tu petición POST. Los cálculos de IVA, bases imponibles y desglose de céntimos los realiza nuestro motor fiscal de forma automática.

Librería de Payloads

Parámetro	Tipo	Requerido	Descripción / Valores Aceptados
tipo_factura	String	Opcional	Por defecto es `F1`. Acepta: `F1` (Completa), `F2` (Ticket simplificado), y de `R1` a `R5` (Abonos/Rectificativas).
serie	String	Sí	Serie y numeración de la factura (Ej: `INV-`, `2026/`). Máximo 20 caracteres.
fecha_emision	String	Sí	Formato estándar ISO `YYYY-MM-DD`.
external_id	String	Opcional	ID interno de tu ERP/Tienda (Ej. order_123). Recomendado para idempotencia y trazabilidad.
cliente.nif	String	Para F1/Rx	NIF/CIF del receptor. Obligatorio si tipo_factura es F1, o de R1 a R4. Opcional para tickets F2 y R5.
conceptos	Array[Obj]	Sí	Lista de artículos con `descripcion`, `importe` (base sin iva) y el `iva` (int: 0, 4, 10, 21).
factura_rectificada	Object	Para Rx	Estructura requerida para abonos. Requiere `numero` y la `fecha_emision` original.

4. Respuesta y Trazabilidad (Response)

HTTP 200 OK

{
  "success": true,
  "data": {
    "invoice_number": "F2026/0001",
    "sif": {
      "mode": "verifactu",
      "status": "aceptado",
      "codigo": "0000",
      "descripcion": "Correcto",
      "qr_url": "https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/...",
      "csv": "A-78LVS89DA8UFV3",
      "huella_hash": "B15B45F40C68584DB134B8...",
      "xml_base64": "PHN1bTpSZWdGYWN0d..."
    }
  }
}

¿Qué debes guardar en tu base de datos?

csv: Código Seguro de Verificación. El dato más importante para certificar la validez de tu factura ante cualquier inspección.
qr_url: URL oficial generada de manera algorítmica para el escaneo directo en la Agencia Tributaria.
status: Controla que el valor sea "aceptado". Si es "rechazado", lee la descripción donde detallamos el motivo fiscal exacto.

Impresión y Maquetación de PDFs

Bajo el marco regulatorio Veri*Factu, es mandatorio adjuntar un código QR en la representación impresa de tu factura. Genera dinámicamente un código QR en tu maquetador apuntando al endpoint exacto recibido en sif.qr_url.

5. Errores, Duplicados e Idempotencia

HTTP Code	Motivo Común	Comportamiento / Solución
200 OK (Código 3000)	Factura Duplicada	Idempotencia absoluta. Si por un microcorte de red reenvías la misma numeración, la AEAT devuelve el código 3000. Nuestra API intercepta este estado y te devuelve el CSV original de forma segura sin provocar un duplicado erróneo.
200 OK (Rechazado)	Rechazo directo de Hacienda.	La petición es correcta tecnológicamente, pero Hacienda ha bloqueado la factura por errores de negocio. El motivo explícito aparecerá traducido y detallado en el parámetro `sif.descripcion` (Ej. NIF no censado).
400 Bad Request	Fallo de Validación Local.	Nuestra API bloqueó la petición antes de enviarla a los servidores de Hacienda al detectar inconsistencias de formato en los campos obligatorios o tipos de IVA no soportados legalmente.
401 Unauthorized	Autenticación Inválida.	Tu Bearer token es incorrecto, no tiene suficientes permisos, o ha sido revocado desde el panel de control del Dashboard.