Actividad de la factura: resultados de la AEAT, correo y cobros
La línea de tiempo de la factura añade el resultado de cada envío a la AEAT, los correos no entregados, la primera visita diaria al enlace público y los eventos de cobro, cada uno con un contrato exacto de metadata.
4 de octubre de 2026
GET /v1/invoices/{invoice}/activities
y la tool MCP get_invoice_activities publican ahora más eventos en la línea de tiempo
de una factura. Cada event_type nuevo tiene un contrato exacto de metadata,
descrito en el esquema InvoiceActivity, y no expone identificadores internos.
Envíos VeriFactu
Se registra el resultado de cada envío de un registro a la AEAT:
event_type | Cuándo | metadata |
|---|---|---|
verifactu.record_accepted | La AEAT aceptó un registro (el alta, una subsanación o la anulación), con o sin errores admisibles. | record_type, csv, aeat_error_code, requires_subsanation, attempt |
verifactu.record_rejected | La AEAT rechazó un registro. | record_type, aeat_error_code, aeat_error_message, attempt |
verifactu.transmission_failed | El envío falló por la AEAT o la red y se reintenta automáticamente. Una entrada por incidencia, no por intento. | record_type, reason, attempt, next_retry_at |
verifactu.transmission_blocked | El envío está detenido, sin reintento automático, hasta que se corrija la causa. | record_type, block_reason |
record_typeesalta,subsanacionoanulacion.csves el código seguro de verificación que devolvió la AEAT; esnullcuando la AEAT confirmó el registro como duplicado de un envío anterior.aeat_error_codees el error admisible (2xxx) o el aviso con el que se aceptó el registro, onull. En un rechazo es el código del rechazo (SCHEMA_INVALIDcuando el registro incumplía el esquema de la AEAT y no se envió).requires_subsanationindica si la AEAT exige una subsanación de ese error admisible. Todos la exigen salvo2004y2009.reasonesAEAT_UNREACHABLE,UNMATCHED_RESPONSE_LINEoSYSTEM_CERTIFICATE_UNAVAILABLE.- Un registro bloqueado se reactiva con
POST /v1/verifactu/records/retry-blocked.
El recurso de registro VeriFactu añade aeat_warning_requires_subsanation: para un
registro aceptado con un error, indica si la AEAT exige su subsanación. Es false para
un aviso que no es un código de la AEAT y null cuando el registro no está aceptado
con aviso.
Correo y enlace público
event_type | Cuándo | metadata |
|---|---|---|
invoice.email_failed | El correo de la factura no pudo entregarse tras sus reintentos. | recipient, reason (motivo legible en español, sin datos sensibles) |
invoice.public_link_viewed | Primera visita del día (Europe/Madrid) al enlace público. Las visitas posteriores ese día no añaden entrada. | views_today y, solo cuando se conoce, downloaded_pdf |
Cobros
Los cobros registrados, revertidos o editados sobre la factura aparecen en su línea de tiempo, también los registrados antes de que se publicaran estos eventos.
event_type | Cuándo | metadata |
|---|---|---|
payment.payment_created | Se registró un cobro. | amount, method, provider |
payment.payment_reversed | Se revirtió un cobro. | amount, reason, provider |
payment.payment_updated | Se editó un cobro. | changed_fields, provider |
amount está en euros, method es una clave del catálogo de GET /v1/payment-methods,
reason es la clave del motivo de la reversión y changed_fields lista los campos del
cobro que cambiaron (amount, date, method, reference, notes). provider es la
pasarela que cobró (stripe, gocardless, monei, woocommerce o shopify) o null
si el cobro se registró a mano. Cuando performed_by es null y provider tiene valor,
el cobro llegó de esa pasarela.
Endpoints actualizados8
| Endpoint | Descripción |
|---|---|
GET/v1/invoices/{invoice}/activities | Listar la actividad de la factura |
GET/v1/invoices/{invoice}/verifactu | Recupera el registro VeriFactu de la factura |
POST/v1/invoices/{invoice}/verifactu | Forzar la creación del registro VeriFactu de una factura |
GET/v1/verifactu/records | Lista los registros VeriFactu |
GET/v1/verifactu/records/{record} | Obtener un registro VeriFactu |
POST/v1/verifactu/records/find-by-csv | Buscar un registro VeriFactu por CSV de la AEAT |
POST/v1/verifactu/records/find-by-huella | Buscar un registro VeriFactu por hash |
POST/v1/verifactu/records/find-by-invoice-number | Buscar un registro VeriFactu por número de factura |