Invoice activity: AEAT results, email and payments
The invoice activity timeline adds the result of every AEAT submission, undelivered emails, the first daily visit to the public link and payment events, each with an exact metadata contract.
4 October 2026
GET /v1/invoices/{invoice}/activities
and the MCP tool get_invoice_activities now publish more events in the timeline of
an invoice. Each new event_type has an exact metadata contract, described in the
InvoiceActivity schema, and no internal identifiers are exposed.
VeriFactu submissions
The result of each submission of a record to the AEAT is recorded:
event_type | When | metadata |
|---|---|---|
verifactu.record_accepted | The AEAT accepted a record (the alta, a subsanación or the annulment), with or without admissible errors. | record_type, csv, aeat_error_code, requires_subsanation, attempt |
verifactu.record_rejected | The AEAT rejected a record. | record_type, aeat_error_code, aeat_error_message, attempt |
verifactu.transmission_failed | The submission failed because of the AEAT or the network and is retried automatically. One entry per incident, not per attempt. | record_type, reason, attempt, next_retry_at |
verifactu.transmission_blocked | The submission is stopped, with no automatic retry, until the cause is fixed. | record_type, block_reason |
record_typeisalta,subsanacionoranulacion.csvis the secure verification code the AEAT returned; it isnullwhen the AEAT confirmed the record as a duplicate of an earlier submission.aeat_error_codeis the admissible error (2xxx) or warning the record was accepted with, ornull. For a rejection it is the rejection code (SCHEMA_INVALIDwhen the record broke the AEAT schema and was not sent).requires_subsanationsays whether the AEAT requires a subsanación of that admissible error. Every one does except2004and2009.reasonisAEAT_UNREACHABLE,UNMATCHED_RESPONSE_LINEorSYSTEM_CERTIFICATE_UNAVAILABLE.- A blocked record is reactivated with
POST /v1/verifactu/records/retry-blocked.
The VeriFactu record resource adds aeat_warning_requires_subsanation: for a record
accepted with an error, whether the AEAT requires its subsanación. It is false for
a warning that is not an AEAT code and null when the record is not accepted with a
warning.
Email and public link
event_type | When | metadata |
|---|---|---|
invoice.email_failed | The invoice email could not be delivered after its retries. | recipient, reason (a readable reason in Spanish, without sensitive data) |
invoice.public_link_viewed | First visit of the day (Europe/Madrid) to the public link. Later visits that day add no entry. | views_today and, only when known, downloaded_pdf |
Payments
Payments registered, reversed or edited on the invoice appear in its timeline, including the ones recorded before these events were published.
event_type | When | metadata |
|---|---|---|
payment.payment_created | A payment was registered. | amount, method, provider |
payment.payment_reversed | A payment was reversed. | amount, reason, provider |
payment.payment_updated | A payment was edited. | changed_fields, provider |
amount is in euros, method is a key from the catalog of GET /v1/payment-methods,
reason is the reversal reason key and changed_fields lists the payment fields that
changed (amount, date, method, reference, notes). provider is the gateway
that collected the payment (stripe, gocardless, monei, woocommerce or
shopify) or null for a payment registered by hand. When performed_by is null
and provider is set, the payment came from that gateway.
Updated endpoints8
| Endpoint | Description |
|---|---|
GET/v1/invoices/{invoice}/activities | List invoice activity |
GET/v1/invoices/{invoice}/verifactu | Retrieve invoice VeriFactu record |
POST/v1/invoices/{invoice}/verifactu | Force-create VeriFactu record for invoice |
GET/v1/verifactu/records | List VeriFactu records |
GET/v1/verifactu/records/{record} | Retrieve a VeriFactu record |
POST/v1/verifactu/records/find-by-csv | Find a VeriFactu record by AEAT CSV |
POST/v1/verifactu/records/find-by-huella | Find a VeriFactu record by hash |
POST/v1/verifactu/records/find-by-invoice-number | Find a VeriFactu record by invoice number |