#

Multi-sede (tenants)

Si tu integración cobra por varias unidades: sucursales, franquicias, o los clientes de tu SaaS white-label (por ejemplo, N institutos). Si cada una necesita recibir SUS propios avisos de pago, las agrupás en tenants. Cada tenant tiene su propio webhook, y cada pago llega solo al webhook de su tenant. Nunca se mezclan.

#

El mapa mental

  • Integración = tu empresa (el integration client).
  • Tenant = cada unidad que agrupás (una sucursal, o un cliente de tu SaaS), con su propio webhook. Es la unidad de ruteo.
  • Cuenta de comercio = la que efectivamente cobra; se vincula a un tenant y sus pagos viajan al webhook de ese tenant.
#

Cómo se arma: 2 pasos, 2 roles

1
El admin da de alta cada tenant
POST /my-integration/tenant

Desde el Portal: nombre del tenant, su webhook y (opcional) un token de validación.

Abrir Tenants →
2
El integrador conecta su cuenta de comercio
PUT /my-integration/tenant

Cada cuenta de comercio se vincula a su tenant con la clave (tenantKey) que le pasó el admin. Es idempotente: repetirlo no rompe nada.

Listo: desde ahí, cada pago de esa sede va a su webhook.

Ver ejemplo
curl
# 1) Admin da de alta la sede
curl -X POST {{integration-admin-url}}/my-integration/tenant \
  -H "Authorization: Bearer {admin_id_token}" \
  -d '{ "key": "sucursal-centro", "name": "Sucursal Centro",
        "webhook_url": "https://tu-backend.com/webhooks/centro" }'

# 2) La sede se vincula a su tenant con la clave
curl -X PUT {{integration-url}}/my-integration/tenant \
  -H "Authorization: Bearer {user_id_token}" \
  -d '{ "tenantKey": "sucursal-centro" }'
#

Sedes y el destino de cada evento

Tenant = unidades DISTINTAS, cada una aislada (un pago nunca se filtra a otro tenant). No existe el fan-out: cada evento se entrega a UN solo destino, nunca a varias URLs a la vez. Si configurás más de una URL a nivel integración y no hay una sede que desempate, el evento no se entrega a ninguna, queda retenido. Las reglas completas de cómo se elige el destino están en Webhooks.
#
Casos borde
  • Tenant sin webhook configurado → el evento queda en hold (no se entrega a ciegas).
  • Un cobro creado con su propia webhookUrl ignora el ruteo por sede: ese evento va a esa URL y a ninguna otra. Es la primera regla de las de Webhooks, y le gana al tenant.
  • Una clave de tenant que pertenece a otro cliente → 404 (no se filtra si la clave existe).
  • El integrationClientId y el userId salen siempre del token, nunca del body.