0051. Endpoint de existencia de una entidad para otros servicios¶
Estado: Aceptado Fecha: 2026-10-26 Autor: David Garcia Módulo(s) afectado(s): app/domains/usuarios/, docs/adr/
Nota (ADR 0067):
mae_personas_juridicases hoymae_personas_comercialesy la ruta/juridicases/comerciales. Este ADR conserva los nombres de su fecha.
Contexto¶
Otros servicios guardan el id de una entidad sin FK entre bases.
svc-fuerza-ventas guarda entidad_id en sus promotores (su ADR 0047), que
puede ser una persona natural o una jurídica, y necesita rechazar al crearlo
un id que no existe o está borrado. El ADR 0050 dejó pendiente esa validación.
Hoy sólo se puede preguntar por tipo: GET /entidades/personas/{id} y
GET /entidades/juridicas/{id}, que traen la ficha completa y responden 404.
Para una entidad de tipo desconocido son dos pedidos, y un 404 no distingue
"no existe" de "la ruta no existe". Los catálogos ya resolvieron lo mismo con
/catalogos/tipos-identificacion/existe/{id} y /catalogos/ciudades/existe/{id}.
Decisión¶
GET /api/v1/entidades/existe/{entidad_id}responde sólotrueofalse, nunca 404, como losexistede catálogos.- Cuenta como existente la entidad no borrada (
deleted_at IS NULL), natural o jurídica, sin miraris_activoni el tipo. Una borrada y una que no existe danfalse: quien consulta no necesita distinguirlas. - Se consulta la raíz:
EntidadesRepository.existe_entidadhace unSELECT EXISTSsobremae_entidades. Cubre los dos tipos en una consulta y el borrado lógico marca la raíz junto con su hija (eliminar_entidad). - Bajo el router de entidades, protegido con JWT (ADR 0031): el servicio que consulta reenvía el token del usuario.
- Sólo se agrega código: un método del repository, uno del service, una ruta y sus pruebas.
Alternativas descartadas¶
- Pedir
/personas/{id}y, si da 404,/juridicas/{id}— dos pedidos, la ficha completa para leer un booleano, y un 404 ambiguo. GET /entidades/{id}con la ficha — el consumidor sólo necesita saber si existe; leer la ficha lo ata a campos que no usa.- Distinguir borrada de inexistente (
404/410o un objeto con estado) — ninguna regla de los consumidores actúa distinto según el caso.
Consecuencias¶
- OpenAPI suma un endpoint de lectura. Nada existente cambia.
- svc-fuerza-ventas valida
entidad_idal crear un promotor con un solo pedido. - Pruebas unitarias:
- Service (repository falso):
truepara natural y jurídica,falsepara una inexistente y para una borrada. - Router (service falso): responde 200 con
trueofalse, sin 404, también después de borrarla. - El SQL no tiene prueba de integración (la carpeta
tests/integrationestá vacía).
Qué no cubre¶
- Entidades inactivas (
is_activo = falsesin borrar): cuentan como existentes. Si un consumidor necesita rechazarlas, se decide aparte. - Consulta de varios ids a la vez: se agrega cuando un consumidor la necesite.