Servicio de recargas

Servicio de recargas

ms-recargas expone dos caminos para ejecutar recargas contra Claro:

• modo manual desde el dashboard
• modo automatico desde n8n usando el webhook de facturas

En ambos casos el envio real hacia Claro termina en la funcion sre_movilposd_76186 del protocolo MOVILPOS v7.0.

Diagrama tecnico

Endpoint principal manual

POST /api/v1/recargas/recharge

Ejecuta una recarga sincronica desde el dashboard.

Autenticacion: Bearer JWT con permiso create_recargas + X-Action-Token

Body soportado

{
  "subscriber_id": "593986686257",
  "offer_id": "150",
  "quantity": 1,
  "external_operation": "RECARGA_DATOS",
  "canton": "0101"
}

Campos obligatorios

Campo	Tipo	Regla
subscriber_id	string	12 digitos. Debe cumplir ^593[89]\d{8}$
offer_id	string	Obligatorio, no vacio
quantity	number	Entero mayor o igual a 1. En la UI actual va fijo en 1
external_operation	enum	RECARGA_DATOS o RECARGA_PINES
canton	string	Codigo INEC de 4 digitos

Reglas de seguridad y aprobacion

• Bearer JWT valido.
• Permiso create_recargas.
• X-Action-Token valido, no expirado y no reutilizado.
• Throttling 5/60s por usuario para el grupo recharge.
• Limite diario RECARGAS_DAILY_LIMIT salvo permiso unlimited_recargas.

Respuesta exitosa

{
  "success": true,
  "transaction_id": "f2c0a4d8-...-uuid",
  "external_transaction_id": "17451234567890123",
  "status": "success",
  "claro_id_recarga": "447435057",
  "claro_id_codigo": "0",
  "message": "Se realizo con exito la recarga"
}

Rechazo logico

{
  "success": false,
  "transaction_id": "f2c0a4d8-...-uuid",
  "external_transaction_id": "17451234567890123",
  "status": "error",
  "error": "El numero no pertenece a Claro o no esta activo",
  "message": "ERROR"
}

Respuestas de infraestructura

• 400 Bad Request: DTO invalido
• 401 Unauthorized: JWT invalido o expirado
• 401 Unauthorized: X-Action-Token invalido, expirado o ya usado
• 403 Forbidden: falta permiso create_recargas
• 429 Too Many Requests: limite por minuto o limite diario alcanzado
• 502 Bad Gateway: SOAP Fault o error de transporte del SPR
• 504 Gateway Timeout: Claro no respondio dentro del timeout

Endpoint automatico para n8n

POST /api/v1/recargas/webhook/invoice-recharge

Recibe la factura parseada por n8n y ejecuta la recarga de forma automatica.

Autenticacion: x-service-key

Body

{
  "invoice_number": "001-001-000045678",
  "invoice_code": "FAC-2026-04-0456",
  "product_code": "RECCLARO5",
  "subscriber_id": "593986686257",
  "amount": 5,
  "notification_email": "[email protected]",
  "source_xml_hash": "sha256:a1b2c3...",
  "canton": "0901"
}

Campos

Campo	Tipo	Regla
invoice_number	string	Numero SRI de factura
invoice_code	string	Codigo interno de MBA3
product_code	string	Debe matchear el patron RECCLARO*
subscriber_id	string	12 digitos. Debe cumplir ^593[89]\d{8}$
amount	number	Monto comercial para validacion cruzada
notification_email	string	Email de sucursal para fallo o confirmacion
source_xml_hash	string	SHA-256 del XML para idempotencia
canton	string	Opcional si n8n ya conoce el canton; si no, aplica fallback del servicio

Reglas de negocio

• product_code debe pertenecer al universo RECCLARO*.
• subscriber_id debe ser un numero movil Claro valido en formato internacional.
• source_xml_hash evita procesar dos veces la misma factura.
• Si el producto no tiene mapping, la transaccion se rechaza y se notifica por correo.
• quantity no se recibe desde n8n; internamente se fija en 1.

Respuesta exitosa

{
  "success": true,
  "transaction_id": "uuid",
  "source": "n8n-webhook",
  "invoice_number": "001-001-000045678",
  "status": "success",
  "claro_id_recarga": "447435057"
}

Código HTTP: 201 Created.

Respuesta con rechazo

{
  "success": false,
  "transaction_id": "uuid",
  "source": "n8n-webhook",
  "invoice_number": "001-001-000045678",
  "status": "rejected",
  "error": "Codigo de producto RECCLARO99 no tiene mapeo a Claro"
}

Respuestas esperadas

• 201 Created: recarga automatica procesada (success, failed o unavailable segun resultado del SPR)
• 400 Bad Request: payload invalido
• 401 Unauthorized: service key ausente o invalida
• 409 Conflict: factura ya procesada por source_xml_hash
• 502 Bad Gateway: SOAP Fault del SPR o error de transporte
• 504 Gateway Timeout: Claro no respondio dentro del timeout de 30 s

Mapping de productos MBA3 a Claro

El webhook no recibe offer_id directo. Recibe el SKU facturado en MBA3 y lo traduce al codigo real de Claro.

product_code MBA3	offer_id Claro	external_operation	Descripcion
RECCLARO3	31	RECARGA_PINES	Pin 3
RECCLARO5	30	RECARGA_PINES	Pin 5
RECCLARO10	151	RECARGA_PINES	Pin 10
RECCLARODATOS3	150	RECARGA_DATOS	Datos 3
RECCLARODATOS5	150	RECARGA_DATOS	Datos 5

La tabla es configurable y se considera provisional hasta que Claro confirme el mapping final de ofertas.

Flujo de traduccion del webhook

1. n8n envia un product_code facturado por MBA3.
2. ms-recargas resuelve offer_id, tipo de operacion y monto esperado.
3. Se inserta la transaccion con source = n8n-webhook y estado inicial pending.
4. Se construye el XML MOVILPOS y se envia al SPR.
5. Si el mapping no existe, la transaccion queda rejected y se encola recharge-invalid-invoice.
6. Si el SPR devuelve error o timeout, queda traza completa y se dispara la notificacion correspondiente.

Flujo automatico resumido

flowchart TD
  A[MBA3 genera factura] --> B[Correo con XML y PDF]
  B --> C[n8n IMAP Trigger]
  C --> D{Producto RECCLARO* y telefono valido}
  D -- No --> E[Registrar ignored o rejected]
  D -- Si --> F[POST webhook con x-service-key]
  F --> G{source_xml_hash ya existe}
  G -- Si --> H[409 Conflict]
  G -- No --> I[Resolver product_code a offer_id]
  I --> J[Insert pending]
  J --> K[Enviar XML MOVILPOS al SPR]
  K --> L{Respuesta Claro}
  L -- SUCCESS --> M[Update success + email + SMS]
  L -- ERROR --> N[Update failed + email]
  L -- Fault o timeout --> O[Update unavailable + alerta]

Flujo manual resumido

flowchart TD
  A[Operador abre tab Recargar] --> B{Busca factura o digita numero}
  B --> C[Selecciona producto]
  C --> D[Solicita OTP de accion]
  D --> E[Valida action token]
  E --> F[POST /recargas/recharge]
  F --> G{Guards y limites}
  G -- OK --> H[Insert pending]
  H --> I[Enviar XML al SPR]
  I --> J{Resultado}
  J -- SUCCESS --> K[Update success + notificacion]
  J -- ERROR --> L[Update failed + notificacion]
  J -- Timeout o fault --> M[Update unavailable + notificacion]

Integracion hacia Claro

El envio real usa XML umsprot contra el endpoint CLARO_SPR_URL con timeout de 30 segundos.

<umsprot version="1">
  <exec_req function="sre_movilposd_76186">
    <data name="EXTERNALOPERATION">RECARGA_DATOS</data>
    <data name="EXTERNALTRANSACTIONID">17451234567890123</data>
    <data name="OFFERID">150</data>
    <data name="SUBSCRIBERID">593986686257</data>
    <data name="QUANTITY">1</data>
  </exec_req>
</umsprot>

La respuesta se considera exitosa solo cuando STATUS = SUCCESS, ID_CODIGO = 0 y no existe SOAP Fault.

Persistencia de la transaccion

Cada recarga se registra en recharge_transactions con estos datos operativos:

• external_transaction_id
• external_operation
• source
• subscriber_id
• offer_id
• quantity
• status
• invoice_number e invoice_code cuando aplica
• notification_email y source_xml_hash en flujo automatico
• product_code, rejection_reason, source_payload, retry_count
• claro_id_recarga, claro_id_codigo, claro_system_message, claro_result_code, claro_diagnostic
• requested_by_user_id y requested_by_username
• raw_request_xml y raw_response_xml
• timestamps de creacion y actualizacion

Estados y resultados

Estado	Origen
pending	Insert inicial antes del llamado al SPR
success	Recarga confirmada por Claro (STATUS=SUCCESS y result=0)
failed	Error de negocio devuelto por Claro (sin saldo, número no válido, credenciales, STATUS=ERROR)
unavailable	SPR no disponible (SOAP Fault, timeout, ECONNREFUSED, VPN caída). Reintentable; incrementa retry_count
rejected	Webhook rechazó antes de llamar al SPR (mapping ausente, DTO inválido, duplicado). rejection_reason explica el motivo
ignored	n8n descartó el correo (no era recarga o no contenía número). Se persiste como bitácora auditable
error (legacy)	Estado generico heredado del flujo manual. Nuevos flujos usan failed o unavailable

Notificaciones por email

ms-recargas publica jobs en BullMQ hacia la cola recharge-notifications. ms-worker consume y envia via SMTP.

Job	Disparador	Destinatarios
recharge-success	status=success	notification_email, operador manual y operaciones
recharge-failed	status=failed	notification_email, operador manual y operaciones
recharge-unavailable	status=unavailable	notification_email, operador manual y operaciones
recharge-invalid-invoice	status=rejected	notification_email y operaciones

Los destinatarios se deduplican antes de encolar el job.

Desarrollo contra Claro real

En desarrollo, el modo por defecto es mock. Para probar contra el SPR real se debe abrir el tunel SSH documentado en scripts/claro-tunnel.sh y desactivar CLARO_MOCK_MODE.

Pasos minimos:

1. Configurar el alias SSH o las variables CLARO_TUNNEL_*.
2. Ejecutar bash scripts/claro-tunnel.sh.
3. Configurar CLARO_SPR_URL=http://host.docker.internal:50004/sprXslt/sprXslt.
4. Dejar CLARO_MOCK_MODE=false.
5. Reiniciar ms-recargas para tomar la nueva configuracion.

Cuando terminen las pruebas, se debe cerrar el tunel y volver el servicio a modo mock.

Validaciones clave

• El numero debe ser Claro valido antes de consumir saldo.
• external_transaction_id debe ser unico.
• El webhook debe validar duplicados por hash del XML.
• El producto debe existir en la tabla de mapping.
• Si el SPR devuelve STATUS=ERROR o un SOAP Fault, la transaccion no debe marcarse como exitosa.
• Si faultCode=350, la IP saliente no esta autorizada por Claro.

Runbook operativo minimo

1. Verifica GET /up antes de probar el flujo.
2. Si estas en desarrollo sin VPN, activa CLARO_MOCK_MODE=true.
3. Si el webhook responde rejected, revisa mapping, telefono, DTO y hash.
4. Si hay 502 o 504, inspecciona raw_response_xml, claro_diagnostic y la conectividad hacia el SPR.
5. Si el problema solo ocurre fuera de produccion, confirma que el tunel o la VPN sigan activos.

Relacion con otras guias

• Usa Consulta de recarga para reconciliar transacciones.
• Usa Consulta de inventario para stock antes de vender.
• Revisa Codigos de error para diagnostico por capa.