Consulta de recarga

Esta guia cubre dos niveles de consulta:

consulta remota contra Claro para reconciliar una transaccion
consulta local de la bitacora recharge_transactions

Consulta remota en Claro

`POST /api/v1/recargas/query-recharge`

Permite consultar el estado real de una transaccion usando la funcion sre_consulta_recarga del protocolo MOVILPOS v7.0.

Autenticacion: Bearer JWT con permiso view_recargas

Body

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

Respuesta exitosa

{
  "success": true,
  "external_transaction_id": "17451234567890123",
  "status": "SUCCESS",
  "message": "Transaccion exitosa",
  "result_code": 0
}

Cuando usarla

una recarga quedo en pending
hubo timeout al llamar al SPR
se necesita confirmar si Claro proceso o no la transaccion
se sospecha desincronizacion entre el estado local y el estado real

Llamado XML subyacente

<umsprot version="1">
  <exec_req function="sre_consulta_recarga">
    <data name="USERID">PRUEBAREC</data>
    <data name="PASSWORD">5566</data>
    <data name="COMPANYID">PRUEBACOMPANI</data>
    <data name="EXTERNALTRANSACTIONID">17451234567890123</data>
    <data name="OFFERID">150</data>
  </exec_req>
</umsprot>

Respuesta tipica del SPR

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="MENSAJE">Transaccion exitosa</data>
    <data name="ID_RECARGA">447435057</data>
    <data name="ID_CODIGO">0</data>
    <data name="STATUS">SUCCESS</data>
  </exec_rsp>
</umsprot>

Consulta local de transacciones

`GET /api/v1/recargas/transactions`

Lista paginada de la base local.

Autenticacion: Bearer JWT con permiso view_recargas

Query params

Param	Tipo	Default
`page`	`number`	`1`
`per_page`	`number`	`20`
`subscriber_id`	`string`	sin filtro
`status`	`pending`, `success`, `failed`, `unavailable`, `rejected`, `ignored`, `error`	sin filtro
`source`	`dashboard`, `n8n-webhook`, `n8n-ignored`	sin filtro

Respuesta

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

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

Devuelve el detalle completo de una transaccion, incluyendo:

XML enviado a Claro
respuesta cruda del SPR
identificadores de factura y usuario
diagnosticos y mensajes tecnicos
payload original del webhook cuando aplica
datos de notificacion y conteo de reintentos

Campos clave de auditoria

Campo	Uso
`external_transaction_id`	llave de reconciliacion con Claro
`source`	origen de la solicitud
`claro_id_recarga`	identificador asignado por Claro
`claro_id_codigo`	`0` exito, distinto de `0` error
`claro_system_message`	mensaje legible del SPR
`claro_diagnostic`	diagnostico tecnico de fault o transporte
`source_xml_hash`	huella de idempotencia del XML
`retry_count`	numero de veces que la transaccion paso por `unavailable`
`raw_request_xml`	request exacto enviado
`raw_response_xml`	respuesta exacta recibida

Reconciliacion de estados

La consulta remota no crea una nueva transaccion. Se usa para reconciliar una ya existente.

Escenarios comunes:

pending local y SUCCESS remoto: actualizar a success.
failed local y SUCCESS remoto: reconciliar a success si el negocio confirma el cobro.
unavailable local y SUCCESS remoto: reconciliar a success por exito tardio.
SUCCESS local y ERROR remoto: tratarlo como incidente operacional; no degradar automaticamente sin analisis.

Maquina de estados resumida

stateDiagram-v2
  [*] --> pending
  pending --> success
  pending --> failed
  pending --> unavailable
  unavailable --> pending
  unavailable --> success
  failed --> success
  success --> [*]
  failed --> [*]
  unavailable --> [*]

Escenarios de error frecuentes

Transaccion no encontrada

Claro no reconoce la transaccion o aun no la tiene confirmada:

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">Transaccion no encontrada</data>
    <data name="ID_CODIGO">1</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Producto incorrecto para la consulta

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">Error al Obtener Parametros
    Producto, intente nuevamente por favor.</data>
    <data name="ID_CODIGO">1</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Credenciales invalidas

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="MENSAJE">La clave ingresada es incorrecta. R.11</data>
    <data name="ID_CODIGO">1</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

IP no autorizada en el SPR

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <env:Fault>
      <faultcode>350</faultcode>
      <faultstring>El id_requerimiento es nulo debido a que el xml
      recibido en el body del request no corresponde a ningun formato
      configurado para la ip del llamante: 10.35.2.31</faultstring>
    </env:Fault>
  </env:Body>
</env:Envelope>

Este caso normalmente deja la transaccion en unavailable y requiere whitelist de IP con Claro.

Recomendaciones

Consulta primero la bitacora local y usa query-recharge solo cuando necesites reconciliar con Claro.
Guarda siempre offer_id junto al external_transaction_id; ambos son necesarios para consultar bien.
Si un timeout deja duda operativa, no marques exito local sin antes reconciliar.
Usa transactions/:id para revisar raw_request_xml, raw_response_xml y source_payload antes de reprocesar.
Revisa Codigos de error para distinguir fallos del modulo y del SPR.