VeriFactu

Alta, subsanación y anulación de registros VeriFactu. El contrato completo.

Los endpoints VeriFactu remiten registros de facturación a la AEAT. Base URL: https://sandbox.veribai.com (Sandbox) o https://api.veribai.com (LIVE), con autenticación x-api-key.

El alta es síncrona y la remisión asíncrona: la petición valida, firma y encola el registro, y devuelve el QR en el momento. El envío a la AEAT se completa en segundo plano. Síguelo con GET /v1/facturas/{idFactura}/estado o recíbelo por webhook.

En LIVE, todas las operaciones exigen que el emisor tenga su representación firmada; en caso contrario devuelven 403 REPRESENTATION_PENDING. En Sandbox no se exige.

POST /v1/verifactu/crear

curl -X POST https://sandbox.veribai.com/v1/verifactu/crear \
  -H "x-api-key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "cabecera": {
      "serie": "A",
      "numero": "12345",
      "fechaExpedicion": "03-04-2026",
      "tipoFactura": "F1",
      "descripcion": "Servicios de consultoría"
    },
    "emisor": {
      "nif": "B00000000",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B11111119",
      "nombre": "Nombre cliente, SL"
    },
    "detalleDesglose": [
      {
        "impuesto": "01",
        "claveRegimen": "01",
        "calificacionOperacion": "S1",
        "baseImponible": "100.00",
        "tipoImpositivo": "21.00",
        "cuotaRepercutida": "21.00"
      }
    ],
    "totales": {
      "cuotaTotal": "21.00",
      "importeTotal": "121.00"
    }
  }'

from datetime import date
from decimal import Decimal

import veribai

client = veribai.Client(api_key="TU_CLAVE", environment="test")

respuesta = client.verifactu.crear({
    "version": "1.0",
    "cabecera": {
        "serie": "A",
        "numero": "12345",
        "fechaExpedicion": date(2026, 4, 3),
        "tipoFactura": "F1",
        "descripcion": "Servicios de consultoría",
    },
    "emisor": {
        "nif": "B00000000",
        "nombre": "Prueba 1 SL",
    },
    "destinatario": {
        "nif": "B11111119",
        "nombre": "Nombre cliente, SL",
    },
    "detalleDesglose": [
        {
            "impuesto": "01",
            "claveRegimen": "01",
            "calificacionOperacion": "S1",
            "baseImponible": Decimal("100.00"),
            "tipoImpositivo": Decimal("21.00"),
            "cuotaRepercutida": Decimal("21.00"),
        },
    ],
    "totales": {
        "cuotaTotal": Decimal("21.00"),
        "importeTotal": Decimal("121.00"),
    },
})
print(respuesta["idFactura"], respuesta["estado"])

const respuesta = await fetch("https://sandbox.veribai.com/v1/verifactu/crear", {
  method: "POST",
  headers: {
    "x-api-key": "TU_CLAVE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "version": "1.0",
    "cabecera": {
      "serie": "A",
      "numero": "12345",
      "fechaExpedicion": "03-04-2026",
      "tipoFactura": "F1",
      "descripcion": "Servicios de consultoría"
    },
    "emisor": {
      "nif": "B00000000",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B11111119",
      "nombre": "Nombre cliente, SL"
    },
    "detalleDesglose": [
      {
        "impuesto": "01",
        "claveRegimen": "01",
        "calificacionOperacion": "S1",
        "baseImponible": "100.00",
        "tipoImpositivo": "21.00",
        "cuotaRepercutida": "21.00"
      }
    ],
    "totales": {
      "cuotaTotal": "21.00",
      "importeTotal": "121.00"
    }
  }),
});

if (!respuesta.ok) throw new Error(`VeriBai ${respuesta.status}`);
const datos = await respuesta.json();

{
  "nifEmisor": "B00000000",
  "idFactura": "…",
  "estado": "pendiente_proceso",
  "numSerieFactura": "A12345",
  "serie": "A",
  "numero": "12345",
  "tipoFactura": "F1",
  "importeTotal": "121.00",
  "cuotaTotal": "21.00",
  "creadoEn": "2026-04-03T10:00:00Z",
  "urlValidacion": "https://…",
  "qrBase64": "…"
}

El registro queda validado, firmado y encolado. Guarda idFactura: es la clave para consultar estado, QR y XML. avisos, cuando aparece, lista avisos de validación no bloqueantes.

Los duplicados son idempotentes: reenviar un alta con la misma identidad (emisor, serie, número, fecha) devuelve 200 con el registro ya existente, no un error. La repetición lleva "yaExistente": true, estado trae el valor de ciclo de vida (registrada, anulada o rectificada) y el QR se regenera. yaExistente: true indica que VeriBai ya tenía esa factura y no ha creado nada; en una factura nueva el campo no aparece.

Campos

Tipos y formato del cuerpo

La validación ocurre antes de construir el XML: un dato mal formado responde 400 de inmediato, sin llegar a firmarse.

• cabecera.serie y cabecera.numero admiten solo ASCII imprimible: letras sin acentos, dígitos y puntuación ASCII. A/2026, A 26, A#1 y A-B_C.D son válidos. Ñ, cualquier acento o € devuelven 400 nombrando el campo, con la regla AEAT 1130, la misma que aplica la AEAT a un NumSerieFactura no ASCII.
• totales.importeTotal no puede ser negativo en F1, F2 ni F3: los importes negativos corresponden a las rectificativas R1–R5. -0.00 no cuenta como negativo.
• En las referencias de rectificativa.facturasRectificadas y facturasSustituidas, serie y numero suman 60 caracteres como máximo (el TextoIDFacturaType de la especificación, el mismo límite que el número de la propia factura).
• Los campos de texto no pueden contener caracteres de control ilegales en XML, ni entidades XML o HTML ya codificadas (<, �, &…). El escapado del XML lo hace la API, así que ese texto es una doble codificación y devuelve 400 nombrando el campo. Un & suelto dentro de un nombre (Tom & Jerry) es correcto.
• En simplificadas F2 rige el tope de 3.000 € de la regla AEAT 1150. Ver el tope de las simplificadas.
• VeriFactu no tiene lineas: el desglose fiscal va en detalleDesglose y no existe un bloque de líneas de detalle en el esquema de la AEAT. Una clave lineas se ignora. Las líneas de detalle existen solo en TicketBAI.

El tope de las simplificadas F2

La regla AEAT 1150 limita las simplificadas F2 a 3.000 €. La API la comprueba en el alta.

facturaSinIdentifDestinatarioArt61d es la cadena "S", no un booleano. true devuelve 400 por tipo de campo, no por el tope. "N" deja la factura sujeta al tope.

Supuestos especiales

El bloque especial recoge los indicadores opcionales del registro de alta. Todos se transmiten a la AEAT.

Los indicadores son las cadenas "S" y "N", no booleanos. "N" equivale a omitir el campo. Un "S" en un tipo de factura no admitido devuelve 400 nombrando el campo.

Macrodato no es un campo: se declara automáticamente cuando el valor absoluto de totales.importeTotal alcanza 100.000.000 €.

Destinatario extranjero

Un destinatario sin NIF español se identifica con destinatario.idOtro en lugar de nif. Enviar nif e idOtro a la vez devuelve 400.

"destinatario": {
  "nombre": "Kunde GmbH",
  "idOtro": { "codigoPais": "DE", "idType": "02", "id": "DE123456789" }
}

El formato de identificación de cada país lo comprueba la AEAT: un id que no corresponde al país vuelve como registro rechazado.

Una entrega intracomunitaria exenta (operacionExenta: "E5" con IVA) exige un destinatario con idOtro.

Claves por impuesto

Las claves admitidas en cada línea de detalleDesglose dependen de impuesto. Una claveRegimen fuera de la lista de su impuesto devuelve 400.

Un mismo código puede significar cosas distintas según el impuesto: 17 es comerciante minorista en IGIC y OSS/IOSS en IVA.

operacionExenta sustituye a calificacionOperacion: la línea lleva una de las dos, nunca ambas, y una línea exenta no lleva tipo ni cuota.

PUT /v1/verifactu/subsanar

Corrige un registro ya remitido cuando la operación es correcta pero el registro contiene datos mal informados. El cuerpo es el mismo que el de crear, con los datos corregidos. La API marca la subsanación automáticamente.

{
  "nifEmisor": "B00000000",
  "idFactura": "…",
  "estado": "pendiente_proceso",
  "numSerieFactura": "A12345",
  "serie": "A",
  "numero": "12345",
  "tipoFactura": "F1",
  "importeTotal": "121.00",
  "cuotaTotal": "21.00",
  "creadoEn": "2026-04-03T12:00:00Z",
  "avisos": [
    "El endpoint /subsanar establece automáticamente subsanacion=true (valor recibido: 'N'). Si necesitas control explícito sobre este campo, usa el endpoint /crear."
  ],
  "urlValidacion": "https://…",
  "qrBase64": "…"
}

La respuesta tiene la misma forma que la del alta. avisos aparece cuando el cuerpo no traía subsanacion: true: la API lo ha fijado por ti y lo dice.

Un campo adicional: rechazoPrevio ("N" por defecto, "S" si la AEAT rechazó el registro original, "X" si el registro no consta en la AEAT). Es el único de estos indicadores que no es booleano: tiene tres estados.

rechazoPrevio pertenece a la subsanación. La AEAT no admite "S" ni "X" en un alta normal. Enviarlos en POST /crear sin marcar subsanacion responde 400 VALIDATION_ERROR nombrando la combinación.

Cuándo subsanar y cuándo emitir rectificativa: Rectificar y anular.

POST /v1/verifactu/anular

Deja sin efecto un registro remitido. El cuerpo identifica la factura original:

curl -X POST https://sandbox.veribai.com/v1/verifactu/anular \
  -H "x-api-key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "facturaAnulada": {
      "nifEmisor": "B00000000",
      "serie": "A",
      "numero": "12345",
      "fechaExpedicion": "03-04-2026"
    }
  }'

from datetime import date

import veribai

client = veribai.Client(api_key="TU_CLAVE", environment="test")

respuesta = client.verifactu.anular({
    "version": "1.0",
    "facturaAnulada": {
        "nifEmisor": "B00000000",
        "serie": "A",
        "numero": "12345",
        "fechaExpedicion": date(2026, 4, 3),
    },
})

const respuesta = await fetch("https://sandbox.veribai.com/v1/verifactu/anular", {
  method: "POST",
  headers: {
    "x-api-key": "TU_CLAVE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "version": "1.0",
    "facturaAnulada": {
      "nifEmisor": "B00000000",
      "serie": "A",
      "numero": "12345",
      "fechaExpedicion": "03-04-2026"
    }
  }),
});

if (!respuesta.ok) throw new Error(`VeriBai ${respuesta.status}`);
const datos = await respuesta.json();

{
  "code": "SUCCESS",
  "message": "Anulación registrada correctamente",
  "data": {
    "nifEmisor": "B00000000",
    "idFactura": "…",
    "estado": "pendiente_envio",
    "numSerieFactura": "A12345",
    "serie": "A",
    "numero": "12345",
    "fechaExpedicion": "03-04-2026",
    "creadoEn": "2026-04-03T11:00:00Z",
    "mensaje": "La anulación ha sido registrada y será procesada para envío a AEAT. …"
  }
}

A diferencia del alta, la respuesta viene envuelta en el sobre { code, message, data }; la remisión a la AEAT es asíncrona y estado arranca en pendiente_envio.

La anulación genera su propio registro encadenado: nada desaparece de la cadena.

Repetir una anulación

Una anulación repetida es un reintento, no una segunda anulación. Si la factura ya tiene una anulación, en cualquier estado salvo rechazada, la respuesta es 200 SUCCESS con esa anulación y data.yaAnulada: true: data.creadoEn y data.estado son los de la anulación existente. No se crea ni se envía nada a la AEAT.

Si la AEAT rechazó la anulación anterior, la petición se acepta como anulación nueva.

El nombre del emisor en la anulación

La AEAT comprueba el NIF y el nombre del emisor juntos; en una persona física, contra el censo. El registro de anulación no lleva nombre, así que la API envía el que declaró el alta en emisor.nombre. Cuando VeriBai tiene ese alta, facturaAnulada.nombreEmisor no hace falta y se ignora si lo envías.

Para una factura que VeriBai no ha visto, normalmente con sinRegistroPrevio: true, envía facturaAnulada.nombreEmisor tal como figura en el censo de la AEAT. Sin él, la respuesta es 400 VALIDATION_ERROR con una entrada en errors que empieza por facturaAnulada.nombreEmisor:, y no se envía nada a la AEAT.

Tipos de factura

Errores

Los códigos comunes a toda la API están en Errores. Específicos de estos endpoints: