Manual de EMPRESA_JOSESAID

1. Mapa rápido de puertos

Estos son los puertos en tu Mac. Dentro de Docker, cada servicio usa su propio nombre y puerto interno.

2. Servicios de área

Cada servicio es dueño de sus datos y tiene su propia base de datos en PostgreSQL. Ningún servicio lee la base de otro: se comunican por la API o por eventos de Kafka.

Ventas y clientes

Finanzas

Operaciones y compras

Legal

Dirección

Acceso

3. Infraestructura

4. Cómo viaja una solicitud

El servicio de área valida el token JWT y revisa el rol. Si la operación cambia datos y debe avisar a otras áreas, guarda el evento en su tabla outbox_eventos dentro de la misma transacción. Un proceso lo envía después a Kafka. Así un evento nunca se pierde aunque Kafka esté caído en ese momento.

Las solicitudes quedan registradas en Jaeger de principio a fin, y sus métricas llegan a Prometheus.

5. Orden para levantar todo

1. Red y base: docker network create empresa-net (una sola vez), luego docker compose up -d postgres kafka.
2. Registro: docker compose up -d discovery-ms. Los servicios deben encontrarlo al arrancar.
3. Gateway y servicios de área: docker compose up -d --build desde la raíz. Pueden levantarse en cualquier orden entre sí.
4. Monitoreo y trazas: ya quedan incluidos en el mismo comando.

Cada servicio también puede levantarse solo desde su carpeta. Su README indica qué necesita antes.

6. Dónde revisar que todo funciona

• Servicios registrados: http://localhost:8761 (con usuario y contraseña de Eureka)
• Salud de un servicio: http://localhost:8080/clientes-ms/actuator/health (clientes-ms; los demás tienen su propio puerto)
• Objetivos de métricas: http://localhost:9090/targets
• Tableros: http://localhost:3000
• Trazas: http://localhost:16686

7. Glosario

Microservicio

Programa pequeño que hace una sola cosa de negocio y tiene su propia base de datos.

Gateway

Punto de entrada único que reenvía cada solicitud al servicio correcto.

Eureka (discovery)

Registro donde cada servicio se anuncia para que los demás lo encuentren.

JWT

Token firmado que identifica al usuario y su rol. Lo emite usuarios-accesos-ms.

DDD

Diseño guiado por el dominio: el código se organiza según los conceptos del negocio, como Cotización o Reporte.

Outbox

Tabla donde un servicio deja los eventos que debe publicar, dentro de la misma transacción que el cambio de datos.

Flyway

Herramienta que aplica los cambios de la base de datos en orden y una sola vez.

RFC 9457

Formato estándar de los errores de la API: indica tipo, título, estado y detalle.

Trazas (OTLP)

Protocolo con el que los servicios envían sus trazas a Jaeger.

Métricas (Prometheus)

Números que describen el estado de cada servicio: memoria, solicitudes y tiempos.

8. Lo que falta por decidir

• Rotación de la clave RS256 con periodo de traslape implementada (procedimiento en usuarios-accesos-ms/README.md). Falta definir el calendario de rotación.
• Cambio de la contraseña temporal de los diez jefes de área: cada uno debe cambiarla antes de iniciar sesión.
• Revocar también el access token al cerrar sesión; hoy vence en 15 minutos.
• Métricas: ningún servicio de área publica puerto; solo el gateway (8080) y Eureka (8761). El gateway bloquea /actuator.
• Órdenes de compra anteriores a V3: reciben en V4 la fecha de aplicación de la migración, por lo que cuentan en ese mes. Confirmar si el criterio es aceptable.

9. Endpoints y ejemplos JSON por microservicio

Cada bloque lista las rutas de un servicio y un cuerpo de ejemplo para probarlas. Por el gateway, la ruta lleva el nombre del servicio al inicio: http://localhost:8080/clientes-ms/v1/clientes. También se puede llamar directo al puerto del servicio (sección 1): http://localhost:8080/clientes-ms/v1/clientes.

Todas las rutas, salvo el login, piden el encabezado Authorization: Bearer <token>. Los ejemplos usan un UUID de prueba, 3fa85f64-5717-4562-b3fc-2c963f66afa6: reemplácelo por el id real que devuelve cada creación.

Formatos: fecha 2026-10-29, instante UTC 2026-10-29T16:30:00Z, mes o periodo 2026-10. Los errores siguen RFC 9457 (campos type, title, status y detail). Los campos que no aparecen como obligatorios pueden omitirse.

Primer paso: obtener el token

curl -s -X POST http://localhost:8080/usuarios-accesos-ms/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"correo":"admin@empresa.mx","password":"<su-contraseña>"}'

La respuesta trae accessToken, tokenType y expiresIn. Ese valor va en el encabezado Authorization de las demás llamadas.

Clientes · /clientes-ms

Método	Ruta	Para qué
POST	/v1/prospectos	Crea un prospecto. Con ?confirmarDuplicado=true lo crea aun si hay un posible duplicado.
GET	/v1/prospectos/{id}	Consulta un prospecto.
PATCH	/v1/prospectos/{id}/estatus	Cambia el estatus del prospecto.
POST	/v1/prospectos/{id}/conversion	Convierte el prospecto en cliente con su contacto principal.
POST	/v1/clientes	Crea un cliente directamente.
GET	/v1/clientes?rfc=&nombre=	Busca clientes por RFC o por nombre.
GET	/v1/clientes/{id}	Consulta un cliente.
PATCH	/v1/clientes/{id}	Cambia la razón social.
PATCH	/v1/clientes/{id}/estatus	Cambia el estatus del cliente.
POST	/v1/clientes/{id}/contactos	Agrega un contacto al cliente.
POST	/v1/contactos/{contactoId}/consentimientos	Registra un consentimiento de privacidad del contacto.
POST	/v1/consentimientos/{id}/revocacion	Revoca un consentimiento. No lleva cuerpo.
POST	/v1/clientes/{clienteId}/interacciones	Registra una llamada, correo o visita.
GET	/v1/clientes/{clienteId}/interacciones	Lista las interacciones del cliente.
GET	/v1/metricas/conversion?mes=2026-10	Tasa de conversión de prospectos a clientes en el mes.

fuente

CAMPANA, REFERIDO, EVENTO

rol

COMPRAS, PAGOS, ASISTENCIA

medio

FORMULARIO, CORREO, TELEFONO, PRESENCIAL

tipo

LLAMADA, CORREO, VISITA

estatus (prospecto)

NUEVO, CONTACTADO, CALIFICADO, CONVERTIDO, PERDIDO

estatus (cliente)

ACTIVO, SUSPENDIDO, BAJA

Crear un prospecto

POST /clientes-ms/v1/prospectos
{
  "nombre": "Distribuidora del Norte",
  "correo": "compras@norte.mx",
  "rfc": "ABC850101XY1",
  "fuente": "REFERIDO"
}

Cambiar el estatus de un prospecto

PATCH /clientes-ms/v1/prospectos/{id}/estatus
{
  "estatus": "CONTACTADO"
}

Convertir un prospecto en cliente

POST /clientes-ms/v1/prospectos/{id}/conversion
{
  "razonSocial": "Distribuidora del Norte SA de CV",
  "rfc": "ABC850101XY1",
  "contactoPrincipal": {
    "nombre": "Ana López",
    "correo": "ana.lopez@norte.mx",
    "rol": "COMPRAS"
  }
}

Crear un cliente

POST /clientes-ms/v1/clientes
{
  "razonSocial": "Distribuidora del Norte SA de CV",
  "rfc": "ABC850101XY1",
  "contactoPrincipal": {
    "nombre": "Ana López",
    "correo": "ana.lopez@norte.mx",
    "rol": "COMPRAS"
  }
}

Agregar un contacto

POST /clientes-ms/v1/clientes/{id}/contactos
{
  "nombre": "Luis Pérez",
  "correo": "luis.perez@norte.mx",
  "rol": "PAGOS",
  "principal": false
}

Registrar un consentimiento

POST /clientes-ms/v1/contactos/{contactoId}/consentimientos
{
  "finalidad": "Envío de promociones",
  "fechaOtorgado": "2026-10-29T10:00:00Z",
  "medio": "FORMULARIO",
  "vigencia": "2027-10-29"
}

Registrar una interacción

POST /clientes-ms/v1/clientes/{clienteId}/interacciones
{
  "tipo": "LLAMADA",
  "fecha": "2026-10-29T16:30:00Z",
  "resumen": "Confirmó interés en el catálogo 2027."
}

Usuarios y accesos · /usuarios-accesos-ms

Método	Ruta	Para qué
POST	/v1/auth/login	Obtiene el token JWT. Es pública. Si la contraseña es temporal, responde 403 hasta que se cambie.
POST	/v1/usuarios	Crea un usuario con sus roles.
GET	/v1/usuarios/{id}	Consulta un usuario. Los datos personales salen enmascarados.
PUT	/v1/usuarios/{id}/roles	Cambia los roles del usuario. Pide un motivo.
POST	/v1/usuarios/{id}/baja	Da de baja al usuario. No lleva cuerpo.
POST	/v1/auth/cambiar-password-inicial	Cambia la contraseña temporal por una definitiva. Pide la temporal actual y responde 204.

roles

ADMIN, FINANZAS, CONTADOR, VENTAS, COMPRAS, ALMACEN, OPERACIONES, CALIDAD, DIRECCION, LEGAL, JEFE_AREA

Crear un usuario

POST /usuarios-accesos-ms/v1/usuarios
{
  "correo": "marta.ruiz@empresa.mx",
  "nombreCompleto": "Marta Ruiz Vega",
  "password": "<contraseña-segura>",
  "roles": ["CONTADOR", "FINANZAS"]
}

Cambiar roles

PUT /usuarios-accesos-ms/v1/usuarios/{id}/roles
{
  "roles": ["VENTAS", "DIRECCION"],
  "motivo": "Cambio de área"
}

Cambiar la contraseña temporal

Las cuentas dadas de alta por la API tienen contraseña temporal. Mientras no la cambien, el login responde 403. Cada usuario la cambia una vez, sin token:

POST /usuarios-accesos-ms/v1/auth/cambiar-password-inicial
{
  "correo": "jefe.ventas1@empresa.mx",
  "passwordActual": "<contraseña-temporal>",
  "passwordNueva": "<contraseña-definitiva-de-12-o-mas>"
}

Facturación y pagos · /facturacion-pagos-ms

Método	Ruta	Para qué
POST	/v1/comprobantes	Crea un comprobante en borrador para una orden.
GET	/v1/comprobantes/{id}	Consulta un comprobante.
POST	/v1/comprobantes/{id}/emision	Emite el comprobante. No lleva cuerpo.
POST	/v1/comprobantes/{id}/cancelacion	Cancela el comprobante con un motivo.
POST	/v1/comprobantes/{id}/pagos	Registra un pago contra el comprobante.

tasaIva

Decimal entre 0 y 1: 0.16 para IVA general, 0.08 para fronterizo, 0 para exento

Crear un comprobante

POST /facturacion-pagos-ms/v1/comprobantes
{
  "ordenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "moneda": "MXN",
  "subtotal": 1500.00,
  "tasaIva": 0.16
}

Registrar un pago

POST /facturacion-pagos-ms/v1/comprobantes/{id}/pagos
{
  "monto": 500.00,
  "fechaPago": "2026-10-29",
  "referencia": "SPEI-998877"
}

Cancelar un comprobante

POST /facturacion-pagos-ms/v1/comprobantes/{id}/cancelacion
{
  "motivo": "Error en el importe"
}

Contabilidad · /contabilidad-ms

Método	Ruta	Para qué
POST	/v1/cuentas	Crea una cuenta del catálogo contable.
POST	/v1/polizas	Registra una póliza con al menos dos movimientos.
GET	/v1/polizas/{id}	Consulta una póliza.
POST	/v1/polizas/{id}/reversa	Reversa una póliza. No lleva cuerpo.
POST	/v1/periodos/{anioMes}/cierre	Cierra el periodo, por ejemplo 2026-10.
GET	/v1/estados-financieros?periodo=2026-10	Balanza del periodo.

naturaleza

DEUDORA, ACREEDORA

tipo (póliza)

INGRESO, EGRESO, DIARIO

cargo / abono

Cada movimiento usa uno de los dos

cuentaId

El id que devolvió la creación de la cuenta

Crear una cuenta

POST /contabilidad-ms/v1/cuentas
{
  "codigo": "1010-001",
  "nombre": "Bancos moneda nacional",
  "naturaleza": "DEUDORA"
}

Registrar una póliza de ingreso

POST /contabilidad-ms/v1/polizas
{
  "tipo": "INGRESO",
  "fecha": "2026-10-29",
  "movimientos": [
    { "cuentaId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "cargo": 1160.00 },
    { "cuentaId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "abono": 1160.00 }
  ]
}

Inventario · /inventario-operaciones-ms

Método	Ruta	Para qué
POST	/v1/articulos	Da de alta un artículo con su SKU.
POST	/v1/almacenes	Da de alta un almacén.
POST	/v1/movimientos	Registra una entrada, salida, ajuste o reserva.
GET	/v1/existencias?articulo={id}	Existencias de un artículo por almacén.
POST	/v1/ordenes-operacion	Abre una orden de producción o de servicio.
POST	/v1/ordenes-operacion/{id}/cierre	Cierra la orden con la cantidad real producida.
GET	/v1/lotes/{lote}/trazabilidad	Movimientos de un lote, de principio a fin.

tipo (movimiento)

ENTRADA, SALIDA, AJUSTE, RESERVA

tipo (orden)

PRODUCCION, SERVICIO

cantidad

Admite tres decimales

Crear un artículo

POST /inventario-operaciones-ms/v1/articulos
{
  "sku": "TOR-M8-50",
  "nombre": "Tornillo M8 x 50 mm",
  "unidad": "PZA",
  "loteObligatorio": true,
  "minimo": 100
}

Registrar una entrada con lote

POST /inventario-operaciones-ms/v1/movimientos
{
  "articuloId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "almacenId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tipo": "ENTRADA",
  "cantidad": 250.000,
  "lote": "L-2026-10A",
  "referencia": "OC-000123"
}

Abrir y cerrar una orden de producción

POST /inventario-operaciones-ms/v1/ordenes-operacion
{
  "tipo": "PRODUCCION",
  "cantidadObjetivo": 500.000
}

POST /inventario-operaciones-ms/v1/ordenes-operacion/{id}/cierre
{
  "cantidadReal": 487.500
}

Compras y proveedores · /compras-proveedores-ms

Método	Ruta	Para qué
POST	/v1/proveedores	Da de alta un proveedor.
GET	/v1/proveedores/{id}	Consulta un proveedor. El RFC sale enmascarado.
POST	/v1/ordenes-compra	Crea una orden de compra con sus líneas.
GET	/v1/ordenes-compra/{id}	Consulta una orden de compra.
POST	/v1/ordenes-compra/{id}/aprobacion	Aprueba la orden. COMPRAS la aprueba por debajo de 1,000,000 USD y DIRECCION en cualquier monto; nadie aprueba una orden que creó. No lleva cuerpo.
POST	/v1/ordenes-compra/{id}/recepciones	Registra la mercancía recibida.
POST	/v1/ordenes-compra/{id}/cancelacion	Cancela la orden con un motivo.

Crear un proveedor

POST /compras-proveedores-ms/v1/proveedores
{
  "razonSocial": "Aceros del Bajío SA de CV",
  "rfc": "ABC850101XY1",
  "correo": "ventas@acerosbajio.mx"
}

Crear una orden de compra

POST /compras-proveedores-ms/v1/ordenes-compra
{
  "proveedorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "moneda": "MXN",
  "lineas": [
    { "articuloSku": "TOR-M8-50", "cantidad": 500, "precioUnitario": 2.50 }
  ]
}

Registrar una recepción

POST /compras-proveedores-ms/v1/ordenes-compra/{id}/recepciones
{
  "lineas": [
    { "articuloSku": "TOR-M8-50", "cantidad": 480 }
  ]
}

Cancelar una orden

POST /compras-proveedores-ms/v1/ordenes-compra/{id}/cancelacion
{
  "motivo": "Proveedor sin existencias"
}

Pedidos y ventas · /pedidos-ventas-ms

Método	Ruta	Para qué
POST	/v1/cotizaciones	Crea una cotización con sus líneas.
GET	/v1/cotizaciones/{id}	Consulta una cotización.
POST	/v1/cotizaciones/{id}/envio	Marca la cotización como enviada. No lleva cuerpo.
POST	/v1/cotizaciones/{id}/aceptacion	Acepta la cotización. Si ya venció responde 410.
POST	/v1/cotizaciones/{id}/pedido	Convierte una cotización aceptada en pedido. No lleva cuerpo.
POST	/v1/pedidos	Crea un pedido directamente.
GET	/v1/pedidos?clienteId=&estatus=&canal=	Busca pedidos. Todos los filtros son opcionales.
GET	/v1/pedidos/{id}	Consulta un pedido.
PUT	/v1/pedidos/{id}/lineas	Reemplaza las líneas del pedido en borrador.
POST	/v1/pedidos/{id}/confirmacion	Confirma el pedido. No lleva cuerpo.
POST	/v1/pedidos/{id}/entrega	Marca el pedido como entregado. No lleva cuerpo.
POST	/v1/pedidos/{id}/cancelacion	Cancela el pedido con un motivo.
POST	/v1/pedidos/{id}/devolucion	Registra la devolución del pedido. No lleva cuerpo.
GET	/v1/metricas/ventas?mes=2026-10	Ventas netas del mes por moneda.
GET	/v1/catalogos/tasas-iva	Tasas de IVA disponibles.
GET	/v1/catalogos/monedas	Monedas disponibles.

canal

WEB, TIENDA, TELEFONO

tasaIva

IVA_GENERAL, IVA_FRONTERIZO, IVA_EXENTO

motivo (cancelación)

CANCELACION_CLIENTE, ERROR_CAPTURA, DEVOLUCION_TOTAL

Crear una cotización

POST /pedidos-ventas-ms/v1/cotizaciones
{
  "clienteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "canal": "WEB",
  "moneda": "MXN",
  "tasaIva": "IVA_GENERAL",
  "vigenteHasta": "2026-11-30",
  "lineas": [
    { "productoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "descripcion": "Licencia anual", "cantidad": 2, "precioUnitario": 1200.00 }
  ]
}

Crear un pedido

POST /pedidos-ventas-ms/v1/pedidos
{
  "clienteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "canal": "TELEFONO",
  "moneda": "MXN",
  "tasaIva": "IVA_FRONTERIZO",
  "lineas": [
    { "productoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "cantidad": 3, "precioUnitario": 1200.00 }
  ]
}

Reemplazar las líneas de un pedido

PUT /pedidos-ventas-ms/v1/pedidos/{id}/lineas
{
  "lineas": [
    { "productoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "cantidad": 4, "precioUnitario": 1200.00 }
  ]
}

Cancelar un pedido

POST /pedidos-ventas-ms/v1/pedidos/{id}/cancelacion
{
  "motivo": "CANCELACION_CLIENTE"
}

Documentos de cumplimiento · /documentos-cumplimiento-ms

Método	Ruta	Para qué
POST	/v1/documentos	Sube un documento nuevo. Es multipart/form-data con dos partes: datos (JSON) y archivo.
POST	/v1/documentos/{id}/versiones	Agrega una versión. Es multipart/form-data con la parte archivo.
GET	/v1/documentos/{id}	Consulta el documento y sus versiones. Nunca muestra la ruta de almacenamiento.
GET	/v1/documentos/{id}/versiones/{n}/descarga	Descarga la versión n.
GET	/v1/documentos/por-vencer?dias=30	Documentos que vencen en los próximos días.
POST	/v1/documentos/{id}/eliminacion	Marca el documento para eliminación con un motivo.
GET	/v1/catalogos/tipos-documento	Tipos de documento y su retención en años.

tipo

CONTRATO, PERMISO, REGISTRO_LEGAL

Las versiones no se pueden modificar.

Subir un documento (curl)

curl -X POST http://localhost:8080/documentos-cumplimiento-ms/v1/documentos \
  -H "Authorization: Bearer $TOKEN" \
  -F 'datos={"tipo":"CONTRATO","titulo":"Contrato marco de servicios 2026","area":"Administración y legal","venceEn":"2027-12-31"};type=application/json' \
  -F "archivo=@/ruta/al/contrato.pdf"

Agregar una versión (curl)

curl -X POST http://localhost:8080/documentos-cumplimiento-ms/v1/documentos/{id}/versiones \
  -H "Authorization: Bearer $TOKEN" \
  -F "archivo=@/ruta/al/contrato-v2.pdf"

Solicitar eliminación

POST /documentos-cumplimiento-ms/v1/documentos/{id}/eliminacion
{
  "motivo": "Reemplazado por una versión nueva"
}

Reportes ejecutivos · /reportes-ejecutivos-ms

Método	Ruta	Para qué
POST	/v1/indicadores	Registra un indicador de un área. Las áreas también pueden enviarlo por Kafka en el tópico indicadores-areas.
GET	/v1/indicadores?periodo=2026-10&area=	Consulta indicadores por periodo. El filtro area es opcional.
GET	/v1/reportes/{periodo}	Consulta el reporte consolidado del periodo.
POST	/v1/reportes/{periodo}/cierre	Cierra el reporte. Guarda una foto que ya no cambia. No lleva cuerpo.
GET	/v1/reportes/{id}/exportacion?formato=CSV	Descarga el reporte en CSV, PDF o XLSX.

area

VENTAS_ATENCION_CLIENTES, FINANZAS_CONTABILIDAD, OPERACIONES, COMPRAS_PROVEEDORES, ADMINISTRACION_LEGAL, DIRECCION_GENERAL

formato

CSV, PDF, XLSX

Registrar un indicador

POST /reportes-ejecutivos-ms/v1/indicadores
{
  "area": "OPERACIONES",
  "nombre": "Órdenes cerradas",
  "periodo": "2026-10",
  "valor": 12.5,
  "fuenteActualizadaUtc": "2026-10-29T10:00:00Z"
}

Descargar el reporte en PDF (curl)

curl -o reporte.pdf "http://localhost:8080/reportes-ejecutivos-ms/v1/reportes/{id}/exportacion?formato=PDF" \
  -H "Authorization: Bearer $TOKEN"

Registro (discovery-ms) y gateway-ms

Eureka recibe el anuncio de cada servicio al arrancar, y el gateway usa ese registro para encontrar a dónde reenviar cada solicitud.