Entiende la estructura del JSON de VeriFactu antes de programarla

Si estás integrando VeriFactu en tu software de facturación, tarde o temprano tu sistema tendrá que construir automáticamente, factura a factura, el JSON del registro de facturación que se envía a la AEAT. El problema es que la especificación tiene secciones anidadas, claves con nombres poco intuitivos (S1, 01, F1...) y reglas que cambian según el caso: una factura rectificativa no lleva los mismos campos que una operación intracomunitaria, y un error en el desglose de impuestos puede provocar un rechazo.

Antes de escribir esa lógica en tu código, conviene tener muy claro cómo se ve realmente esa estructura. Para eso creamos el Generador de JSON: un formulario visual que te deja explorar la estructura del registro de facturación campo a campo y ver, en tiempo real, cómo cambia el JSON según los valores que introduces.

Cómo funciona

El generador está organizado en los mismos bloques que exige la especificación de VeriFactu, para que no tengas que ir saltando entre la documentación de la AEAT y el formulario:

• Emisor y tipo de factura. El NIF del emisor y el tipo de factura (por ejemplo, F1 para factura ordinaria).
• Cabecera. Número de serie, referencia externa, quién la emite, fecha de expedición, fecha de la operación y descripción de la operación.
• Destinatarios. Nombre o razón social, si es nacional o internacional, y NIF.
• Desglose. La parte más compleja: tipo de impuesto (01 para IVA), clave de régimen, calificación de la operación (por ejemplo, S1 para sujeta y no exenta), base imponible, tipo impositivo, la cuota repercutida calculada automáticamente y, si aplica, el recargo de equivalencia.

A medida que rellenas cada campo, el JSON se va construyendo en tiempo real a la derecha, así que puedes ver exactamente qué forma toma la estructura para cada caso concreto.

Un ejemplo de lo que verás

Con unos datos de ejemplo, el generador te muestra esto:

{
  "IDEmisorFactura": "B12345678",
  "NumSerieFactura": "FAC/2026-3265",
  "FechaExpedicionFactura": "2026-09-14",
  "TipoFactura": "F1",
  "DescripcionOperacion": "Prestación de servicios",
  "FechaOperacion": "2026-09-14",
  "RefExterna": "26-3265",
  "Destinatarios": [
    {
      "NombreRazon": "Empresa cliente TEST",
      "NIF": "A98765432"
    }
  ],
  "Desglose": [
    {
      "Impuesto": "01",
      "ClaveRegimen": "01",
      "BaseImponibleOImporteNoSujeto": 100,
      "CalificacionOperacion": "S1",
      "TipoImpositivo": 21,
      "CuotaRepercutida": 21,
      "TipoRecargoEquivalencia": 5.2,
      "CuotaRecargoEquivalencia": 5.2
    }
  ],
  "CuotaTotal": 26.2,
  "ImporteTotal": 126.2
}

Ese es el bloque que después viaja, vía nuestra API REST, hasta la AEAT, con nosotros actuando como Colaborador Social autorizado de la Agencia Tributaria, así que ni tú, ni tu cliente final necesitáis instalar certificados digitales para enviar los registros.

Para qué sirve realmente

El generador no está pensado para que generes ahí cada factura que emitas, ya que eso lo hará tu propio sistema, de forma automática, cuando tengas la integración terminada.

El valor de esta herramienta está en la fase previa, porque te deja probar distintos escenarios visualmente;una operación nacional frente a una intracomunitaria, un régimen general frente a uno especial, con o sin recargo de equivalencia. Viendo de inmediato qué campos cambian y de qué manera. Esa exploración es mucho más rápida que ir descifrando la especificación de la AEAT documento en mano, y te da un modelo claro de la estructura que luego tienes que traducir a código, identificando qué campos son obligatorios en cada caso, cómo se relacionan entre sí y qué valores exactos espera cada clave.

La idea es que puedas utilizarlo como mapa antes de programar, no como generador de facturas en producción.

Y cuando ya envíes datos reales, validamos antes de que lo haga la AEAT

Entender la estructura es el primer paso, pero incluso con el JSON bien construido hay reglas de negocio fáciles de pasar por alto. Por ejemplo qué campos son obligatorios según el tipo de factura, qué combinaciones de valores son incompatibles, o qué cálculos tienen que cuadrar entre sí. Por eso, cuando tu sistema empiece a enviar registros de verdad, nuestra API aplica un conjunto de validaciones, tanto las oficiales de Veri*Factu, AEAT y TicketBAI (Araba, Bizkaia, Gipuzkoa) como reglas propias, antes de que el registro llegue a la administración. Así, si algo falla, te enteras antes con un mensaje claro, en lugar de recibir un rechazo de la Agencia Tributaria sobre un registro ya emitido que obligaría a generar una rectificativa.

Algunos ejemplos del tipo de comprobaciones que hacemos:

• Campos obligatorios según el contexto. Por ejemplo, TipoRectificativa es obligatorio si TipoFactura es R1–R5, pero no puede informarse si es F1, F2 o F3.
• Formato de identificadores. El NIF del emisor, del destinatario o de un tercero se valida contra el formato oficial antes de enviarlo; lo mismo con los identificadores fiscales de otros países (cada uno con su propio patrón: 8 números y una letra para España, 11 caracteres alfanuméricos para Francia, etc.).
• Coherencia de importes. La suma de CuotaRepercutida y CuotaRecargoEquivalencia debe coincidir con CuotaTotal (con un margen de 2 céntimos), y lo mismo para ImporteTotal frente a la suma de las líneas del desglose.
• Valores permitidos y dependencias entre campos. TipoImpositivo solo admite los tipos vigentes (0, 2, 4, 5, 7.5, 10 o 21), y algunos de ellos solo son válidos en ventanas de fechas concretas; el TipoRecargoEquivalencia tiene que corresponderse exactamente con el tipo impositivo aplicado.
• Reglas específicas por régimen. Por ejemplo, si ClaveRegimen es 10, todos los destinatarios deben ir identificados por NIF y el tipo de factura tiene que ser F1.

Esta capa de validación es la otra mitad del proceso: el generador te ayuda a entender la forma del JSON, y las validaciones te confirman que lo que tu sistema construye automáticamente cumple las reglas antes de que sea la propia AEAT quien te lo diga.

Pruébalo tú mismo

El Generador de JSON es gratuito y está disponible en verifactuapi.es/generador-json. Una vez tengas claro el modelo de datos, el siguiente paso natural es probar el envío real con nuestro sandbox ilimitado, sin tarjeta ni certificado, para validar tu integración antes de pasar a producción.

Con los plazos ya fijados: enero de 2027 para sociedades y julio de 2027 para autónomos y pymes, cuanto antes entiendas la estructura de datos y sus reglas, antes podrás automatizar su generación en tu sistema sin sorpresas de última hora.