Saltar a contenido

0008. Flujo de alta de empresa (onboarding multiempresa)

Estado: Propuesto Fecha: 2026-09-08 Autor: Duval Alcivar Módulo(s) afectado(s): svc-identidad (core_sigfa), svc-erp, svc-crm

Contexto

Cuando se crea una empresa nueva en el sistema, esta se registra en svc-identidad (el servicio dueño de usuarios y empresas, ver ADR 0004). Pero la empresa también necesita existir en los demás sistemas: el ERP debe crearle su numeración de facturas, el CRM sus configuraciones, etc.

El problema: ¿cómo avisamos a los otros sistemas que hay una empresa nueva? Si lo hacemos a mano, alguien tiene que entrar a cada sistema y repetir el registro. Si svc-identidad llama directamente a cada sistema en el momento del alta y uno de ellos está caído, el alta falla a medias.

Conceptos usados en este documento

Término Qué es (en palabras simples)
Servicio Un sistema independiente que hace una parte del trabajo. Ejemplo: svc-identidad maneja usuarios y empresas; el ERP maneja facturas. Cada uno tiene su propia base de datos.
empresa_id El número único que identifica a cada empresa en toda la plataforma. Todos los sistemas lo usan para saber de qué empresa es cada dato.
Bandeja de salida (outbox) Una tabla de la base de datos donde se guardan los avisos pendientes de enviar. Como la bandeja de "enviados pendientes" de un correo: primero se guarda, luego se envía.
Aviso / mensaje / evento Un mensaje que un sistema le envía a otro para avisarle que algo pasó (ejemplo: "se creó una empresa"). En este documento las tres palabras significan lo mismo.
trace_id Un código único que identifica cada aviso. Como el número de tracking de un paquete: permite rastrearlo en los registros (logs) de todos los sistemas por los que pasa.
API (llamada HTTP) La forma en que un sistema le habla a otro hoy: le hace una petición directa, como cuando el navegador le pide datos a un servidor.
Kafka Una herramienta de mensajería (mensajero intermediario) que se usará en el futuro: en vez de que los sistemas se llamen directamente, dejan los avisos en Kafka y los demás los recogen de ahí. Más robusto cuando hay muchos mensajes.
Endpoint La "dirección" a la que se envía una petición dentro de un sistema. Ejemplo: POST /api/v1/empresas es la dirección que crea empresas.
Reintento Si el envío de un aviso falla (sistema caído), se vuelve a intentar automáticamente cada cierto tiempo hasta que llegue. Nada se pierde.

Decisión

El alta se hace en dos pasos separados:

Paso 1 — Guardar en svc-identidad (lo único que pasa "en el momento")

Cuando el administrador crea la empresa (POST /api/v1/empresas), svc-identidad guarda todo junto en una sola operación de base de datos (si algo falla, no se guarda nada):

  • La empresa (mae_empresas).
  • Las sucursales, solo si se registraron (una empresa puede existir sin sucursales; no se crea ninguna automática para no duplicar información en reportes).
  • Las aplicaciones contratadas (rel_empresa_aplicacion: ERP, CRM, etc.).
  • El usuario administrador inicial de la empresa (para que alguien pueda entrar desde el primer momento).
  • Un mensaje de aviso pendiente en una tabla llamada outbox ("bandeja de salida").

El aprovisionamiento completo del tenant (clon de la plantilla de navegación del ADR 0013, permisos base del 0014 y acceso del usuario inicial con sus acciones del 0015) se detalla en el ADR 0016; aquí solo se lista como parte del mismo flush.

Paso 2 — Avisar a los demás sistemas (minutos después, en segundo plano)

Un proceso automático revisa la bandeja de salida cada minuto (ADR transversal 0015) y envía el aviso a cada sistema suscrito (ERP, CRM). Hoy lo envía por una llamada HTTP (API); en el futuro se usará Kafka, pero el mensaje ya tiene el formato final para que ese cambio sea sencillo.

¿Qué contiene el aviso? Un mensaje con esta estructura fija:

{
  "evento": "empresa.creada",        // QUÉ pasó: el nombre del suceso
  "trace_id": "<uuid>",              // código único de seguimiento (como el tracking de un paquete)
  "payload": {                       // LOS DATOS: lo que los demás sistemas necesitan saber
    "empresa_id": 1,                 // el número único de la empresa en toda la plataforma
    "nombre": "Empresa Demo",        // nombre legal de la empresa
    "identificacion": "0999999999001", // identificación tributaria (RUC en Ecuador)
    "sucursales": [],                // sucursales registradas (vacío si no tiene)
    "aplicaciones": ["erp", "crm"]   // qué sistemas contrató la empresa
  }
}

Cada parte del mensaje, en palabras simples:

Parte Qué es Para qué sirve
evento El nombre de lo que pasó: "empresa.creada" El sistema que recibe sabe qué hacer con el mensaje
trace_id Un código único de seguimiento Como el número de tracking de un paquete: permite rastrear este aviso en los logs de todos los sistemas
payload Los datos de la empresa creada Lo que el ERP/CRM necesita para registrar la empresa (su id, nombre, sucursales, aplicaciones)

sucursales va vacío si la empresa no registró ninguna. Los sistemas que reciben el aviso deben aceptar la lista vacía sin fallar.

Reglas del aviso:

  • El aviso se guarda primero en la base de datos y se envía después. Si un sistema está caído, el proceso lo reintenta hasta que responda. La empresa ya está creada y operativa en svc-identidad mientras tanto.
  • Cada sistema procesa el aviso una sola vez aunque llegue repetido (por eso se identifica con evento + empresa_id).
  • El formato del mensaje no cambiará: hoy viaja por HTTP, mañana por Kafka. Migrar a Kafka solo cambia cómo se transporta el mensaje, no su contenido ni lo que hacen los sistemas al recibirlo.
  • Cuando luego se creen sucursales nuevas, se envía un aviso igual llamado sucursal.creada.

Reglas de negocio

  • Solo svc-identidad crea empresas. Ningún otro sistema puede inventar un empresa_id por su cuenta.
  • Las sucursales son opcionales. Una empresa puede operar sin sucursales; las consultas y reportes deben funcionar igual (sin exigir sucursal).
  • El alta no se bloquea por otros sistemas. Aunque el ERP esté apagado, la empresa se crea igual; el ERP se pone al día cuando vuelva.

Alternativas descartadas

  • Avisar a cada sistema dentro del mismo momento del alta — si el ERP está caído, el alta falla o queda a medias.
  • Usar Kafka desde el primer día — es infraestructura compleja que aún no necesitamos; el formato del mensaje ya queda listo para adoptarlo después.
  • Que todos los sistemas lean la misma base de datos — los acopla: un cambio de tabla en identidad rompería al ERP y al CRM.
  • Registrar la empresa a mano en cada sistema — lento y propenso a errores de digitación.

Consecuencias

  • Crear una empresa es rápido y seguro: no depende de que los demás sistemas estén funcionando.
  • Los demás sistemas se enteran segundos o minutos después (no al instante). Es un retraso aceptable para un proceso administrativo que ocurre pocas veces.
  • Cada sistema (ERP, CRM) debe tener un endpoint que reciba estos avisos y los procese sin duplicar trabajo si el aviso llega repetido.
  • El día que se adopte Kafka, no hay que rediseñar los mensajes ni los sistemas que los reciben: solo cambia el canal de entrega. El versionado de los eventos quedó resuelto en el ADR 0019 del índice (empresa.creada.v1).