Conectar Stripe en marca blanca

Si montas un producto sobre Factuarea, tus clientes no deberían tener que salir de él para conectar su cuenta de Stripe. Este flujo los mantiene en tu portal: tú inicias la conexión, la persona completa el alta en la página propia de Stripe y, cuando vuelve, Factuarea completa la conexión y redirige el navegador a tu sitio.

Factuarea crea una cuenta Standard de Stripe para el NIF y la guarda junto a la autorización. La cuenta que acaba conectada es siempre esa: nada de lo que llegue en la dirección de vuelta puede cambiarla. Una vez conectada se comporta como cualquier otra cuenta conectada, así que la auto-facturación sigue desactivada hasta que la actives.

Qué necesitas

• Una clave live con stripe_autoinvoicing:write (y stripe_autoinvoicing:read para listar). No interviene ningún scope nuevo.
• El NIF debe ser de tu propia cuenta, o de una cuenta que gestionas con acceso operate. Una cuenta que solo recibió acceso a un NIF no puede iniciar la conexión y obtiene forbidden_action. Un NIF que tu clave no alcanza responde 404.
• El módulo de Stripe en el plan del NIF, disponible en los planes Empresario y Enterprise.
• Dominios de retorno dados de alta en tu cuenta. Son los únicos hosts a los que Factuarea devolverá a una persona.

1. Da de alta tus dominios de retorno

Un dominio de retorno es un host que permites como destino del return_url. Pertenecen a la cuenta que inicia la conexión, que es la tuya, no la de quien posee 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"}'

Responde 201 con un objeto connect_return_domain. Las reglas:

• Solo el host, hasta 253 caracteres: sin esquema, puerto, ruta, comodín, dirección IP ni localhost. Se pasa a minúsculas, así que App.MiDominio.com y app.midominio.com son el mismo dominio.
• Coincidencia exacta. Dar de alta midominio.com no permite app.midominio.com: cada subdominio que uses es una entrada propia.
• Una cuenta puede tener hasta veinte dominios. Dar de alta uno que ya existe responde connect_return_domain_already_exists (409) y pasarse del límite, connect_return_domain_limit_reached (422).
• {account} es tu propia cuenta. Otra cuenta, una que gestionas o una que no existe responde 404 account_not_found.
• La clave debe haberla emitido un titular o administrador de la cuenta y su ámbito de NIF debe cubrir todos los NIF de la cuenta; si no, forbidden_action.

Lístalos con GET sobre la misma ruta, con paginación por cursor, y elimina uno con DELETE …/return-domains/{return_domain}, que responde 204. Eliminar un dominio no toca las autorizaciones ya iniciadas, pero cualquier return_url nuevo en ese host se rechaza, y la vuelta de una que ya estaba en curso deja de enviarse a él (mira la vuelta). Si el dominio no existe o pertenece a otra cuenta, la respuesta es connect_return_domain_not_found.

La misma lista se gestiona desde la aplicación web, en Desarrolladores, en la pestaña de dominios de retorno.

2. Inicia la autorización

POST /v1/companies/{company}/connected-accounts/authorizations inicia la conexión de un NIF. Dos cosas son obligatorias:

• El header Idempotency-Key. La llamada crea una cuenta en Stripe, así que un reintento sin clave podría crear una segunda. Si falta, responde idempotency_key_required cuando la ventana de transición de la plataforma esté cerrada, y hasta entonces la llamada se atiende con un header Deprecation. Envíala desde el primer día.
• return_url, una dirección https absoluta de hasta 2048 caracteres, sin credenciales ni fragmento y en el puerto 443. Su host debe ser uno de tus dominios de retorno. Cualquier otra cosa responde connect_return_url_not_allowed (422) y no crea nada.

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 es el enlace de alta de Stripe. No es una página de Factuarea: ábrelo en el navegador de la persona titular de la cuenta de Stripe. Es un Account Link de Stripe de vida corta: si caduca o ya se ha usado, Stripe devuelve a la persona a Factuarea, que lo renueva con un enlace nuevo de la misma cuenta de Stripe, así que no hace falta iniciar de nuevo.
• La autorización queda pending durante 24 horas (expires_at es el plazo para completarla, no la caducidad de url). Si vuelves a iniciarla para el mismo NIF desde la misma cuenta mientras sigue vigente, se reutiliza: recibes el mismo id y la misma cuenta de Stripe con un enlace nuevo, y el estado del anterior deja de ser válido.
• La respuesta no lleva header Location: una autorización no tiene lectura propia.
• La llamada está limitada a 10 por minuto por clave y empresa, y un rechazo nunca llega a Stripe.

3. La vuelta a tu sitio

Cuando la persona termina en Stripe, pasa un instante por Factuarea, que comprueba la cuenta con Stripe y completa la conexión, y el navegador se redirige a tu return_url conservando su query y añadiendo estos parámetros:

Estos son los casos que verás en error:

• business_rule_violation con error_subcode=onboarding_incomplete u onboarding_pending_review: la persona se fue antes de que Stripe aceptara la cuenta. La autorización sigue pending hasta que caduca: inicia de nuevo y obtienes la misma autorización con un enlace nuevo.
• resource_already_exists con error_subcode=connected_account_in_use: esa cuenta de Stripe ya está conectada a otra empresa. No se conecta nada.
• business_rule_violation con error_subcode=connect_authorization_expired o connect_authorization_already_used: inicia una autorización nueva.

Hay dos situaciones en las que el navegador nunca va a tu sitio. Si retiraste el dominio del return_url después de iniciar, la conexión se completa si procede, pero la persona aterriza en la aplicación de Factuarea. Lo mismo ocurre si la vuelta llega con un valor que no identifica ninguna autorización. En ningún caso Factuarea redirige a un host que no esté en tu lista.

Lee status y el resto de parámetros como una pista para tu pantalla, no como la fuente de verdad: confirma la conexión leyendo la cuenta.

4. Lee la conexión

La cuenta conectada aparece entonces en GET /v1/companies/{company}/connected-accounts, identificada por el connected_account_id de la vuelta. Empieza con la auto-facturación desactivada y es la cuenta principal del NIF si no había otra. A partir de ahí se gestiona con las operaciones habituales.

Qué tener en cuenta

• Quién puede iniciar. La cuenta que posee el NIF, o el proveedor que lo gestiona con acceso operate. El acceso view responde 403.
• Sin tool MCP. El flujo necesita una redirección del navegador, así que no se expone en el servidor MCP.
• El estado es de un solo uso. El valor firmado que viaja en la vuelta se comprueba antes de leer nada y funciona una vez. Abrir dos veces la misma vuelta nunca conecta nada dos veces.
• Los errores, en un solo sitio. Los códigos de este flujo son connect_return_url_not_allowed, connect_return_domain_already_exists, connect_return_domain_limit_reached y connect_return_domain_not_found, además de los generales. Consulta los límites de peticiones para saber qué ocurre si llamas demasiado deprisa.