Saltar a contenido

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_juridicas es hoy mae_personas_comerciales y la ruta /juridicas es /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ólo true o false, nunca 404, como los existe de catálogos.
  • Cuenta como existente la entidad no borrada (deleted_at IS NULL), natural o jurídica, sin mirar is_activo ni el tipo. Una borrada y una que no existe dan false: quien consulta no necesita distinguirlas.
  • Se consulta la raíz: EntidadesRepository.existe_entidad hace un SELECT EXISTS sobre mae_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/410 o 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_id al crear un promotor con un solo pedido.
  • Pruebas unitarias:
  • Service (repository falso): true para natural y jurídica, false para una inexistente y para una borrada.
  • Router (service falso): responde 200 con true o false, sin 404, también después de borrarla.
  • El SQL no tiene prueba de integración (la carpeta tests/integration está vacía).

Qué no cubre

  • Entidades inactivas (is_activo = false sin 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.