Saltar a contenido

0031. Persona comercial y tipo de contribuyente

Estado: Aceptado Fecha: 2026-11-16 Autor: Duval Alcivar Módulo(s) afectado(s): svc-identidad (core_sigfa), modelo de entidades, contratos de la API y plantilla de navegación; panel core-admin Modifica a: ADR 0022, ADR 0026 Origen: ADR 0067 de implementación

Contexto

El ADR 0022 clasificó las entidades del patrón party en PERSONA_NATURAL y PERSONA_JURIDICA. Ese eje mezcla dos cosas distintas: la naturaleza de la entidad (un humano o un sujeto comercial) y el régimen tributario (persona natural o sociedad). Un profesional con RUC es una persona natural en lo tributario, pero no cabía en ninguna de las dos tablas sin forzar el modelo. Además, la cédula o el pasaporte identifican a la persona; el RUC identifica a quien factura.

Decisión

  • mae_entidades.tipo_entidad pasa a PERSONA y PERSONA_COMERCIAL.
  • mae_personas_juridicas pasa a mae_personas_comerciales. La cédula y el pasaporte siguen en mae_personas; el RUC vive en mae_personas_comerciales.
  • Nueva columna mae_personas_comerciales.tipo_contribuyente (String(20), NOT NULL, CHECK en PERSONA_NATURAL o PERSONA_JURIDICA): obligatoria al crear, editable por el administrador y expuesta en las lecturas, el perfil y la lista común de entidades (null en las personas).
  • Un mismo humano puede existir como dos entidades independientes, una PERSONA y una PERSONA_COMERCIAL. No hay vínculo ni clave foránea entre ambas.
  • API, renombrado duro y sin alias: /api/v1/entidades/juridicas pasa a /comerciales y /api/v1/entidades/admin/juridicas a /admin/comerciales. En el alta, EntidadCreate.juridica pasa a comercial. El perfil propio es la unión PerfilPersonaRead | PerfilPersonaComercialRead.
  • Plantilla de navegación: persona_natural pasa a persona ("Personas", /config/entidades/personas) y persona_juridica a persona_comercial ("Personas comerciales", /config/entidades/personas-comerciales).
  • No se valida el formato del RUC según tipo_contribuyente.
  • La clave foránea de mae_personas_comerciales.tipo_identificacion_id lleva nombre explícito (fk_mae_personas_comerciales_tipo_identificacion_id), porque el de la convención superaba los 63 caracteres de PostgreSQL. La regla general queda en el ADR 0004 transversal.

Alternativas descartadas

  • Vincular la persona con su comercial por clave foránea — YAGNI: nada consume el vínculo hoy y rellenarlo después es barato (el RUC de una persona natural es su cédula más 001, salvo con pasaporte, donde se resuelve a mano).
  • Mantener PERSONA_JURIDICA y agregar un tercer valor para el profesional con RUC — deja el eje mezclado y duplica el criterio tributario.
  • Conservar las rutas viejas como alias — el único consumidor es el panel, que se actualiza junto con el servicio.

Consecuencias

  • Los clientes que enviaban PERSONA_NATURAL o PERSONA_JURIDICA como tipo_entidad, o juridica en el alta, reciben 422; el panel y el servicio se despliegan juntos.
  • Un alta de persona comercial sin tipo_contribuyente responde 422.
  • La migración 20261116_001 convierte los datos: las filas existentes quedan con tipo_contribuyente = 'PERSONA_JURIDICA' y el menú de todas las empresas se renombra. El downgrade pierde tipo_contribuyente con la columna.
  • En core-admin: vistas PersonaView.vue y PersComercialView.vue, rutas entidades/personas y entidades/personas-comerciales, y pestañas "Persona" y "Persona comercial" en el alta de usuario, con tipo de contribuyente obligatorio (ver los ADR 0011 y 0013 del panel).
  • El modelo de datos vigente está en docs-sql (mae_entidades, mae_personas, mae_personas_comerciales).

Resume el ADR 0067 de implementación, que fija la fecha de esta decisión.