0064. Varias sucursales por id para que otro servicio las valide en una llamada¶
Estado: Aceptado (2026-11-10) Fecha: 2026-11-10 Autor: David Garcia Módulo(s) afectado(s): app/domains/sucursales/ (router, service, repository), tests/, docs/adr/ Complementa a: ADR 0063 (referencia de una sucursal), ADR 0062 (varias entidades por id)
Contexto¶
crm-svc-fuerza-ventas guarda las sucursales que cubre cada promotor (rel_promotores_sucursales) y
las reemplaza con la lista completa. Al agregar varias a la vez valida cada una con
GET /sucursales/referencia/{id} (ADR 0063): una llamada por sucursal, en serie, y el tiempo crece con
cuántas se agregan. Traer GET /sucursales para validar unas pocas ya se descartó en el ADR 0063. Para
las entidades el mismo problema se resolvió con GET /entidades/por-ids (ADR 0062).
Decisión¶
GET /api/v1/sucursales/por-ids?ids=…&ids=…(de 1 a 100) →list[SucursalReferenciaRead](id,is_activo,codigo,nombre): los mismos campos que la referencia de una, en una sola consulta.- Activas e inactivas (
is_activolo dice); las que no existen, están borradas o son de otra empresa no vienen, sin error, como enentidades/por-ids. Quien consulta decide qué hacer con las que faltan. Orden:nombreeid. - La empresa sale del token y va explícita en el SQL, además de la RLS, como en la referencia.
- En el router del tenant, con JWT normal: el servicio que consulta reenvía el token del usuario; el token administrativo no vale (401).
referencia/{id}no cambia: sigue sirviendo a quien valida una sola.
Alternativas descartadas¶
- Llamar
referenciaen paralelo desde el consumidor — sigue siendo una llamada por sucursal. - Que el consumidor use
GET /sucursales— trae todas para validar unas pocas (ADR 0063). POSTcon los ids en el cuerpo — es una lectura y con hasta 100 ids la URL alcanza (ADR 0062).- 404 si falta alguna — obligaría a una llamada más para saber cuál; la ausencia ya lo dice.
Consecuencias¶
- OpenAPI suma un endpoint de lectura; nada existente cambia.
- Fuerza de ventas valida las sucursales nuevas de un promotor en una llamada; clientes puede usarlo si llega a asignar varias a la vez.
- Pruebas unitarias (router con service falso y repository parcheado): campos y orden, desactivadas, inexistentes, borradas y de otra empresa omitidas, 422 con 0, más de 100 o un id inválido, 100 ids, 401 sin token y con token administrativo, y una sola consulta por el pool del tenant con la empresa del token. El SQL no tiene prueba de integración.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.