Esdeveniments

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/companies/{company}/events/{id} i GET /v1/companies/{company}/events?type=invoice.paid.
• Lliurar-lo als webhook endpoints subscrits, en un sobre signat amb el mateix id, type i data (vegeu Webhooks).
• Reenviar un lliurament des del dashboard (Developers > Webhooks > Deliveries).

Forma del payload

GET /v1/companies/{company}/events/{id} retorna l'esdeveniment dins de data. L'esdeveniment té aquest aspecte, amb la factura de data.object abreujada a sis dels seus camps:

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d",
  "object": "event",
  "type": "invoice.paid",
  "aggregate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
  "correlation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99",
  "api_version": "2026-09-23",
  "livemode": true,
  "test": false,
  "data": {
    "type": "invoice.paid",
    "object": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
      "object": "invoice",
      "number": "FAC-2026-00042",
      "status": "paid",
      "total": "1210.00",
      "currency": "EUR"
    },
    "amount": "1210.00",
    "payment_date": "2026-03-20",
    "payment_method": "bank_transfer",
    "payment_reference": "TRF-2026-0042"
  },
  "created": 1774002600
}

Camps:

• id — identificador opac de l'esdeveniment (UUID v7). Fes-lo servir per deduplicar 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.
• correlation_id — UUID v7 que enllaça els esdeveniments provocats per una mateixa operació, o null quan no n'hi ha cap. La clau sempre és present.
• 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/companies/{company}/events, però no es lliuren als webhook endpoints (vegeu Mode de prova i sandbox), de manera que qualsevol esdeveniment que el teu endpoint rebi realment és sempre livemode: true.
• test — true per a un lliurament de prova enviat amb test-event, false per a esdeveniments reals. És ortogonal a livemode.
• data — { "type", "object" }. object és el snapshot complet del recurs afectat tal com era quan va passar l'esdeveniment, idèntic al que retornava un GET d'aquell recurs en aquell moment. Està congelat: els canvis posteriors del recurs no reescriuen els esdeveniments passats, així que obtén el recurs des del seu propi endpoint quan necessitis el seu estat actual. Les claus pròpies de l'esdeveniment van al costat d'object, com amount i payment_date a invoice.paid.
• created — timestamp Unix, en segons, de quan es va crear l'esdeveniment.

Un webhook lliura el mateix esdeveniment en un sobre signat: els mateixos id, type, api_version, created, livemode, test, correlation_id i data, sense object ni aggregate_id. Consulta el seu body del lliurament.

Idempotència

Cada esdeveniment té un id únic. Els webhooks tornen a lliurar el mateix id al mateix endpoint a cada reintent, i un endpoint de compte que admet el mateix esdeveniment d'un NIF també el rep amb el mateix id. Al teu handler, desa els ids que hagis processat i respon 2xx sense actuar si en tornes a veure algun. Deduplicar lliuraments de webhooks té la recepta completa i quant de temps cal conservar els ids.

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
}

Aquest és el catàleg dels esdeveniments d'un NIF. Els esdeveniments account.* del mateix compte no hi són: consulta Esdeveniments de compte.

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

Factures

invoice.created, invoice.auto_created, invoice.corrective_auto_created, invoice.subscription_auto_created, invoice.updated, invoice.issued, invoice.marked_sent, invoice.unsent, invoice.sent (deprecat), invoice.paid, invoice.cancelled, invoice.annulled, invoice.overdue, invoice.deleted, invoice.number_assigned, invoice.rectified, invoice.email_sent, invoice.email_failed, invoice.payment_reminder_sent, invoice.simplified_created, invoice.simplified_substituted, invoice.substituted_by_complete, invoice.verifactu_submitted, invoice.verifactu_failed, invoice.metadata_changed.

invoice.auto_created / invoice.corrective_auto_created / invoice.subscription_auto_created els emeten els fluxos d' auto-facturació de passarel·les de pagament quan un cobrament, una devolució o un cicle de subscripció generen una factura de manera automàtica.

invoice.issued s'emet quan s'emet una factura: número definitiu, registre VeriFactu i moviments d'stock. invoice.marked_sent s'emet quan arriba al client (el servidor de correu en va acceptar l'email de lliurament o algú la va marcar a mà) i invoice.unsent quan s'esborra aquesta marca. Un cobrament mai no marca una factura com a enviada. invoice.sent és un àlies deprecat d'invoice.issued, emès en el mateix instant i amb el mateix data.object; les integracions noves s'han de subscriure a invoice.issued, i la retirada de l'àlies s'anunciarà amb una data Sunset. Les regles d'automatització ja no accepten invoice.sent com a activador.

Pressupostos

quote.created, quote.updated, quote.deleted, quote.approved, quote.rejected, quote.converted, quote.expired, quote.marked_as_pending, quote.cancelled, quote.number_assigned, quote.metadata_changed, quote.email_sent, quote.email_failed.

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, proforma.email_sent, proforma.email_failed.

Albarans

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

Documents de control

transport_document.created, transport_document.updated, transport_document.issued, transport_document.modified, transport_document.closed, transport_document.reopened, transport_document.cancelled, transport_document.superseded, transport_document.email_sent, transport_document.email_failed.

Cada lliurament porta el recurs v1 transport_document complet a data.object. S'emeten sigui quin sigui l'origen del canvi: l'app, la REST API, MCP o el tancament automàtic diari. transport_document.updated s'emet també quan un esborrany torna a copiar una part el contacte o les dades d'empresa de la qual han canviat (consulta Document de control (DeCA)). transport_document.closed distingeix un tancament manual d'un d'automàtic amb data.object.close_mode (manual o automatic). transport_document.email_sent (el servidor de correu va acceptar l'email) i transport_document.email_failed (no s'ha pogut lliurar) funcionen com els dels albarans: al costat de data.object, data porta recipient_email (la primera adreça de to), les llistes to, cc i bcc i la version del PDF adjunt; email_sent afegeix transport_document_number i email_failed afegeix error_message i error_class. Esborrar un esborrany no es publica com a esdeveniment. El prefix transport_document pertany al mòdul transport_documents. Consulta Document de control (DeCA).

Despeses

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.demoted_from_default, series.number_consumed, series.year_reset, series.month_reset, tax.metadata_changed, tax.validity_changed, tax.external_reference_changed.

Els esdeveniments tax.* es lliuren per als impostos propis de la teva empresa. Els impostos del catàleg de Factuarea no emeten esdeveniments.

FacturaE (FACe)

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

Pagaments i passarel·les

payment.received, payment.reversed, payout.reconciled.

payment.received i payment.reversed són les dues meitats d'un mateix cicle: el primer es dispara quan es registra un pagament contra una factura, i el segon quan aquest pagament s'anul·la i la factura torna al circuit de cobrament. Subscriu-te als dos — una factura que vas donar per cobrada pot deixar d'estar-ho, i reaccionar només a la primera meitat és confiar en una xifra que ha caducat. Consulta payment.reversed més avall.

payout.reconciled es dispara quan un payout de Stripe es concilia amb el teu extracte bancari (consulta Payouts i conciliació).

Automatitzacions

automation_rule.activated, automation_rule.paused, automation_rule.auto_paused, automation_run.started, automation_run.completed, automation_run.failed, automation_run.step_dead_lettered.

El motor informa del seu propi cicle de vida. Els tres esdeveniments automation_rule.* porten la regla al cos del lliurament, sota data.object: activated quan una regla entra en servei i comença a escoltar el seu activador, paused quan l'atura una persona i auto_paused quan l'atura la plataforma després d'una ratxa d'execucions fallides.

Els quatre esdeveniments automation_run.* porten l'execució al cos del lliurament, sota data.object: started quan un activador que ha coincidit supera els límits del motor i l'execució s'admet, completed quan tots els passos van aplicar el seu efecte, failed quan l'execució va acabar sense produir el seu efecte i no es pot reprocessar, i step_dead_lettered quan un pas concret queda aparcat a l'espera d'un rellançament manual. Com a la resta d'esdeveniments, data.object és el snapshot pres en emetre'l, no l'estat actual del recurs. Consulta la referència de l'execució.

Dos d'ells porten claus extra al costat del snapshot. automation_rule.auto_paused afegeix consecutive_failures, el nombre d'execucions fallides consecutives que van provocar la pausa automàtica — la regla la va pausar la plataforma, i automation_rule.paused és el seu equivalent humà. automation_run.step_dead_lettered afegeix step_index i discard_reason: step_index és la posició del pas aparcat començant per zero, i es resol contra el mateix snapshot (l'element de data.object.steps el step_index del qual coincideix, perquè un pas no és un recurs públic per si mateix), i discard_reason és un valor tipat d'un catàleg tancat, mai text lliure. A la pràctica sempre és un motiu de descart rellançable: un resultat que no admet reprocés tanca l'execució com a failed en comptes d'aparcar el pas.

Aquests set noms són al mateix catàleg tancat que la resta d'esdeveniments, així que també són activadors vàlids de regles: una automatització pot reaccionar a automation_run.failed igual que reacciona a invoice.paid, i cap llista d'exclusió no els amaga del catàleg d'activadors. Com la resta del motor, requereixen el mòdul automations.

Encadenar-los està acotat, no prohibit. Cada salt «acció → esdeveniment → regla» consumeix el límit de profunditat d'encadenament del motor —tres salts per defecte—, així que una regla que reacciona a automation_run.failed i torna a fallar no pot repetir-se sense fi: exhaurit el límit, l'execució no arriba a executar-se i queda registrada com a blocked. Un esdeveniment que produeix una persona o una integració entra amb profunditat zero, així que només consumeix aquest pressupost allò que va provocar una automatització.

Tasques i projectes

El mòdul de tasques publica 21 esdeveniments en quatre famílies. Viuen al mateix catàleg tancat que qualsevol altre esdeveniment, així que un endpoint de webhook s'hi pot subscriure (o a "*"), i són activadors d'automatització vàlids per a les empreses amb el mòdul tasks: una empresa que no el té ni els veu al catàleg d'activadors ni pot desar una regla que en faci servir un.

Cada esdeveniment l'emet l'operació que el causa, des de qualsevol superfície —l'app, l'API, MCP, el portal de l'empleat, una automatització, una integració o un procés programat—, i s'entrega un cop per fet, encara que l'esdeveniment es reentregui internament.

Què has de saber en consumir-los:

• data.object és el recurs v1 tal com era quan es va emetre l'esdeveniment —una task, un task_comment, un task_time_entry o un project, exactament com el serialitza l'API (consulta Projectes i tasques)—, no l'estat actual. Les claus extra de la taula viatgen al seu costat, sota data.
• task.completed és un subconjunt de task.status_changed. Moure una tasca a una columna final n'emet els dos. Subscriu-te a task.status_changed per seguir cada moviment entre columnes i estats, i a task.completed només si el que t'importa són les tasques completades; subscriure't als dos entrega dos esdeveniments per una mateixa tasca completada.
• Els esborrats es degraden. task.deleted, task_comment.deleted, task_time_entry.deleted i project.deleted porten deleted: true a data.object i, quan el recurs ja no es pot llegir, res més que el seu id. El seu project_id germà (i task_id) continua dient-te on era.
• Encamina per projecte. Cada esdeveniment de tasca, comentari i temps porta l'id del seu projecte —a data.object.project_id, o a data.project_id quan l'objecte no en té o l'esdeveniment és un esborrat—. En els esdeveniments project.* el projecte és data.object.id. Consulta la guia de webhooks per veure un handler.
• Desarxivar és una actualització. No existeix project.unarchived: desarxivar un projecte emet project.updated.
• task.due_soon i task.overdue s'emeten un cop per tasca i data de venciment. Canviar la data de venciment rearma els dos per a la data nova.
• El temps imputat no és el registre de jornada. El prefix és task_time_entry, mai time_entry, que pertany als fitxatges del control horari; una empresa sense aquest mòdul continua rebent task_time_entry.*. Consulta Temps imputat a tasques.

Esdeveniments de compte

A més dels esdeveniments d'un NIF de dalt, hi ha disset esdeveniments de compte, amb noms que comencen per account.. T'expliquen què li passa al mateix compte: els seus membres i el seu titular (account.member_added, account.owner_transferred…), l'accés que dona a altres comptes (account.access_granted…), els comptes que gestiona (account.managed_account_provisioned…), l'arribada i la sortida dels seus NIF (account.nif_added, account.nif_transferred, account.nif_archived), les seves importacions massives (account.import_completed), les seves places contractades (account.seats_updated) i la fi d'un paquet d'oferta (account.offer_package_ended). La seva audiència és el compte, no un NIF, així que viuen apart de tota la resta d'aquesta pàgina:

• No són al catàleg d'esdeveniments d'empresa. GET /v1/event-catalog no els llista, i un endpoint d'empresa no s'hi pot subscriure: un nom account.* al seu enabled_events respon 422 i no es crea res. Tampoc són al log d'esdeveniments de GET /v1/companies/{company}/events, perquè aquest log pertany a un sol NIF.
• No activen automatitzacions d'empresa. El catàleg d'activadors de les automatitzacions es construeix a partir dels esdeveniments d'empresa, així que un esdeveniment account.* mai no és l'activador d'una regla.
• Només arriben a endpoints de compte. Només un endpoint de webhook de compte s'hi pot subscriure, juntament amb els esdeveniments d'empresa si vols. El seu filtre account_relationship i la família de cada esdeveniment decideixen qui l'escolta.

Webhooks de compte llista els disset noms amb el data.object de cadascun, el sobre que rep un endpoint de compte i qui escolta cada esdeveniment. Un esdeveniment d'un NIF, com invoice.paid, també pot arribar a un endpoint de compte i conserva el mateix id que té en un endpoint d'empresa: consulta Deduplicar lliuraments de webhooks.

Exemples de payload

Aquests són els cossos que lliura un webhook, amb data.object abreujat a uns pocs camps: el real és el recurs complet, com a Forma del payload.

invoice.paid

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d",
  "type": "invoice.paid",
  "api_version": "2026-09-23",
  "created": 1774002600,
  "livemode": true,
  "test": false,
  "correlation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99",
  "data": {
    "type": "invoice.paid",
    "object": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
      "object": "invoice",
      "number": "FAC-2026-00042",
      "status": "paid",
      "total": "1210.00",
      "currency": "EUR"
    },
    "amount": "1210.00",
    "payment_date": "2026-03-20",
    "payment_method": "bank_transfer",
    "payment_reference": "TRF-2026-0042"
  }
}

invoice.issued

El body de l'entrega porta la factura completa a data.object; l'exemple conserva només els camps dels eixos d'emissió i d'enviament. Un endpoint amb api_version 2026-05-22 rep el mateix snapshot amb el vocabulari anterior: "status": "sent", sent_at igual a l'instant d'emissió i sense issued_at, sent_via ni is_sent. Consulta Webhooks.

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a7a",
  "type": "invoice.issued",
  "api_version": "2026-10-01",
  "created": 1773575100,
  "livemode": true,
  "test": false,
  "correlation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a7b",
  "data": {
    "type": "invoice.issued",
    "object": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a03",
      "object": "invoice",
      "number": "FAC-2026-00042",
      "status": "issued",
      "issued_at": "2026-03-15T11:45:00Z",
      "sent_at": null,
      "sent_via": null,
      "is_sent": false
    }
  }
}

transport_document.closed

S'emet quan es tanca un document de control. El procés diari el tanca automàticament 7 dies després del final de la seva última data de transport (Europe/Madrid); l'exemple és aquest tancament automàtic. El cos del lliurament porta el recurs complet a data.object; l'exemple conserva només els camps del cicle de vida.

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9b01",
  "type": "transport_document.closed",
  "api_version": "2026-10-01",
  "created": 1791929700,
  "livemode": true,
  "test": false,
  "correlation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9b02",
  "data": {
    "type": "transport_document.closed",
    "object": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01",
      "object": "transport_document",
      "number": "DC-2026-042",
      "status": "closed",
      "public_url": "https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE",
      "current_version": 2,
      "closed_at": "2026-10-13T22:15:00+00:00",
      "close_mode": "automatic",
      "reopen_deadline": null,
      "retention_until": "2027-10-13T22:15:00+00:00"
    }
  }
}

client.updated

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a1a",
  "type": "client.updated",
  "api_version": "2026-09-23",
  "created": 1774003800,
  "livemode": true,
  "test": false,
  "correlation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a1b",
  "data": {
    "type": "client.updated",
    "object": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a2b",
      "object": "client",
      "name": "Acme Corporation",
      "tax_id": "B12345674",
      "email": "billing@acme.com"
    }
  }
}

quote.converted

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a3c",
  "type": "quote.converted",
  "api_version": "2026-09-23",
  "created": 1774003315,
  "livemode": true,
  "test": false,
  "correlation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a3d",
  "data": {
    "type": "quote.converted",
    "object": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04",
      "object": "quote",
      "number": "P-2026-00012",
      "status": "converted",
      "converted_to_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"
    },
    "target": "invoice",
    "target_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"
  }
}

El snapshot de data.object és el pressupost tal com era quan es va convertir, i target i target_id apunten a la factura que va produir. Obtén aquella factura des del seu propi endpoint (p. ex. GET /v1/companies/{company}/invoices/{id}) per llegir-ne l'estat actual.

payment.reversed

S'emet quan s'anul·la un pagament registrat contra una factura. Fins que va existir, una integració que havia sentit payment.received no tenia manera d'assabentar-se que aquell mateix pagament s'havia desfet.

Com tot esdeveniment, porta el recurs afectat complet sota data.object — el pagament tal com el serialitza l'API v1, ja marcat com a anul·lat — i afegeix un bloc data.reversal que descriu l'operació mateixa:

{
  "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a5e",
  "type": "payment.reversed",
  "api_version": "2026-09-23",
  "created": 1780388100,
  "livemode": true,
  "test": false,
  "correlation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a6f",
  "data": {
    "type": "payment.reversed",
    "object": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b",
      "object": "payment",
      "invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "amount": "500.00",
      "payment_date": "2026-05-20",
      "payment_method": "direct_debit",
      "payment_method_text": "Domiciliación bancaria",
      "reference": "TRF-2026-0042",
      "notes": null,
      "is_reversed": true,
      "reversed_at": "2026-06-02T08:15:00Z",
      "reversal_reason": "direct_debit_return",
      "reversal_reason_text": "Devolución de adeudo SEPA",
      "reversal_note": "Devuelto por el banco con motivo MD01.",
      "created_at": "2026-05-20T10:30:00Z",
      "updated_at": "2026-06-02T08:15:00Z"
    },
    "reversal": {
      "reason": "direct_debit_return",
      "origin": "gateway"
    }
  }
}

• data.reversal.reason — un dels cinc valors del catàleg tancat: direct_debit_return, card_dispute, misapplied_payment, bounced_effect, recording_error; un sisè, issued_in_error, apareix als pagaments revertits en anul·lar amb revert_collections una factura emesa per error. Ramifica segons aquest camp, mai segons reversal_reason_text, que és una etiqueta en castellà per a persones.
• data.reversal.origin — gateway quan va ser la passarel·la de pagament la que va informar de la devolució, disputa o retrocessió (ja hi va haver moviment al banc); manual quan ho va registrar una persona. Útil per decidir si reclamar al client o esperar el fitxer bancari.

Què fer quan arriba: la factura ha tornat al circuit de cobrament (issued, sent abans de la versió de l'API 2026-10-01, o overdue si el seu venciment ja ha passat) i el seu paid_amount ja no inclou aquella entrada, així que refresca el que tinguessis desat a la memòria cau sobre aquella factura. No emetis una factura rectificativa com a reacció — una anul·lació no és una minoració d'ingressos. Consulta Anul·lació o rectificativa?.

task.status_changed

El cos del lliurament porta la tasca a data.object, tal com va quedar després del moviment, i les dues claus extra d'aquest esdeveniment: l'estat i la columna de la qual venia la tasca. L'exemple conserva només els camps de l'eix del tauler.

{
  "id": "0193a4f2-e1a0-7c10-9b21-3d5f7a9c1e01",
  "type": "task.status_changed",
  "api_version": "2026-10-01",
  "created": 1790673330,
  "livemode": true,
  "test": false,
  "correlation_id": "0193a4f2-e1a0-7c10-9b21-3d5f7a9c1e02",
  "data": {
    "type": "task.status_changed",
    "object": {
      "id": "0193a4f2-8f53-7d44-8e85-7a9b1c3d5f16",
      "object": "task",
      "key": "DEV-16",
      "project_id": "0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01",
      "column_id": "0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02",
      "status": "active",
      "title": "Call the customer about the checkout demo",
      "completed_at": null
    },
    "previous_status": "active",
    "previous_column_id": "0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01"
  }
}

• data.previous_status — planned, active o archived: l'estat de tauler abans del canvi.
• data.previous_column_id — la columna que va deixar la tasca, o null quan venia del backlog o de l'arxiu.

Els altres esdeveniments del mòdul conserven el mateix embolcall: task.assigned afegeix previous_assignee_id, task.moved afegeix from_project_id i task.updated afegeix changed_fields, la llista de camps del recurs públic task que han canviat.

Subscriure's a esdeveniments

Via API:

curl -X POST https://api.factuarea.com/v1/companies/{company}/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"]
  }'

enabled_events pren noms d'esdeveniment del catàleg, almenys un. Un comodí com * o invoice.* no és un nom vàlid: respon 422 i no es crea res. Per reaccionar a una família sencera, enumera'n els esdeveniments (el catàleg els agrupa per categoria):

{ "enabled_events": ["invoice.created", "invoice.sent", "invoice.paid"] }

Un endpoint de webhook de compte accepta aquests mateixos noms i també els esdeveniments account.*, barrejats a la mateixa llista.

Llistar esdeveniments via API

GET /v1/companies/{company}/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ó.

Els esdeveniments es conserven 30 dies: els més antics deixen d'aparèixer al llistat. Els lliuraments d'un webhook conserven la seva pròpia còpia del payload durant 90 dies.

Esdeveniments de comandes

Subscriu-te a order.invoiced i order.refunded per rebre snapshots complets de la factura o rectificativa a data.object. Tots dos inclouen data.store.uuid, data.store.provider i data.order.external_id; les devolucions afegeixen data.refund.scope i data.refund.reason_code. Fes servir l’id de l’esdeveniment per deduplicar lliuraments i correlation_id per relacionar operacions. Consulta el processament de botigues i el trigger de n8n.

if (event.type === "order.invoiced" || event.type === "order.refunded") {
  const invoice = event.data.object;
  const storeId = event.data.store.uuid;
  const orderId = event.data.order.external_id;
  await saveOrderDocument({ eventId: event.id, storeId, orderId, invoice });
}