Eventos

Objetos event de solo lectura con un id opaco. Consulta histórica vía la API y entrega por webhook.

Cada evento publicado en Factuarea se persiste como un objeto event de solo lectura con un id opaco (un UUID v7, p. ej. 01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d), coherente con el id de cualquier otro recurso v1. Esto te permite:

Consultarlo vía API: GET /v1/events/{id} y GET /v1/events?type=invoice.paid.
Entregarlo a los webhook endpoints suscritos (el mismo objeto se envía en el body de la entrega — ver Webhooks).
Reenviar una entrega desde el dashboard (Developers > Webhooks > Deliveries).

Forma del payload

Cada evento comparte esta estructura:

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d",
  "object": "event",
  "type": "invoice.paid",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "invoice": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03" }
  },
  "created": "2026-05-15T10:23:18Z"
}

Campos:

id — identificador opaco del evento (UUID v7). Úsalo como la idempotency key en tu lado.
object — siempre event.
type — nombre del evento como <category>.<action> (p. ej. invoice.paid, quote.approved).
aggregate_id — UUID v7 del recurso que produjo el evento (p. ej. la factura para invoice.paid). null para eventos sin agregado rellenado. Distinto de id, que identifica el propio evento.
api_version — versión por fecha bajo la que se serializó el payload, sellada en la emisión. Siempre presente en los eventos emitidos hoy; null solo para eventos antiguos emitidos antes de sellar las versiones.
livemode — true para eventos generados en producción (clave live, fact_live_); false para eventos generados en modo de prueba (empresa sandbox, clave fact_test_). Los eventos de modo de prueba se registran y se pueden consultar vía GET /v1/events, pero no se entregan a los webhook endpoints (ver Modo de prueba y sandbox), así que cualquier evento que tu endpoint reciba realmente es siempre livemode: true.
data — una referencia ligera al recurso afectado, indexada por su tipo — p. ej. { "invoice": { "id": "..." } }. Obtén el recurso desde su propio endpoint para conseguir la representación completa y actual.
created — timestamp ISO 8601 UTC de cuándo se creó el evento.

Idempotencia

Cada evento tiene un id único. Los webhooks reentregan el mismo id al mismo endpoint en cada reintento. En tu handler:

event_id = event['id']
if seen_in_db(event_id):
    return '', 200
process(event)
mark_seen_in_db(event_id)

Catálogo de eventos

El catálogo completo y autoritativo de tipos de evento suscribibles lo devuelve GET /v1/event-catalog. Cada entrada lleva un name, una category, una description legible y un status (available o coming_soon):

curl https://api.factuarea.com/v1/event-catalog \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

{
  "data": [
    {
      "name": "invoice.paid",
      "category": "invoice",
      "description": "Factura pagada",
      "status": "available"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Tipos de evento representativos por categoría (consulta el catálogo para la lista completa y actualizada):

Facturas

invoice.created, invoice.updated, invoice.sent, invoice.paid, invoice.cancelled, invoice.annulled, invoice.overdue, invoice.deleted, invoice.number_assigned, invoice.rectified, invoice.email_sent, invoice.payment_reminder_sent, invoice.simplified_created, invoice.verifactu_submitted, invoice.metadata_changed.

Presupuestos

quote.created, quote.updated, quote.deleted, quote.approved, quote.rejected, quote.converted, quote.expired, quote.number_assigned, quote.metadata_changed.

Facturas proforma

proforma.created, proforma.updated, proforma.deleted, proforma.accepted, proforma.rejected, proforma.cancelled, proforma.expired, proforma.converted_to_invoice, proforma.number_assigned, proforma.metadata_changed.

Albaranes

delivery_note.created, delivery_note.updated, delivery_note.status_changed, delivery_note.signed, delivery_note.converted.

Facturas de compra

purchase_invoice.created, purchase_invoice.updated, purchase_invoice.paid, purchase_invoice.payment_registered, purchase_invoice.cancelled, purchase_invoice.metadata_changed.

Facturas recurrentes

recurring_invoice.created, recurring_invoice.activated, recurring_invoice.paused, recurring_invoice.updated, recurring_invoice.deleted, recurring_invoice.completed, recurring_invoice.executed, recurring_invoice.failed, recurring_invoice.cancelled, recurring_invoice.metadata_changed.

Clientes y productos

client.created, client.updated, client.deleted, client.metadata_changed, product.created, product.updated.

Series e impuestos

series.created, series.updated, series.deleted, series.archived, series.unarchived, series.marked_as_default, series.number_consumed, tax.metadata_changed, tax.validity_changed, payment.received.

FacturaE (FACe)

facturae.face_submitted, facturae.face_status_changed, facturae.face_cancellation_requested.

Ejemplos de payload

invoice.paid

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d",
  "object": "event",
  "type": "invoice.paid",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "invoice": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03" }
  },
  "created": "2026-05-15T11:42:08Z"
}

client.updated

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a1a",
  "object": "event",
  "type": "client.updated",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a2b",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "client": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a2b" }
  },
  "created": "2026-05-15T11:50:12Z"
}

quote.converted

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a3c",
  "object": "event",
  "type": "quote.converted",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a4d",
  "api_version": "2026-05-22",
  "livemode": true,
  "data": {
    "quote": { "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a4d" }
  },
  "created": "2026-05-15T12:01:55Z"
}

El evento solo lleva una referencia ligera al recurso afectado. Obtén el recurso desde su propio endpoint (p. ej. GET /v1/quotes/{id}) para leer la factura convertida a la que enlaza.

Suscribirse a eventos

Vía API:

curl -X POST https://api.factuarea.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.mycompany.com/factuarea/webhook",
    "enabled_events": ["invoice.paid", "quote.approved"]
  }'

Para suscribirte a todos los eventos (no recomendado en producción salvo para dashboards internos):

{ "enabled_events": ["*"] }

Para suscribirte a familias enteras (todos los invoice.*):

{ "enabled_events": ["invoice.*", "quote.*"] }

Listar eventos vía API

GET /v1/events?type=invoice.paid&limit=50

Filtros disponibles: type, type[in], created[gte], created[lte], created[gt], created[lt]. Paginación por cursor estándar (limit, starting_after, ending_before) — ver Paginación.

En esta página