Recargas Claro

Recargas Claro

El modulo de recargas Claro en NoviSuite permite ejecutar recargas de pines y datos contra el SPR de Claro Ecuador a traves del microservicio ms-recargas. Este microservicio actua como mediador entre el dashboard, el ERP MBA3 y el protocolo MOVILPOS v7.0.

Que permite este modulo

• Ejecutar recargas de pines y datos desde el dashboard.
• Consultar el estado de una recarga procesada.
• Verificar el inventario disponible en tiempo real.
• Listar y filtrar transacciones registradas.
• Operar con datos extraidos automaticamente de facturas MBA3.

Permisos requeridos

El acceso a las funciones del modulo depende de los permisos asignados al usuario:

Permiso	Acciones habilitadas
create_recargas	Ejecutar recargas.
view_recargas	Consultar transacciones, estado de recarga e inventario.

Si un usuario no tiene el permiso correspondiente, recibira un rechazo 403 Forbidden.

Resumen de endpoints

Todos los endpoints requieren autenticacion JWT (Authorization: Bearer <token>) y usan application/json.

Metodo	Ruta	Permiso	Descripcion
POST	/api/v1/recargas/recharge	create_recargas	Ejecuta una recarga.
GET	/api/v1/recargas/transactions	view_recargas	Lista transacciones paginada.
GET	/api/v1/recargas/transactions/:id	view_recargas	Detalle de una transaccion por UUID.
POST	/api/v1/recargas/query-recharge	view_recargas	Consulta estado real en Claro por TX externa.
GET	/api/v1/recargas/inventory	view_recargas	Consulta stock disponible en el SPR.

Flujo con factura MBA3

El flujo principal conecta la factura generada en MBA3 con la recarga en Claro:

1. El operador genera una factura en MBA3.
2. Desde el dashboard busca la factura por numero o codigo.
3. El sistema consulta la factura en 4D y extrae el telefono del cliente (CLNT_Ficha_Principal.TELEFONO).
4. Si el numero cumple el formato Claro Ecuador (593 + 8 o 9 + 8 digitos), se auto-rellena en el formulario.
5. El operador selecciona el producto del inventario y la cantidad.
6. Confirma la operacion y el sistema ejecuta la recarga.

Note

El flujo manual (sin factura) tambien esta soportado: el operador escribe el subscriber_id directamente en el formulario.

Ejecutar una recarga

Request

POST /api/v1/recargas/recharge

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

Campos obligatorios

Campo	Tipo	Regla
subscriber_id	string	12 digitos, formato ^593[89]\d{8}$.
offer_id	string	Identificador del producto Claro. Ej: 150 (datos), 30/31/151 (pines).
quantity	number	Entero mayor o igual a 1.
external_operation	enum	RECARGA_DATOS o RECARGA_PINES.
canton	string	Codigo INEC de 4 digitos (ej: 0101).

Respuesta exitosa

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

Respuesta con rechazo logico

Cuando Claro rechaza la transaccion, el HTTP status es 200 pero success es false:

{
  "success": false,
  "transaction_id": "f2c0a4d8-...-uuid",
  "external_transaction_id": "17451234567890123",
  "status": "error",
  "error": "El número no pertenece a Claro o no está activo",
  "message": "ERROR"
}

Consultar transacciones

Lista paginada

GET /api/v1/recargas/transactions

Parametro	Tipo	Default	Descripcion
page	number	1	Pagina actual.
per_page	number	20	Registros por pagina.
subscriber_id	string	—	Filtra por numero exacto.
status	enum	—	pending, success o error.

Respuesta:

{
  "data": [],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Detalle por UUID

GET /api/v1/recargas/transactions/:id

Devuelve el objeto completo de la transaccion, incluyendo raw_request_xml y raw_response_xml para auditoria.

Consultar estado real en Claro

Util cuando una recarga quedo en pending o se sospecha desincronizacion.

POST /api/v1/recargas/query-recharge

{
  "external_transaction_id": "17451234567890123",
  "offer_id": "150"
}

Respuesta:

{
  "success": true,
  "external_transaction_id": "17451234567890123",
  "status": "SUCCESS",
  "message": "Transacción exitosa",
  "result_code": 0
}

Consultar inventario

GET /api/v1/recargas/inventory

Respuesta:

{
  "success": true,
  "products": [
    { "name": "Pines PVIR MOVIL POS", "offer_id": "30", "status": "DISPONIBLE", "balance": "985750" },
    { "name": "Pines 100", "offer_id": "151", "status": "DISPONIBLE", "balance": "999345.5" }
  ],
  "raw_message": ";Pines PVIR MOVIL POS - 985750;Pines 100 - 999345.5"
}

Estados de una transaccion

Cada recarga pasa por los siguientes estados:

Estado	Significado
pending	La transaccion fue registrada y esta en proceso.
success	Claro confirmo la recarga exitosamente.
error	La recarga fue rechazada o fallo por timeout, SOAP Fault u otro error.

Una transaccion en error puede pasar a success si al usar query-recharge se confirma que Claro si la proceso (reconciliacion).

Validaciones y puntos de rechazo

El flujo tiene multiples puntos de validacion. Si cualquiera falla, se muestra un mensaje especifico:

Gate	Capa	Mensaje al usuario
JWT invalido o expirado	AuthGuard	Sesion expirada, vuelve a iniciar sesion.
Falta permiso create_recargas	PermissionsGuard	No tienes permiso para ejecutar recargas.
Factura no existe en 4D	ms-mba	Factura no encontrada en MBA3.
Cliente sin telefono	ms-mba	La factura no tiene numero telefonico asociado.
Telefono no Claro / formato invalido	Frontend	El numero no es Claro Ecuador valido.
Producto no disponible	Frontend	Producto no disponible en inventario.
DTO invalido	ValidationPipe	Datos del formulario invalidos.
EXTERNALTRANSACTIONID duplicado	DB / Claro	Imposible realizar la recarga. Intente nuevamente.
SOAP Fault del SPR	ClaroClientService	Error de comunicacion con Claro.
Timeout mayor a 30 s	ClaroClientService	Claro no respondio a tiempo.
STATUS=ERROR de Claro	RecargasService	Se muestra el mensaje crudo de Claro.
Excepcion inesperada	AllExceptionsFilter	Error inesperado, contacta soporte.

Codigos HTTP de respuesta

Codigo	Significado
200	Operacion procesada (verificar success en el body).
400	Datos del request invalidos.
401	JWT invalido o expirado.
403	Permiso insuficiente.
502	El SPR respondio con SOAP Fault o status HTTP no exitoso.
504	El SPR no respondio en 30 segundos.

Datos de la transaccion registrada

Cada recarga se persiste en base de datos con los siguientes campos relevantes:

Campo	Descripcion
id	UUID local de la transaccion.
external_transaction_id	Identificador unico generado por el servidor (usado ante Claro).
external_operation	RECARGA_DATOS o RECARGA_PINES.
subscriber_id	Numero del suscriptor (12 digitos).
offer_id	Producto Claro.
quantity	Cantidad solicitada.
status	pending, success o error.
claro_id_recarga	ID secuencial de Claro al confirmar.
claro_id_codigo	0 = exito, distinto de 0 = error.
claro_system_message	Mensaje legible devuelto por Claro.
requested_by_user_id	UUID del usuario que ejecuto la recarga.
requested_by_username	Email del solicitante.
raw_request_xml	XML enviado al SPR (auditoria).
raw_response_xml	Respuesta cruda del SPR (auditoria).
created_at	Fecha y hora de creacion.

Modo de desarrollo

Para trabajar sin conectividad VPN al SPR de Claro, se puede activar el modo mock con la variable CLARO_MOCK_MODE=true. En este modo, todas las llamadas se redirigen a un servicio simulado que retorna respuestas predefinidas.

Documentacion relacionada

• Vision general del modulo Claro para el panorama funcional del protocolo MOVILPOS v7.0.
• Servicio de recargas para el contrato XML directo del SPR.
• Consulta de recarga para verificar transacciones a nivel de protocolo.
• Consulta de inventario para la consulta de stock a nivel de protocolo.
• Codigos de error para el catalogo completo de errores del SPR.