Saltar a contenido

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_activo lo dice); las que no existen, están borradas o son de otra empresa no vienen, sin error, como en entidades/por-ids. Quien consulta decide qué hacer con las que faltan. Orden: nombre e id.
  • 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 referencia en paralelo desde el consumidor — sigue siendo una llamada por sucursal.
  • Que el consumidor use GET /sucursales — trae todas para validar unas pocas (ADR 0063).
  • POST con 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.