Esdeveniments

Objectes event de només lectura amb un id opac. Consulta històrica via l'API i entrega per webhook.

Cada esdeveniment publicat a Factuarea es persisteix com un objecte event de només lectura amb un id opac (un UUID v7, p. ex. 01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d), coherent amb l'id de qualsevol altre recurs v1. Això et permet:

Consultar-lo via API: GET /v1/events/{id} i GET /v1/events?type=invoice.paid.
Entregar-lo als webhook endpoints subscrits (el mateix objecte s'envia al body de l'entrega — vegeu Webhooks).
Reenviar una entrega des del dashboard (Developers > Webhooks > Deliveries).

Forma del payload

Cada esdeveniment comparteix aquesta 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"
}

Camps:

id — identificador opac de l'esdeveniment (UUID v7). Fes-lo servir com a idempotency key al teu costat.
object — sempre event.
type — nom de l'esdeveniment com a <category>.<action> (p. ex. invoice.paid, quote.approved).
aggregate_id — UUID v7 del recurs que va produir l'esdeveniment (p. ex. la factura per a invoice.paid). null per a esdeveniments sense agregat reomplert. Diferent d'id, que identifica el propi esdeveniment.
api_version — versió per data sota la qual es va serialitzar el payload, segellada en l'emissió. Sempre present en els esdeveniments emesos avui; null només per a esdeveniments antics emesos abans de segellar les versions.
livemode — true per a esdeveniments generats en producció (clau live, fact_live_); false per a esdeveniments generats en mode de prova (empresa sandbox, clau fact_test_). Els esdeveniments de mode de prova es registren i es poden consultar via GET /v1/events, però no s'entreguen als webhook endpoints (vegeu Mode de prova i sandbox), de manera que qualsevol esdeveniment que el teu endpoint rebi realment és sempre livemode: true.
data — una referència lleugera al recurs afectat, indexada pel seu tipus — p. ex. { "invoice": { "id": "..." } }. Obtén el recurs des del seu propi endpoint per aconseguir la representació completa i actual.
created — timestamp ISO 8601 UTC de quan es va crear l'esdeveniment.

Idempotència

Cada esdeveniment té un id únic. Els webhooks reentreguen el mateix id al mateix endpoint a cada reintent. Al teu handler:

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

Catàleg d'esdeveniments

El catàleg complet i autoritatiu de tipus d'esdeveniment subscribibles el retorna GET /v1/event-catalog. Cada entrada porta un name, una category, una description llegible i 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
}

Tipus d'esdeveniment representatius per categoria (consulta el catàleg per a la llista completa i actualitzada):

Factures

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.

Pressupostos

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

Factures 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.

Albarans

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

Factures de compra

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

Factures recurrents

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.

Clients i productes

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

Sèries i impostos

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.

Exemples 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"
}

L'esdeveniment només porta una referència lleugera al recurs afectat. Obtén el recurs des del seu propi endpoint (p. ex. GET /v1/quotes/{id}) per llegir la factura convertida a la qual enllaça.

Subscriure's a esdeveniments

Via 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"]
  }'

Per subscriure't a tots els esdeveniments (no recomanat en producció excepte per a dashboards interns):

{ "enabled_events": ["*"] }

Per subscriure't a famílies senceres (tots els invoice.*):

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

Llistar esdeveniments via API

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

Filtres disponibles: type, type[in], created[gte], created[lte], created[gt], created[lt]. Paginació per cursor estàndard (limit, starting_after, ending_before) — vegeu Paginació.

En aquesta pàgina