Integració GoCardless
Estat de la integració amb GoCardless — encara no alliberada, què existeix ja darrere del flag, i la superfície v1 i MCP exacta que apareix el dia que s'encén.
GoCardless encara no està disponible. Els seus endpoints v1 i les seves
tools MCP no estan registrats, així que cridar-los avui retorna
404 route_not_found. Aquesta pàgina documenta l'estat de la integració i
la superfície que apareixerà quan s'alliberi — no és una guia d'ús, i res del
que segueix s'ha de llegir com «això ja es pot cridar».
GoCardless cobra per domiciliació directa SEPA: en comptes de carregar una targeta, el teu client signa un mandat que t'autoritza a treure diners del seu compte bancari, i tot cobrament posterior corre contra aquest mandat. Aquest model canvia dues coses respecte d'una passarel·la de targeta — els diners es mouen amb un calendari diferit i una finestra de garantia, i el mandat té vida pròpia: neix, s'activa i es pot cancel·lar o caducar amb independència de qualsevol cobrament concret.
Què vol dir «encara no alliberada»
L'única font de veritat és la llista de passarel·les de pagament alliberades del
backend (integrations.released_providers), que avui conté només Stripe. És
configuració, no codi, així que una passarel·la s'encén sense desplegar codi.
Mentre GoCardless sigui fora d'aquesta llista:
- El seu bloc de rutes v1 no està registrat.
GET /v1/gocardless/mandatesi els endpoints/v1/gocardless-autoinvoicing/*no existeixen — no són al registre de rutes, ni a l'especificació OpenAPI, ni a la referència d'API d'aquest lloc. - Les seves tools MCP queden filtrades del servidor públic, així que un agent ni les descobreix ni les pot cridar.
- La passarel·la apareix com a «Properament» al marketplace d'integracions del Dashboard, i el flux de connexió està bloquejat també al command handler — fins i tot per a un super-admin que se salti el middleware de mòduls.
- L'endpoint de comptes connectats agnòstic de passarel·la filtra els seus resultats a les passarel·les alliberades, així que cap compte de GoCardless no pot aparèixer tampoc per aquí.
No falta res ni hi ha res a mig construir: les classes estan adormides, no absents. L'alliberament canvia una llista.
Què existeix ja darrere del flag
| Peça | Estat |
|---|---|
| Flux de connexió OAuth 2 | Construït. GoCardless s'autentica amb OAuth 2, a diferència de MONEI |
| Verificació de la firma del webhook | Construïda |
| Normalitzador d'esdeveniments | Construït — mapeja els esdeveniments de GoCardless sobre els mateixos esdeveniments de pagament interns que fa servir el pipeline de Stripe |
| Mandats SEPA | Construïts — es guarden amb el seu propi cicle de vida: pending, active, cancelled, expired, failed, sincronitzat des dels webhooks mandates.* |
| Comptes connectats per passarel·la | Construïts — llistar, obtenir, actualitzar i desconnectar, replicant el model multi-botiga de Stripe |
| Cobraments i rectificatives auto-facturats | Construïts — mateixes regles de decisió, mateixa alta a VeriFactu que a Stripe |
Quins esdeveniments facturen, i quins no ho fan a propòsit
El normalitzador és més estricte que «qualsevol esdeveniment de pagament emet factura», i la raó és la finestra de garantia SEPA:
| Esdeveniment de GoCardless | Què produeix |
|---|---|
payments.confirmed | Es tracta com a cobrat → corre el flux d'auto-facturació |
payments.charged_back, payments.late_failure | Es tracten com a devolució → flux de factura rectificativa |
payments.created, payments.submitted | S'ignoren a propòsit — són estats intermedis d'un càrrec diferit; facturar abans que el cobrament estigui garantit seria facturar diners que encara poden tornar enrere |
payments.paid_out | Avui no té efecte (la conciliació de payouts de GoCardless és un seguiment a part) |
| Qualsevol altre | Es registra com a esdeveniment desconegut |
Per això un cobrament de GoCardless no es converteix en factura a l'instant en què s'envia, i és la principal diferència de comportament que notaràs si véns de Stripe.
La superfície que apareix en alliberar-se
Endpoints v1
| Endpoint | Scope |
|---|---|
GET /v1/gocardless/mandates | gocardless_autoinvoicing:read |
GET /v1/gocardless-autoinvoicing/connected-accounts | gocardless_autoinvoicing:read |
GET /v1/gocardless-autoinvoicing/connected-accounts/{account} | gocardless_autoinvoicing:read |
PUT /v1/gocardless-autoinvoicing/connected-accounts/{account} | gocardless_autoinvoicing:write |
DELETE /v1/gocardless-autoinvoicing/connected-accounts/{account} | gocardless_autoinvoicing:write |
GET /v1/gocardless-autoinvoicing/payments | gocardless_autoinvoicing:read |
GET /v1/gocardless-autoinvoicing/correctives | gocardless_autoinvoicing:read |
Els mandats són de només lectura a l'API pública: el seu cicle de vida el
governen els webhooks mandates.*, no les teves crides.
Tools MCP
list_gocardless_mandates, list_gocardless_connected_accounts,
get_gocardless_connected_account, update_gocardless_connected_account,
disconnect_gocardless_connected_account,
list_gocardless_autoinvoiced_payments i
list_gocardless_autoinvoiced_correctives — una per cada endpoint de dalt, amb
els mateixos scopes.
Requisit de pla
La integració amb GoCardless és un mòdul dels plans Empresario i Enterprise, igual que les integracions amb Stripe i MONEI. Ser al pla correcte no bastarà per si sol mentre la passarel·la segueixi sense alliberar-se — s'han de complir les dues condicions.
Equivalències amb el flux de Stripe
Tot el que ja saps de Auto-facturació amb Stripe es trasllada, perquè la part específica de cada passarel·la acaba al normalitzador: a partir d'aquí, totes dues passarel·les comparteixen el mateix pipeline de facturació, les mateixes decisions fiscals i la mateixa alta a VeriFactu.
| Concepte | Stripe | GoCardless |
|---|---|---|
| Autenticació | OAuth 2 (Stripe Connect) | OAuth 2 |
| Multi-botiga | connected-accounts per compte | Mateix model, sota gocardless-autoinvoicing/connected-accounts |
| Senyal de «cobrament amb èxit» | charge.succeeded / invoice.paid | payments.confirmed (passada la finestra de garantia SEPA) |
| Devolucions | charge.refunded → factura rectificativa | payments.charged_back / payments.late_failure → factura rectificativa |
| Mandats | No aplica | Recurs de primer nivell amb el seu propi cicle de vida |
| Factura ordinària o simplificada | Mateixes regles de decisió | Mateixes regles de decisió |
| Cicles de subscripció | invoice.paid amb un billing_reason de subscripció | Sense branca equivalent: el normalitzador només mapeja esdeveniments payments.* |
| Conciliació de payouts | Suportada | Avui no coberta |
Què funciona avui de totes maneres
La safata d'esdeveniments d'integració és
agnòstica de la passarel·la i està registrada sense condicions. Registra
esdeveniments de qualsevol integració que escrigui historial, incloses les
passarel·les que encara no estan alliberades — perquè amagar aquestes files et
deixaria sense explicació per a cobraments que no es van facturar mai.
provider=gocardless hi és un valor de filtre vàlid des del primer dia.