Connectar Stripe en marca blanca

Si muntes un producte sobre Factuarea, els teus clients no haurien de sortir-ne per connectar el seu compte de Stripe. Aquest flux els manté al teu portal: tu inicies la connexió, la persona completa l'alta a la pàgina pròpia de Stripe i, quan torna, Factuarea completa la connexió i redirigeix el navegador al teu lloc.

Factuarea crea un compte Standard de Stripe per al NIF i el desa juntament amb l'autorització. El compte que acaba connectat és sempre aquest: res del que arribi a l'adreça de tornada pot canviar-lo. Un cop connectat es comporta com qualsevol altre compte connectat, de manera que l'autofacturació continua desactivada fins que l'activis.

Què necessites

• Una clau live amb stripe_autoinvoicing:write (i stripe_autoinvoicing:read per llistar). No intervé cap scope nou.
• El NIF ha de ser del teu propi compte, o d'un compte que gestiones amb accés operate. Un compte que només ha rebut accés a un NIF no pot iniciar la connexió i obté forbidden_action. Un NIF que la teva clau no assoleix respon 404.
• El mòdul de Stripe al pla del NIF, disponible als plans Empresario i Enterprise.
• Dominis de retorn donats d'alta al teu compte. Són els únics hosts als quals Factuarea retornarà una persona.

1. Dona d'alta els teus dominis de retorn

Un domini de retorn és un host que permets com a destinació del return_url. Pertanyen al compte que inicia la connexió, que és el teu, no el de qui posseeix el NIF.

curl -X POST https://api.factuarea.com/v1/accounts/{account}/connected-accounts/return-domains \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.midominio.com"}'

Respon 201 amb un objecte connect_return_domain. Les regles:

• Només el host, fins a 253 caràcters: sense esquema, port, ruta, comodí, adreça IP ni localhost. Es passa a minúscules, de manera que App.MiDominio.com i app.midominio.com són el mateix domini.
• Coincidència exacta. Donar d'alta midominio.com no permet app.midominio.com: cada subdomini que facis servir és una entrada pròpia.
• Un compte pot tenir fins a vint dominis. Donar-ne d'alta un que ja existeix respon connect_return_domain_already_exists (409) i passar-se del límit, connect_return_domain_limit_reached (422).
• {account} és el teu propi compte. Un altre compte, un que gestiones o un que no existeix respon 404 account_not_found.
• La clau l'ha d'haver emès un titular o administrador del compte i el seu àmbit de NIF ha de cobrir tots els NIF del compte; si no, forbidden_action.

Llista'ls amb GET sobre la mateixa ruta, amb paginació per cursor, i elimina'n un amb DELETE …/return-domains/{return_domain}, que respon 204. Eliminar un domini no toca les autoritzacions ja iniciades, però qualsevol return_url nou en aquest host es rebutja, i la tornada d'una que ja estava en curs deixa d'enviar-s'hi (mira la tornada). Si el domini no existeix o pertany a un altre compte, la resposta és connect_return_domain_not_found.

La mateixa llista es gestiona des de l'aplicació web, a Desenvolupadors, a la pestanya de dominis de retorn.

2. Inicia l'autorització

POST /v1/companies/{company}/connected-accounts/authorizations inicia la connexió d'un NIF. Dues coses són obligatòries:

• El header Idempotency-Key. La crida crea un compte a Stripe, de manera que un reintent sense clau en podria crear un segon. Si falta, respon idempotency_key_required quan la finestra de transició de la plataforma estigui tancada, i fins llavors la crida s'atén amb un header Deprecation. Envia-la des del primer dia.
• return_url, una adreça https absoluta de fins a 2048 caràcters, sense credencials ni fragment i al port 443. El seu host ha de ser un dels teus dominis de retorn. Qualsevol altra cosa respon connect_return_url_not_allowed (422) i no crea res.

curl -X POST https://api.factuarea.com/v1/companies/{company}/connected-accounts/authorizations \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: connect-2026-0001" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://app.midominio.com/stripe/vuelta"}'

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-3a3b3c3d3e3f",
    "object": "connected_account_authorization",
    "url": "https://connect.stripe.com/setup/s/…",
    "return_url": "https://app.midominio.com/stripe/vuelta",
    "status": "pending",
    "expires_at": "2026-10-06T10:00:00+00:00",
    "company_id": "0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f"
  }
}

• url és l'enllaç d'alta de Stripe. No és una pàgina de Factuarea: obre'l al navegador de la persona titular del compte de Stripe. És un Account Link de Stripe de vida curta: si caduca o ja s'ha fet servir, Stripe retorna la persona a Factuarea, que el renova amb un enllaç nou del mateix compte de Stripe, així que no cal iniciar de nou.
• L'autorització queda pending durant 24 hores (expires_at és el termini per completar-la, no la caducitat d'url). Si la tornes a iniciar per al mateix NIF des del mateix compte mentre continua vigent, es reutilitza: reps el mateix id i el mateix compte de Stripe amb un enllaç nou, i l'estat de l'anterior deixa de ser vàlid.
• La resposta no porta header Location: una autorització no té lectura pròpia.
• La crida està limitada a 10 per minut per clau i empresa, i un rebuig mai no arriba a Stripe.

3. La tornada al teu lloc

Quan la persona acaba a Stripe, passa un instant per Factuarea, que comprova el compte amb Stripe i completa la connexió, i el navegador es redirigeix al teu return_url conservant-ne la query i afegint aquests paràmetres:

Aquests són els casos que veuràs a error:

• business_rule_violation amb error_subcode=onboarding_incomplete o onboarding_pending_review: la persona se'n va anar abans que Stripe acceptés el compte. L'autorització continua pending fins que caduca: inicia de nou i obtens la mateixa autorització amb un enllaç nou.
• resource_already_exists amb error_subcode=connected_account_in_use: aquest compte de Stripe ja està connectat a una altra empresa. No es connecta res.
• business_rule_violation amb error_subcode=connect_authorization_expired o connect_authorization_already_used: inicia una autorització nova.

Hi ha dues situacions en què el navegador mai no va al teu lloc. Si has retirat el domini del return_url després d'iniciar, la connexió es completa si escau, però la persona aterra a l'aplicació de Factuarea. El mateix passa si la tornada arriba amb un valor que no identifica cap autorització. En cap cas Factuarea redirigeix a un host que no sigui a la teva llista.

Llegeix status i la resta de paràmetres com una pista per a la teva pantalla, no com la font de veritat: confirma la connexió llegint el compte.

4. Llegeix la connexió

El compte connectat apareix llavors a GET /v1/companies/{company}/connected-accounts, identificat pel connected_account_id de la tornada. Comença amb l'autofacturació desactivada i és el compte principal del NIF si no n'hi havia cap altre. A partir d'aquí es gestiona amb les operacions habituals.

Què has de tenir en compte

• Qui pot iniciar. El compte que posseeix el NIF, o el proveïdor que el gestiona amb accés operate. L'accés view respon 403.
• Sense tool MCP. El flux necessita una redirecció del navegador, de manera que no s'exposa al servidor MCP.
• L'estat és d'un sol ús. El valor signat que viatja a la tornada es comprova abans de llegir res i funciona una vegada. Obrir dues vegades la mateixa tornada mai no connecta res dues vegades.
• Els errors, en un sol lloc. Els codis d'aquest flux són connect_return_url_not_allowed, connect_return_domain_already_exists, connect_return_domain_limit_reached i connect_return_domain_not_found, a més dels generals. Consulta els límits de peticions per saber què passa si crides massa de pressa.