Alta automática en VeriFactu
No hay un botón de «enviar a la AEAT». El alta se crea cuando la factura sale de draft — esta es la lista de compuertas que deciden si ocurre, y las únicas palancas manuales que existen después.
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 en la transición a sent — incluidas las
facturas que nacen ya emitidas: rectificativas, sustitutivas F3, generaciones
de recurrentes y creaciones que pasan status: sent directamente.
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/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.
Certificado activo. Firmar requiere el certificado FNMT propio de la empresa.
Si no hay ninguno, o está caducado, revocado, o su NIF no coincide con el de la
empresa, la creación del alta falla con un error de regla de negocio. Comprueba
has_active_certificate en el endpoint de configuración antes de salir a
producción.
Si pasan las cinco, 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/invoices que
lo controle. 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/invoices/{id}/sendoPOST /v1/invoices/{id}/mark-sent. - O créala y emítela de forma atómica pasando
options.issue_directlyen la llamada de creación.
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/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/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 dos operaciones actúan sobre ella, y las dos se explican en Estados de envío VeriFactu:
retry— reenvía sin cambios la declaración almacenada, para fallos técnicos.subsanar— regenera la declaración a partir de datos maestros corregidos, para rechazos de la AEAT.
No existe operación que retransmita un registro aceptado. La aceptación es terminal por norma.
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/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.
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— modono_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 comoinstancia Y empresa.BR-INV-011— la excepción de la importación histórica, vista desde la facturación.