Alta automática en VeriFactu

Quien integra viniendo de otras plataformas de facturación busca la operación que envía una factura a la Administración tributaria, no la encuentra y da por hecho que la funcionalidad falta. No falta: el alta no es un paso que ejecutes tú. El registro se crea como consecuencia de emitir la factura, y lo transmite una tubería en segundo plano.

Esta página responde a «¿por qué mi factura no ha llegado a la AEAT?», que casi siempre es una de las compuertas de abajo y no un fallo.

Cuándo aplica

A toda factura que sale de draft en una empresa cuya activación de VeriFactu es efectiva. En concreto, el alta se crea cuando la factura se emite — incluidas las facturas que nacen ya emitidas: rectificativas, sustitutivas F3, generaciones de recurrentes y creaciones que pasan options.issue_directly. (Antes de la versión de API 2026-10-01 una factura emitida se publica como sent; consulta Versionado.)

La etapa draft queda deliberadamente fuera del mecanismo. Un borrador no tiene número definitivo, ni snapshot congelado del destinatario, ni existencia fiscal; no se declara nada por él.

Las compuertas, en el orden en que se evalúan

Interruptor de emergencia de la instancia. Una bandera global puede desactivar VeriFactu para toda la instalación. Es un interruptor de emergencia, nunca una activación: por sí sola no habilita nada.

Activación por empresa. Esta es la que controlas tú. Viene desactivada de fábrica en una cuenta recién creada — una empresa nueva no da de alta sus facturas hasta que alguien activa VeriFactu. La activación efectiva es instancia Y empresa (BR-VFC-025).

Léela con GET /v1/companies/{company}/verifactu/config: el campo enabled ya es el valor efectivo, no la bandera cruda de la empresa.

Modo de funcionamiento. Con la activación puesta, la empresa aún elige entre transmitir y no transmitir. En modo no_verifactu los registros encadenados se siguen generando y guardando en local — el modo cambia la transmisión, no el encadenamiento — y deben quedar disponibles para inspección, pero no se envía nada en tiempo real (BR-VFC-018, RD 1007/2023 art. 16).

Excepción de la importación histórica. Las facturas cargadas por la importación masiva de histórico previo a la adhesión llevan una marca transitoria que hace que los manejadores de VeriFactu retornen sin crear registro alguno (BR-INV-011, BR-VFC-009). Sin ella, importar años de histórico declararía miles de altas con fechas de expedición anteriores a la incorporación de la empresa al sistema. La marca la fuerza el importador y no se expone en los endpoints ordinarios de creación — no puedes activarla desde la API pública.

Datos del registro válidos. Antes de emitir una factura, Factuarea comprueba que el registro que va a generar cabe en el esquema de la AEAT: un nombre de cliente de como máximo 120 caracteres, un NIF español de 9 caracteres, un número de factura de ASCII imprimible de como máximo 60 caracteres, como mucho 12 desgloses fiscales, importes que quepan en 12 cifras enteras y 2 decimales. Si algo no cabe, la operación responde 422 verifactu_not_eligible con el campo en error.param, la factura no se emite y no se consume número. Se aplica a toda operación que emite una factura y a toda empresa con VeriFactu activado. La tabla de campos está en Facturación desde terminales desatendidos.

Un certificado que pueda presentar o firmar el registro. Lo que hace falta depende del modo:

Modo VERI*FACTU. El certificado que remite los registros autentica la conexión con la AEAT; el registro en sí no se firma. Si no hay un certificado utilizable, o una representación activa en los modos de tercero, la factura sí se emite y su registro se genera, pero nace bloqueado (MISSING_CERTIFICATE o MISSING_REPRESENTATION) y se libera cuando subes el certificado o registras la representación. Consulta Registros bloqueados.
Modo NO VERI*FACTU con VeriFactu activado. Cada registro se firma, y un registro solo cuenta como generado cuando está firmado. Sin un certificado de firma utilizable, la operación que lo generaría se rechaza antes de ejecutarse: emitir, y también anular, responden 422 verifactu_not_eligible con subcode: signing_certificate_unavailable y error.param certificate, representation o system_certificate. La factura queda como estaba. Afecta a las ocho operaciones que emiten o anulan (create con options, issue, send, mark-sent, corrective, substitute-simplified, annul y void); can-annul te lo anticipa.
VeriFactu desactivado. No cambia nada: una empresa que no ha activado VeriFactu emite y anula sin certificado, aunque su modo por defecto sea no_verifactu.

Comprueba has_active_certificate y presenter_certificate_status en el endpoint de configuración antes de salir a producción.

Si pasan las seis, el registro se crea, se encadena y se encola para transmitir. Que la cola transmita automáticamente es a su vez un ajuste de instancia, expuesto en solo lectura como auto_transmit en el endpoint de configuración.

Qué envía la API

Nada que escribas tú. No hay cuerpo de petición para «enviar», ni ningún campo en POST /v1/companies/{company}/invoices que decida si se crea un alta. Lo que sí controlas es cuándo se emite la factura, y de ahí se deriva todo lo demás:

Crea la factura como borrador y luego emítela con POST /v1/companies/{company}/invoices/{id}/send o POST /v1/companies/{company}/invoices/{id}/mark-sent.
O créala y emítela de forma atómica pasando options.issue_directly en la llamada de creación.
O, desde un terminal que necesita el QR en la misma respuesta, pasa options.register_verifactu: el alta se genera de forma síncrona, antes de responder, y la respuesta lleva su huella y su QR. Si no se puede generar (sin certificado, sin representación, reloj desfasado) la factura queda emitida y el bloque responde status: failed; repetir el mismo external_id la completa. Consulta Facturación desde terminales desatendidos.

Como el camino de «crear y emitir en una sola llamada» emite a la vez un evento de creación y uno de emisión, dos manejadores compiten por crear la misma alta. El comando es idempotente por factura: el segundo detecta el alta existente y no hace nada en silencio, de modo que existe exactamente un registro por factura (BR-VFC-008). No necesitas deduplicar por tu lado.

La única vía de escape explícita

Sí existe una operación que fuerza la creación de un alta para una factura ya emitida: POST /v1/companies/{company}/invoices/{id}/verifactu, scope verifactu:write. Crea el alta y encola su transmisión, respondiendo 201 con el registro nuevo.

Existe para el caso en que una factura se emitió con una compuerta cerrada —un certificado que todavía no se había subido, por ejemplo— y quieres el alta en cuanto la compuerta se abre. No es un reenvío:

Situación	Respuesta
La factura ya tiene un alta	`422` `verifactu_already_submitted`
La factura sigue en borrador, VeriFactu está desactivado en la instancia, o el certificado falta, está caducado, revocado o con NIF que no casa	`422` `verifactu_not_eligible`
La factura no existe, o pertenece a otra empresa	`404` `invoice_not_found`

curl -X POST https://api.factuarea.com/v1/companies/{company}/invoices/0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42/verifactu \
  -H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW"

Las únicas palancas manuales sobre un registro que ya existe

Creada el alta, exactamente tres operaciones actúan sobre ella, y todas se explican en Estados de envío VeriFactu:

retry — programa el lote de la empresa para que un registro fallido salga en él, para fallos técnicos. No hay límite de intentos.
retry-blocked — reactiva de una vez todos los registros bloqueados de la empresa, después de que hayas resuelto lo que los bloqueaba. Responde 202 con data.reactivated.
subsanar — genera un registro nuevo que corrige uno aceptado o uno rechazado; el original nunca se edita.

No existe operación que retransmita un registro aceptado ni que lo edite en su sitio. La aceptación es terminal para ese registro por norma; un error de datos en él se corrige con un registro nuevo (subsanar), o con una factura rectificativa cuando las reglas de facturación la exigen.

Cómo llegan los registros a la AEAT

La remisión sigue el artículo 16 de la Orden HAC/1177/2024. No la gobiernas tú, pero explica lo que verás en un registro y en las estadísticas.

Lotes, en orden. Los registros de una empresa se envían juntos, sin mezclarlos nunca con los de otra, hasta 1.000 por envío y siempre en el orden de la cadena: un registro nunca adelanta a uno anterior. Solo hay un envío en vuelo por empresa.
Tiempo de espera. En cada respuesta la AEAT indica cuánto esperar antes del siguiente envío (TiempoEsperaEnvio). Factuarea lo respeta (60 segundos si la AEAT no ha indicado ninguno), salvo que ya haya 1.000 registros esperando. Un registro creado dentro de la ventana espera al siguiente envío.
Respuesta por registro. Aceptado, aceptado con errores (el registro queda aceptado, con un aviso) o rechazado. El error 3000 de la AEAT, «registro duplicado», cuenta como confirmación de que la AEAT lo recibió.
Reintentos sin tope. Si un envío no obtiene respuesta, obtiene un fallo de servidor o falla la red, sus registros siguen pendientes, marcados como incidencia (Incidencia=S en el siguiente envío), y se reintentan con intervalos crecientes —1, 5, 15, 30 minutos y después cada 55— de modo que nunca pase más de una hora entre dos intentos, sin número máximo de intentos, mientras dure la incidencia. Los registros generados entretanto esperan detrás de los anteriores.
Aviso de pendientes. GET /v1/companies/{company}/verifactu/stats informa de pending_incident_count (registros que aún esperan llegar a la AEAT), blocked_incident_count (de esos, los bloqueados) y oldest_pending_at. Los filtros de la consulta no los afectan. La aplicación muestra el mismo aviso, y el correo de resumen diario lo incluye.
Un registro que no cabe en el esquema se genera rejected con aeat_error_code: SCHEMA_INVALID y nunca se envía: la AEAT rechaza un envío entero cuando un registro incumple su esquema, así que se detecta antes. Lo corriges con una subsanar, y no detiene el resto de la cadena.
Las empresas de prueba (claves fact_test_) nunca remiten.

Registros bloqueados

Un registro en error sin reintento automático está bloqueado: algo necesita tu acción, no se reintenta solo y detiene los registros que van detrás. El registro lo indica con is_blocked: true y la causa en block_reason:

`block_reason`	Qué falta
`MISSING_CERTIFICATE`	La empresa no tiene un certificado utilizable (ausente, caducado, revocado o de otro NIF).
`MISSING_REPRESENTATION`	El modo es de tercero y no hay una representación activa del tipo que necesita.
`PRESENTER_NOT_ENABLED`	La AEAT dice que el presentador no está habilitado (`4112` o `3003`).
`SUBMISSION_REJECTED`	La AEAT rechazó el envío por un fallo del lado del cliente.

aeat_error_code lleva el último código de la AEAT (o el interno). Una quinta causa, SYSTEM_CERTIFICATE_UNAVAILABLE (el certificado de Factuarea en los modos de tercero), es del lado de Factuarea: no bloquea y el registro se reintenta solo.

Resolver la causa libera los registros por sí solo: subir o activar un certificado, registrar una representación o cambiar el modo reactiva lo que ese suceso puede liberar. Para liberarlos todos a mano, llama a retry-blocked.

Remitir a través de Factuarea: los modos de tercero

Por defecto cada empresa remite con su propio certificado. Una empresa puede, en cambio, autorizar a Factuarea a remitir en su nombre, para no entregar su certificado. El modo es remission_mode, que se lee en GET /v1/companies/{company}/verifactu/config y se cambia con PATCH /v1/companies/{company}/verifactu/settings:

`remission_mode`	Quién remite	Representación necesaria
`own_certificate` (por defecto)	La empresa, con su certificado.	Ninguna.
`social_collaborator`	Factuarea, como colaborador social.	El anexo I firmado de la Resolución de 18-12-2024 (`social_collaboration_annex_i`).
`power_of_attorney`	Factuarea, al amparo de un apoderamiento.	Un apoderamiento inscrito en la AEAT (`aeat_power_of_attorney`).

social_collaborator solo está disponible mientras el acuerdo de colaboración social con la AEAT esté en vigor en la instancia: comprueba social_collaborator_available. Hasta entonces, power_of_attorney cubre el mismo caso.

La representación se registra con POST /v1/companies/{company}/verifactu/representation (multipart/form-data: kind, signer_name, signer_tax_id, granted_on, el PDF document o, para un apoderamiento, power_of_attorney_reference, y un valid_until opcional), se lee con GET y se revoca con DELETE (reason opcional de 3 a 500 caracteres). Conviene saber:

Solo hay una representación vigente. Registrar otra revoca la anterior, que se conserva en el historial; el documento firmado se custodia cifrado y nunca se devuelve. Revocar es definitivo y devuelve la empresa a own_certificate.
Vigencia. valid_until es el último día (hora de Madrid) y no puede superar cinco años desde granted_on. Se te avisa 30 y 7 días antes y al caducar. Una representación caducada se sigue devolviendo (is_expired: true) pero ya no habilita la remisión: los registros nuevos quedan bloqueados con MISSING_REPRESENTATION hasta que registres otra.
El modo sigue a la representación. Registrar una representación del otro tipo mientras la empresa remite por un tercero mueve el modo al que ese tipo necesita, o de vuelta a own_certificate si ese modo no se puede usar. Con own_certificate, registrar no cambia nada: cambia con PATCH …/settings, que exige una representación activa (422 representation_required).
El emisor es siempre la empresa. Quien presente el lote, cada registro lleva el NIF y el nombre de la empresa, nunca los del certificado.
Presentador. En modo NO VERI*FACTU los registros se firman con el certificado del presentador: el propio de la empresa o, con una representación activa, el de Factuarea.

Cada registro, revocación y caducidad de una representación, y cada cambio de modo, quedan auditados.

Activar es un compromiso, no un interruptor

Encender VeriFactu es asimétrico, y una integración que lo trate como un interruptor reversible se topará con un 422 en producción.

Pasar al modo verificable siempre está permitido. Volver atrás está bloqueado hasta el 31 de diciembre del año en que se activó (BR-VFC-001, BR-VFC-023, RD 1007/2023 art. 13). La integridad de una cadena declarada a la AEAT en tiempo real no puede degradarse a software autocertificado a mitad de un ejercicio fiscal.

Hay una escapatoria deliberada: mientras la cadena siga vacía —la empresa no ha emitido un solo registro de facturación en ningún estado— la empresa puede cambiar de idea y volver atrás, y el bloqueo se levanta. El primer registro emitido, aunque sea uno rechazado o con error, arma el bloqueo hasta fin de año. Apagar la bandera de activación por empresa lo impide la misma guarda, así que no sirve para esquivar el compromiso.

GET /v1/companies/{company}/verifactu/config expone is_locked_until para que puedas enseñárselo a tus usuarios antes de que se comprometan.

Sandbox y producción no son intercambiables

Cada empresa opera contra un único entorno AEAT, expuesto como environment tanto en el objeto de configuración como en cada registro. Un CSV obtenido contra el entorno de pruebas de la AEAT no es un alta: los CSV de pruebas llevan un prefijo reconocible, y una base de datos de producción que los contenga significa que se simuló algo que debería haberse transmitido (BR-VFC-017).

La regla que te protege es que el sistema nunca debe caer en simulación de forma silenciosa — un endpoint inaccesible tiene que aflorar como estado técnico error, no como una aceptación fabricada. Cuando concilies, trata el campo environment como parte de la identidad del registro.

Qué sale en el PDF

El alta automática en sí no añade nada al documento; lo impreso depende de la existencia de un registro, no de cómo se creó. En cuanto existe un registro, la factura lleva el bloque QR legal (BR-VFC-015), y la leyenda bajo el código difiere según el modo de funcionamiento: la marca corta VERI*FACTU en modo verificable, y la frase completa que declara que la factura es verificable en la sede electrónica de la AEAT en el otro.

Una factura importada con la excepción de histórico no tiene registro y por tanto no imprime QR. Es lo correcto: las facturas anteriores a la adhesión no son verificables en la AEAT.

Qué llega a la AEAT

Una declaración de alta por factura emitida, encadenada al registro anterior de la empresa, más una declaración de anulación si la factura se anula después (ver Anular o rectificar). No se transmite nada más como consecuencia de emitir. Los registros van en los lotes que describe Cómo llegan los registros a la AEAT, y una factura simplificada cualificada viaja como una F1 marcada con FacturaSimplificadaArt7273 (consulta Facturas simplificadas o completas).

En modo no_verifactu no llega nada a la AEAT en tiempo real; la empresa conserva la cadena local para inspección y el sistema registra periódicamente resúmenes de sus propios eventos operativos, que la norma trata como evidencia separada (BR-VFC-018).

Trazabilidad

Derivado de las reglas de dominio del backend de Factuarea:

BR-VFC-001 — la adhesión al modo verificable es irrevocable hasta fin de año natural, con la excepción de la cadena vacía.
BR-VFC-008 — idempotencia: un alta por factura, incluso cuando el flujo de crear y emitir dispara dos eventos.
BR-VFC-009 — la excepción de la importación histórica, vista desde VeriFactu.
BR-VFC-015 — el bloque QR y sus dos leyendas.
BR-VFC-017 — la frontera entre sandbox y producción, y la prohibición de simular en silencio.
BR-VFC-018 — modo no_verifactu: cadena local, resúmenes de eventos, sin transmisión en tiempo real.
BR-VFC-023 — el cambio de modo asimétrico y el bloqueo hasta fin de año, incluida la guarda que impide esquivarlo con la bandera de activación.
BR-VFC-025 — activación por empresa, desactivada de fábrica, valor efectivo como instancia Y empresa.
BR-INV-011 — la excepción de la importación histórica, vista desde la facturación.

Alta automática en VeriFactu

En esta página