Vision general

ms-recargas - Vision general

ms-recargas es un microservicio NestJS 11 que actua como mediador entre el dashboard de NoviSuite, el ERP MBA3 y el SPR de Claro Ecuador para ejecutar recargas de pines y datos sobre el protocolo MOVILPOS v7.0.

Opera en dos modos complementarios:

Modo	Disparador	Intervencion humana
Automatico	n8n detecta factura de recarga en el correo interno	Ninguna
Manual	Operador busca o digita el numero en el dashboard	Confirma producto homologado, canton y OTP de accion

Proposito del modulo

• Recibir solicitudes HTTP autenticadas por JWT o x-service-key.
• Generar un external_transaction_id unico e idempotente.
• Construir el XML MOVILPOS v7.0 y enviarlo al SPR de Claro.
• Persistir cada transaccion en PostgreSQL con raw_request_xml y raw_response_xml como bitacora.
• Exponer endpoints de consulta de transacciones, estado real e inventario.
• Encolar notificaciones por email hacia sucursal y operaciones mediante BullMQ y ms-worker.
• Soportar CLARO_MOCK_MODE=true para desarrollo sin VPN al SPR.

Responsabilidades principales

• Traducir SKUs de MBA3 (product_code) al offer_id real de Claro.
• Separar errores de negocio (failed) de errores de transporte (unavailable).
• Garantizar idempotencia del webhook por source_xml_hash.
• Mantener trazabilidad completa de la operacion manual y automatica.

Resumen ejecutivo

Modo automatico

1. MBA3 genera la factura de recarga.
2. El correo con XML y PDF llega a la casilla interna.
3. n8n detecta el mensaje por IMAP, parsea el XML y valida producto RECCLARO* y telefono.
4. n8n llama POST /api/v1/recargas/webhook/invoice-recharge con x-service-key.
5. ms-recargas valida idempotencia, resuelve el mapping a Claro y ejecuta la recarga.
6. Si falla, encola email a sucursal; si sale bien, Claro envia el SMS y el servicio puede enviar confirmacion.

Modo manual

1. El operador abre la tab de recargas.
2. Busca factura por codigo o digita el numero manualmente.
3. Solicita y valida un action_token de un solo uso.
4. El dashboard ejecuta POST /api/v1/recargas/recharge con Bearer JWT y X-Action-Token.
5. ms-recargas registra la transaccion, llama al SPR y devuelve el resultado sincronico.

Consulta

• POST /api/v1/recargas/query-recharge: consulta el estado real en Claro.
• GET /api/v1/recargas/transactions: lista paginada local.
• GET /api/v1/recargas/inventory: stock disponible en el SPR.

Diagrama tecnico

Contrato HTTP expuesto

Endpoint	Metodo	Uso
/api/v1/recargas/recharge	POST	Recarga manual sincronica
/api/v1/recargas/webhook/invoice-recharge	POST	Recarga automatica desde n8n
/api/v1/recargas/query-recharge	POST	Consulta de estado real
/api/v1/recargas/transactions	GET	Listado paginado de transacciones
/api/v1/recargas/transactions/:id	GET	Detalle auditable de una transaccion
/api/v1/recargas/inventory	GET	Consulta de stock en el SPR
/up	GET	Health check

Datos base del servicio

Recurso	Valor
Puerto HTTP	3004
Base de datos	recargas_service_development
Redis	Cache JWT 60 s y cache OAuth2 Claro (claro:oauth:token)
SPR Claro	http://192.168.37.40:50004/sprXslt/sprXslt
Mock mode	CLARO_MOCK_MODE=true
BullMQ	Cola recharge-notifications
Worker de correo	ms-worker
n8n	Instancia externa, no incluida en docker compose
Health check	GET /up

Estructura del modulo

src/
├── recargas/
├── webhook/
├── notifications/
├── consultas/
├── claro-client/
├── auth-client/
├── entities/
├── redis/
└── common/

Integracion con Claro

ms-recargas consume tres funciones del contrato MOVILPOS v7.0:

Funcion Claro	Uso interno
sre_movilposd_76186	Ejecutar recargas de pines y datos
sre_consulta_recarga	Conciliar transacciones
sre_consulta_inventario	Consultar stock disponible

Todas usan CLARO_SPR_URL. En desarrollo, si no existe conectividad hacia la red privada de Claro, el servicio debe operar en mock o a traves del tunel SSH documentado en la guia de recargas.

Estados de transaccion

Estado	Significado
pending	Insert inicial antes de recibir resultado terminal
success	Claro confirmo la recarga
failed	Error de negocio devuelto por Claro
unavailable	SOAP Fault, timeout, ECONNREFUSED o SPR no disponible
rejected	El webhook rechazo la factura antes de llamar a Claro
ignored	n8n descarto el correo como no procesable
error	Estado legacy de registros anteriores a la separacion failed y unavailable

Reglas operativas clave

• Persistir la transaccion antes de llamar al SPR.
• Nunca mezclar product_code de MBA3 con offer_id de Claro.
• Guardar request y response crudos para auditoria.
• Diferenciar rechazo de negocio y falla de infraestructura.
• Tratar el webhook como flujo idempotente por source_xml_hash.

Navegacion recomendada

• Revisa Autenticacion y credenciales para JWT, ServiceKey y OTP de accion.
• Continua con Servicio de recargas para el contrato manual y automatico.
• Consulta Consulta de recarga para reconciliacion y trazabilidad.
• Revisa Consulta de inventario para stock y parsing.
• Usa Campos del contrato como referencia del XML MOVILPOS.
• Revisa Codigos de error para validaciones y fallos operativos.
• Consulta Documentos fuente para el respaldo base del contrato.