Documentación interna

Documentación técnica interna de la plataforma de Allaria Grupo Financiero. Esta sección está restringida al personal de Allaria y no forma parte de la documentación pública de la API.

Acceso restringido

Esta sección requiere el rol INTERNAL_VIEWER. No compartas links a estas páginas fuera de Allaria.

Alcance

Esta sección es para documentación que no está destinada a clientes externos de la API, como:

• Arquitectura de servicios internos y cómo cada servicio llega al gateway b2b
• Runbooks operativos y guías de troubleshooting
• Endpoints internos y herramientas administrativas
• Referencias de entornos e infraestructura

Alta de un cliente

Los seis pasos manuales para darle acceso a la API b2b a un nuevo cliente externo, en orden. Ceibo es el caso de referencia en todos.

1. Whitelistear las IPs del cliente en el ALB b2b

Pedile al cliente las IPs públicas de salida desde las que su integración nos va a consumir (las del NAT si están detrás de uno), para cada entorno que vaya a usar.

Hasta que no estén whitelisteadas, los requests se descartan a nivel de red y el cliente ve un timeout de conexión, no un error HTTP.

En allaria-tech/infrastructure, agregá una entrada al local b2b_alb_clients:

Entorno	Archivo
Development	development/us-east-1/ec2/load-balancing/b2b.public.load.balancer.tf
Production	production/us-east-1/ec2/load-balancing/b2b.public.load.balancer.tf

{
  name = "<client-name>"
  ips  = ["<ip-1>", "<ip-2>", "<ip-3>"]
},

Se aceptan IPs sueltas y bloques CIDR (una IP suelta se normaliza a /32). No hay que tocar nada más — las reglas se generan a partir de esa lista.

1. Abrí el PR.
2. Verificá que el plan solo agregue recursos aws_security_group_rule.
3. Mergeá y aplicá.

Referencia: chore: add ceibo ips to whitelist (#1355).

2. Crear el clientId del cliente en Keycloak

En allaria-tech/infra-tf-keycloak-identity-management, creá <client-name>.tf en la raíz del repo:

module "<client-name>" {
  source      = "git@github.com:allaria-tech/infra-terraform-modules.git//keycloak"
  name        = "<client-name>"
  description = "credenciales para que <client-name> consulte sobre sus comitentes"
  assigned_roles = {
    bymas = {
      "roles" : ["BY_MAS_OPERATOR"]
    }
  }
}

assigned_roles lista los roles que necesita el cliente, con clave en el client que es dueño de esos roles:

• Consultar sus propios comitentes por bymas (el caso habitual): solo BY_MAS_OPERATOR.
• Cualquier otra cosa (market-data, opex, api-assets-transfer…): copiá el nombre del rol del .tf de ese servicio en el mismo repo.

Ojo con:

• name acepta solo minúsculas y guiones; si necesita un underscore, agregá convention_disabled = true.
• description no puede tener comillas ni backticks.
• Si el client ya existe en Keycloak, agregá enable_import = true — si no, el apply falla con 409 Conflict.

Un archivo por cliente, que se aplica a cada entorno con profiles/development.tfvars / profiles/production.tfvars.

Referencia: added ceibo clientId with bymas role (#155).

3. Agregar el mapper bymas_client_id

Paso manual en la consola de administración de Keycloak — host interno, no está cubierto por Terraform, así que hay que hacerlo una vez por entorno:

• Producción: https://keycloak.svc.internal.allaria.cloud/admin/master/console/#/main
• Development: https://keycloak.svc.internal.allaria.dev/admin/master/console/#/main

realm main → Clients → <client-name> → Client scopes → <client-name>-dedicated → Add mapper → By configuration → Hardcoded claim

Campo	Valor
Mapper type	Hardcoded claim
Name	bymas_client_id
Token Claim Name	bymas_client_id
Claim value	el id del cliente (Ceibo → 102)
Claim JSON Type	long
Add to ID token	On
Add to access token	On

Preguntá qué id usar

No hay registro ni asignación automática de bymas_client_id — los valores se reparten a dedo a medida que se dan de alta clientes (a Ceibo le tocó 102). Preguntá antes de definirlo; una colisión permitiría que un cliente resuelva contra las cuentas de otro.

Para verificar, pedí un token con las credenciales del cliente y decodificalo: el payload tiene que traer "bymas_client_id": <id> como número.

4. Vincular los comitentes en común a ese id

Registra qué cuentas de Allaria puede ver el cliente. Hasta que una cuenta no esté vinculada, sus posiciones y movimientos vuelven 403.

POST/by-mas/client-relationships

Endpoint interno de administración, en el host propio de bymas — a propósito no está expuesto por el gateway b2b, así que no usa https://b2b.allaria.dev ni /v1. Para development usá el host .dev.

curl --request POST \
  --url https://by-mas.svc.internal.allaria.cloud/by-mas/client-relationships \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Origin: ALLARIA_MAS' \
  --header 'accept: */*' \
  --data '[
  {
    "client_id": 102,
    "account_id": 500185,
    "company": "ALLARIA"
  }
]'

Campo	Tipo	Requerido	Descripción
client_id	number	Sí	El id del paso 3.
account_id	number	Sí	El número de cuenta en Allaria a vincular.
company	string	Sí	ALLARIA, ALLARIA_MAS o ALLARIA_DIGITAL.
should_delete	boolean	No	true desvincula en lugar de vincular.

El body es siempre una lista, así que se pueden vincular varias cuentas en una sola llamada.

Response: { "created": "1", "deleted": "0", "unchanged": "0" } — los vínculos que ya existen cuentan como unchanged en lugar de fallar.

Los clientes ya no llaman a este endpoint por su cuenta: Allaria vincula las cuentas automáticamente y los clientes solo pueden consultar el estado en Vincular cuentas. Usá el host interno de acá cuando haya que crear o corregir una vinculación a mano.

Usá el host interno de acá cuando necesites vincular cuentas en nombre de un cliente con un token de admin.

Se necesita un admin token

{{token}} tiene que ser un admin token de Allaria+ (Firebase), enviado con X-Client-Origin: ALLARIA_MAS. El token de Keycloak del propio cliente se rechaza acá — no puede vincularse sus propias cuentas.

Todo el batch es una sola transacción

Si algún account_id no existe para la company indicada, no se aplica nada del batch. Mandá batches chicos y revisá los números de cuenta y su company.

5. Darle acceso a esta documentación a la gente del cliente

Agregá los emails que nos pasó el cliente, uno por persona, en authz dentro de la aplicación external-docs:

• Producción: https://authz.app.internal.allaria.cloud/applications/external-docs/users
• Development: https://authz.app.internal.allaria.dev/applications/external-docs/users

Agregar Usuario → email → rol ALL_VIEWER → guardar.

ALL_VIEWER da acceso a todas las tabs de producto y no llega a la tab Internal, por eso es el default para contactos de clientes.

• Si el cliente solo debe ver una parte del sitio: ALYC_VIEWER / WALLET_VIEWER (o un controller role).
• Nunca le asignes INTERNAL_VIEWER a un cliente.

Si a la persona le aparece Access Denied, el email cargado en authz no coincide con el que usa para loguearse.

6. Enviarle las credenciales al cliente

En la consola de administración de Keycloak — lista de Clients (producción), lista de Clients (development) — abrí realm main → Clients → <client-name>:

Qué	Dónde
Client ID	Tab Settings
Client Secret	Tab Credentials — ícono de ojo para verlo, ícono de copiar para copiarlo

1. Preguntale al cliente a qué dirección mandarlas, y confirmala con tu contacto conocido.
2. Mandá el secret por OneTimeSecret — el link, nunca el valor en el cuerpo de un mail o chat.
3. Incluí el clientId y un link a la página de Autenticación (grant_type=client_credentials contra POST /auth/token).
4. Recordales que solo pueden llegar a la API desde las IPs del paso 1, y que las nuevas hay que pedirlas con anticipación.

Regenerate invalida el secret anterior al instante

Rotar el secret en la tab de Credentials rompe la integración del cliente hasta que cargue el nuevo. Coordinalo con ellos.

Convenciones

Las páginas de esta sección siguen las mismas reglas que el resto del sitio:

• Cada página debe existir en inglés (internal/) y en español (i18n/es/docusaurus-plugin-content-docs-internal/current/).
• Las páginas de endpoints usan el componente ApiEndpoint y la estructura definida en ENDPOINT_TEMPLATE.md.
• Las base URLs usan el placeholder https://b2b.allaria.dev — nunca hardcodees un dominio.

Agregar una subsección

Creá un subdirectorio dentro de internal/ con un _category_.json que defina su label y position, y replicalo bajo i18n/es/docusaurus-plugin-content-docs-internal/current/ con el label en español.