Safata d'esdeveniments d'integració

Una passarel·la de pagament envia a Factuarea un esdeveniment per tot el que passa al teu compte: un cobrament amb èxit, una devolució emesa, un cicle de subscripció cobrat, un payout que arriba. La majoria d'aquests esdeveniments produeixen alguna cosa — una factura, una rectificativa, un registre de pagament. Alguns no produeixen res, i quan això passa la pregunta interessant sempre és la mateixa: per què aquest cobrament no va acabar en factura?

La safata d'esdeveniments d'integració la respon. Cada esdeveniment que Factuarea rep queda registrat amb allò que va produir i, quan no va produir res, amb un motiu de descart tipat sortit d'un catàleg tancat. Sense endevinar als logs, sense obrir un tiquet de suport: el motiu és un valor pel qual pots filtrar i, en els motius sobre els quals pots actuar, ve amb el pas següent i, de vegades, amb la possibilitat de reprocessar l'esdeveniment.

La safata és agnòstica de la passarel·la. Registra esdeveniments de qualsevol integració que escrigui historial — incloses les passarel·les que encara no estan alliberades i els esdeveniments històrics d'una que es retiri — perquè amagar aquestes files et deixaria sense explicació per a cobraments que no es van facturar mai.

L'exposen tres endpoints:

La mateixa superfície existeix com a tools MCP — list_integrations_events, get_integrations_event i replay_integrations_event — amb els mateixos scopes.

Recórrer la safata

Del més recent al més antic, acotat a l'empresa autenticada. Paginació per cursor amb limit (d'1 a 100; 25 per defecte) i starting_after:

curl -G https://api.factuarea.com/v1/integrations/events \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "provider=stripe" \
  --data-urlencode "status=skipped" \
  --data-urlencode "limit=50"

{
  "data": [
    {
      "id": "0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f",
      "object": "integration_event",
      "provider": "stripe",
      "event_type": "invoice.paid",
      "direction": "inbound",
      "status": "skipped",
      "discard_reason": "subscription_autoinvoicing_disabled",
      "discard_reason_label": "Auto-facturación de suscripciones desactivada",
      "is_actionable": true,
      "is_replayable": true,
      "error_message": null,
      "duration_ms": 412,
      "created_at": "2026-07-14T09:31:07Z"
    }
  ],
  "has_more": true,
  "next_cursor": "84120"
}

Tracta next_cursor com a opac: en aquest llistat és una cadena numèrica, no un UUID v7 com els cursors dels llistats de documents. Torna'l tal qual a starting_after.

discard_reason_label arriba sempre en castellà, l'idioma de la interfície del producte, sigui quin sigui l'idioma de la teva integració. Si construeixes un panell en un altre idioma, basa els teus propis textos en discard_reason — aquest valor és l'identificador estable i tancat.

Filtres

discard_reason és l'eix tancat; event_type no és un enum. La columna event_type barreja a propòsit dues convencions: les branques instrumentades més tard guarden el tipus cru de la passarel·la (charge.refunded), mentre que les preexistents conserven el seu propi valor semàntic (autoinvoice.*). Busca'l per coincidència exacta quan sàpigues què persegueixes, però no el modelis mai com un conjunt tancat — estaries modelant una cosa que la columna no garanteix.

is_parked=false no és el mateix que ometre el paràmetre. El primer exclou els esdeveniments aparcats; el segon no exclou res.

Un valor fora del seu catàleg retorna 422, i un paràmetre de consulta desconegut retorna 400 parameter_unknown en comptes d'ignorar-se en silenci — un filtre que cau sense avisar et lliura una pàgina que creus acotada i no ho està.

El catàleg de motius de descart

Vint motius tipats, un per cada branca de descart del pipeline de webhooks de les passarel·les. Cadascun declara dues decisions de negoci que no són banderes decoratives:

• Accionable — pot fer-hi alguna cosa el titular del compte? Només els motius accionables avisen. Avisar algú d'un descart que no pot resoldre li ensenya a ignorar la safata, i així és com es perd l'avís que sí que importava.
• Aparcat — reprocessar el mateix contingut podria donar un altre resultat? Només els esdeveniments aparcats guarden el seu contingut xifrat i admeten un reprocessament.

La regla que hi ha darrere de la columna d'aparcament: un esdeveniment s'aparca quan el descart el va causar un estat extern que pots canviar (un ajust apagat, un compte connectat que es va desvincular, una moneda encara sense tipus de canvi). No s'aparca quan la causa és el contingut del mateix esdeveniment (mal format, duplicat, de tipus no cobert, import zero, cicle ja facturat) — reprocessar-lo prendria exactament la mateixa branca i només escriuria una segona fila. D'aquí l'invariant: tot motiu aparcat és accionable, i sis dels nou accionables s'aparquen.

Un motiu sense res a fer ho diu explícitament. Onze dels vint són informatius, i el contracte no s'inventa una instrucció per a ells: l'endpoint de detall retorna recommended_action: null en comptes d'una frase fabricada per omplir el camp.

Avisos: només el que pots arreglar

Un descart accionable avisa els administradors del compte. Un d'informatiu no avisa mai.

L'avís porta throttling: si ja existeix un avís sense llegir de la mateixa empresa, la mateixa passarel·la i el mateix motiu dins de les últimes 24 hores, no se'n crea un segon — un webhook mal configurat dispara centenars d'esdeveniments idèntics. La condició és sense llegir a propòsit: un cop l'has llegit, si continuen arribant descarts, el següent sí que avisa. Això no és soroll, vol dir que la incidència segueix viva.

L'aparcament i la finestra de 30 dies

Quan un motiu és aparcable, Factuarea guarda l'esdeveniment cru xifrat en repòs, per poder reprocessar-lo més tard. Aquest contingut no es retorna mai per l'API — ni al llistat, ni al detall. Conté dades personals dels teus clients finals i dades de pagament, i existeix per a exactament un propòsit: fer possible el reprocessament.

El contingut es purga als 30 dies d'aparcar-se l'esdeveniment. La fila sobreviu: el seu motiu, el seu estat, la seva data i la seva marca is_parked segueixen a la teva safata indefinidament, perquè el registre que un cobrament no va produir factura és historial que pots necessitar molt després que el contingut caduqui.

El detall: què fer a continuació

L'endpoint de detall retorna tot el del llistat, més recommended_action: una frase en imperatiu amb el pas següent per a aquell motiu concret, o null quan el motiu és informatiu.

curl https://api.factuarea.com/v1/integrations/events/0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

La frase distingeix a propòsit els motius reproduïbles («… i reprocessa l'esdeveniment») dels que no ho són («… emet-la a mà»), de manera que mai no t'apunta a una operació que respondria 422.

Un esdeveniment d'una altra empresa i un esdeveniment que no existeix retornen el mateix 404 resource_not_found. L'endpoint no revela mai si un id existeix en un altre lloc.

Reprocessar un esdeveniment aparcat

Torna a processar un esdeveniment de la passarel·la que va quedar aparcat, un cop ja no hi és la causa que li va impedir produir el seu efecte — has tornat a activar l'auto-facturació, has tornat a vincular el compte connectat, ja hi ha disponible el tipus de canvi oficial del dia.

curl -X POST https://api.factuarea.com/v1/integrations/events/0192f3a4-7b2c-7c1d-9e8f-1a2b3c4d5e6f/replay \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Quatre propietats d'aquesta operació importen més que la seva firma:

• No duplica factures. El reprocessament passa pel mateixíssim control d'idempotència que l'intent original, així que si aquell cobrament ja va produir una factura, el job s'atura sol i no crea res.
• És asíncron. 202 vol dir acceptat i encuat, no completat. El cos retorna l'esdeveniment tal com està ara — el seu is_replayable segueix sent true —, no el resultat del reintent. El resultat apareix com un esdeveniment nou a la safata, així que consulta GET /v1/integrations/events per veure com ha acabat.
• Si la causa segueix present, l'esdeveniment es descarta un altre cop i es registra de nou. És correcte, i és observable.
• No admet entrada. Qualsevol paràmetre de consulta o clau del cos retorna 400 parameter_unknown en comptes d'ignorar-se. Enviar-ne un vol dir que et penses que estàs configurant alguna cosa del reintent — un mode, una sèrie, una data — que aquesta operació no suporta, i acceptar-ho en silenci confirmaria aquella expectativa falsa sobre una acció que pot emetre una factura. Un cos buit, o directament cap cos, és el cas normal.

Quan es rebutja un reprocessament

is_replayable: true és el contracte: quan val true, el reprocessament no respon 422. És la conjunció de tres condicions — l'esdeveniment està aparcat, encara conserva el seu contingut i el seu motiu admet reprocessament —, avaluades en aquest mateix ordre pel mateix handler que guarda el reprocessament. Això és el que et permet oferir un botó de reintent sense endevinar.

Els tres rebutjos retornen 422 business_rule_violation i et diuen quin és a través del subcode:

On encaixa això

• Auto-facturació amb Stripe — el flux que produeix la majoria dels esdeveniments que trobaràs aquí, inclosos els cicles de subscripció, l'ajust dels quals és darrere de subscription_autoinvoicing_disabled.
• Payouts i conciliació bancària — la ingesta de payouts que hi ha darrere de payout_missing_id i payout_connected_account_missing.
• Mode de prova i sandbox — valida el teu tractament de la safata amb una clau fact_test_ abans de connectar un botó de reprocessament a una credencial de producció.
• Gestió d'errors — l'envelope de les respostes 400, 404 i 422 citades més amunt.