Consulta de inventario

Consulta de inventario

El dashboard no consulta inventario desde una tabla local. Lo obtiene en linea a traves de ms-recargas, que a su vez llama la funcion sre_consulta_inventario del protocolo MOVILPOS v7.0.

Endpoint expuesto por ms-recargas

GET /api/v1/recargas/inventory

Autenticacion: Bearer JWT con permiso view_recargas

Respuesta esperada

{
  "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"
}

Este endpoint se consume con Bearer JWT y permiso view_recargas.

Llamado XML subyacente

<umsprot version="1">
  <exec_req function="sre_consulta_inventario">
    <data name="EXTERNALOPERATION">CONSULTA_INVENTARIO</data>
    <data name="COMPANYID">PRUEBACOMPANI</data>
    <data name="USERID">PRUEBAREC</data>
    <data name="PASSWORD">5566</data>
    <data name="TERMINAL">10.35.2.78</data>
  </exec_req>
</umsprot>

Respuesta cruda de Claro

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">;Pines PVIR MOVIL POS -
    985750;Pines 100 - 999345.5</data>
    <data name="STATUS">SUCCESS</data>
  </exec_rsp>
</umsprot>

Formatos de SYSTEMMESSAGE soportados

El parser de ms-recargas debe aceptar dos variantes:

Formato	Ejemplo	Uso
Produccion real	;Pines PVIR MOVIL POS - 985750;Pines 100 - 999345.5	Respuesta esperada del SPR
Mock legacy	Pines;30;DISPONIBLE;985750;...	Respuesta de desarrollo o simulacion

En ambos casos el endpoint debe devolver un arreglo products uniforme para el frontend.

Regla de parseo

• En el formato real, el parser separa por ; y luego intenta resolver name y balance por el delimitador -.
• En el formato mock legacy, el parser interpreta grupos posicionales name, offer_id, status, balance.
• raw_message siempre se conserva para auditoria y debugging.

Campos relevantes

Campo	Ejemplo	Descripcion
name	Pines PVIR MOVIL POS	Nombre del producto reportado por Claro
offer_id	30	Se completa cuando el parser puede resolverlo
status	DISPONIBLE	Estado legible para el dashboard
balance	985750	Saldo o stock reportado
raw_message	;Pines PVIR...	Valor original devuelto por el SPR

Errores operativos comunes

Escenario	Sintoma	Lectura recomendada
Credenciales invalidas	STATUS=ERROR y mensaje de usuario o clave	Revisar variables CLARO_USERID, CLARO_PASSWORD, CLARO_TOKEN
Terminal no asociado	SYSTEMMESSAGE indica terminal no asignado	Revisar CLARO_TERMINAL
IP no validada	SOAP Fault 350	Solicitar whitelist a Claro
Sin conectividad	timeout o ECONNREFUSED	Revisar VPN, tunel SSH o mock mode

Escenarios de error

IP no validada en 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>

Credenciales o terminal invalidos

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">El usuario ingresado es incorrecto o
    se encuentra inactivo.</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Terminal no asociado al usuario

<umsprot version="1">
  <exec_rsp result="OK" diagnostic="Conexion Exitosa">
    <data name="SYSTEMMESSAGE">El terminal no se encuentra
    asignado al usuario.</data>
    <data name="STATUS">ERROR</data>
  </exec_rsp>
</umsprot>

Buenas practicas

1. Consultar inventario antes de ofrecer productos en el dashboard.
2. No inferir disponibilidad solo por configuracion local; el dato valido es el del SPR.
3. Mantener visible raw_message cuando el parser no pueda normalizar completamente la respuesta.
4. Si el ambiente local usa Claro real, verificar que CLARO_MOCK_MODE=false y que el tunel al puerto 50004 siga activo.

Recomendaciones

1. Consulta inventario antes de habilitar productos en el dashboard.
2. Conserva raw_message para debugging cuando el parser no reconozca el formato.
3. Si usas mock mode, valida que el frontend no dependa del formato crudo sino del arreglo normalizado.
4. Revisa Codigos de error cuando el inventario falle por red, IP o credenciales.