saldoComercio

El método saldoComercio permite consultar el saldo disponible de un comercio previamente registrado en la plataforma de Operaciones en Línea (OEL), mediante el servicio SoapAliados.

La operación recibe las credenciales del aliado y el identificador del comercio cuya información financiera se desea consultar.

Como resultado, devuelve información de identificación del aliado y del establecimiento, el saldo disponible reportado por el servicio y los códigos funcionales de respuesta.

Este método es exclusivamente de consulta. Su contrato no contempla parámetros para modificar saldos, realizar transferencias, ejecutar retiros ni efectuar movimientos financieros.

Información del servicio

Endpoint de producción

Endpoint de desarrollo

La disponibilidad del ambiente de pruebas y la habilitación de las credenciales deben verificarse con OEL.

Autenticación

La operación utiliza dos niveles de identificación:

1. Cabecera SOAP OpHeader.

2. Credenciales del aliado dentro del objeto request.

Cabecera SOAP — OpHeader

<soap:Header>
  <OpHeader xmlns="https://servidorseguro.operacionesenlinea.com/">
    <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
    <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
  </OpHeader>

Credenciales del aliado

Parámetros de solicitud (Request)

El método recibe un objeto request de tipo cSaldoComercioReq, compuesto por tres parámetros.

Los parámetros se presentan en el orden exacto establecido por el WSDL.

Consideraciones de los parámetros

claveAliado

Identifica al aliado que realiza la consulta.

Debe corresponder a las credenciales autorizadas para el ambiente utilizado.

contrasena

Contraseña del aliado.

Debe mantenerse protegida y no incluirse en registros de aplicación, URLs o respuestas públicas.

comercioId

Identifica al establecimiento cuyo saldo disponible se desea consultar.

El valor puede obtenerse del resultado de afiliacionComercio o de los registros administrativos del sistema integrador.

Restricciones funcionales no especificadas

• El aliado puede consultar únicamente saldos de sus comercios afiliados.

• No pueden consultarse saldos de comercios suspendidos o inactivos.

Ejemplo XML Request — SOAP 1.1

Petición HTTP

Cuerpo SOAP

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Header>
    <OpHeader xmlns="https://servidorseguro.operacionesenlinea.com/">
      <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
      <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
    </OpHeader>
  </soap:Header>

  <soap:Body>
    <saldoComercio
        xmlns="https://servidorseguro.operacionesenlinea.com/">
      <request>
        <claveAliado>ALIADO_DEMO</claveAliado>
        <contrasena>CLAVE_ALIADO</contrasena>
        <comercioId>12345</comercioId>
      </request>
    </saldoComercio>

Todos los valores son ficticios o simbólicos.

Para ejecutar la solicitud deben reemplazarse las credenciales y el identificador del comercio por valores válidos del ambiente correspondiente.

Parámetros de respuesta (Response)

El servicio devuelve el elemento saldoComercioResponse, que puede contener saldoComercioResult, de tipo cSaldoComercioResp.

El WSDL define 8 parámetros, organizados a continuación por categorías funcionales.

1. Identificación del aliado y comercio

Estos campos permiten identificar al aliado y al establecimiento relacionados con la consulta.

2. Información financiera

Campo SaldoDisponible

SaldoDisponible es el dato principal de la respuesta y corresponde al saldo disponible del establecimiento.

El WSDL define este campo de la siguiente manera:

Consideraciones técnicas:

• El nombre comienza con S mayúscula.

• El tipo XML es decimal.

• El elemento es requerido estructuralmente.

• El esquema establece el uso de dos decimales.

Importante: el campo debe interpretarse como el saldo disponible reportado por OEL. No debe presentarse automáticamente como saldo bancario liquidado, saldo retirable o importe garantizado para transferencias.

3. Resultado funcional

Estos campos permiten interpretar el resultado comunicado por el servicio.

Ejemplo XML Response — SOAP 1.1

El siguiente ejemplo contiene los ocho parámetros de cSaldoComercioResp, respetando el orden establecido por el WSDL.

Todos los valores son ficticios.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>
    <saldoComercioResponse
        xmlns="https://servidorseguro.operacionesenlinea.com/">

Notas sobre el ejemplo

El valor 1500.75 es exclusivamente ilustrativo y no representa un saldo real.

Los valores 0 en codigoRespuesta y ccErrorCode no establecen que dichos códigos representen necesariamente una consulta satisfactoria.

El ejemplo incluye los ocho campos para mostrar la estructura completa; los elementos opcionales pueden estar ausentes en respuestas reales.

Interpretación de la respuesta

La aplicación integradora debe evaluar los códigos funcionales antes de utilizar el saldo devuelto.

Resultado de la consulta

Los campos codigoRespuesta, ccErrorCode y mensajeRespuesta permiten conocer el resultado comunicado por el servicio.

Una respuesta HTTP 200 OK no debe considerarse prueba suficiente de que la consulta fue satisfactoria.

Correspondencia del comercio

Se recomienda comprobar que el comercioId devuelto corresponda al identificador solicitado.

Saldo disponible

Cuando la operación haya concluido satisfactoriamente, el valor de SaldoDisponible podrá utilizarse como el saldo disponible reportado por OEL para el comercio consultado.

Precisión decimal

Se recomienda utilizar dos decimales exactos para procesar el valor, evitando representaciones de punto flotante que puedan introducir diferencias de precisión.

Respuestas incompletas

El integrador debe validar la existencia del objeto de respuesta antes de utilizar sus propiedades y contemplar errores SOAP Fault.

Flujo operativo recomendado

Paso 1. Identificar al aliado

Obtener las credenciales autorizadas para consumir SoapAliados.

Paso 2. Identificar al comercio

Determinar el comercioId del establecimiento cuyo saldo se desea consultar.

Paso 3. Construir la solicitud SOAP

Preparar la cabecera OpHeader y el objeto cSaldoComercioReq.

Paso 4. Enviar la solicitud

Invocar saldoComercio mediante HTTPS.

Paso 5. Procesar la respuesta

Deserializar saldoComercioResult y recuperar los campos funcionales.

Paso 6. Validar el resultado

Interpretar los códigos de respuesta conforme al catálogo confirmado por OEL.

Paso 7. Verificar el comercio

Comprobar la correspondencia del identificador recibido.

Paso 8. Obtener el saldo

Cuando la consulta sea satisfactoria, utilizar SaldoDisponible conforme al propósito autorizado.

Paso 9. Registrar la consulta

Conservar los datos de trazabilidad necesarios, evitando almacenar credenciales.

Este flujo es una recomendación de integración y no implica que OEL ejecute validaciones adicionales no descritas en el contrato.

Casos de uso

Consulta de saldo desde un panel administrativo

Un sistema autorizado puede presentar el saldo disponible reportado por OEL para un comercio.

Se recomienda mostrar claramente la fecha y hora en que el sistema integrador realizó la consulta, sin confundirlas con una fecha de actualización interna de OEL.

Verificación previa a una transferencia

El integrador puede consultar el saldo antes de solicitar una operación mediante trasferenciaSaldo.

Sin embargo, esta consulta no reserva fondos ni garantiza que una transferencia posterior será aceptada.

Seguimiento de saldos

Un sistema administrativo puede realizar consultas periódicas para observar cambios en el saldo reportado.

El contrato no devuelve un historial de movimientos ni explica las causas de cada variación.

Conciliación administrativa

El saldo puede utilizarse como dato de referencia durante procesos de conciliación con los registros financieros disponibles.

No sustituye un estado de cuenta ni un reporte detallado de movimientos.

Validación de integración

Se recomienda comenzar las pruebas con operaciones de consulta, como detalleComercio o saldoComercio, para verificar autenticación y serialización antes de ejecutar operaciones que modifiquen información.

Códigos de respuesta y errores

La operación contempla tres campos comunes de resultado:

Escenarios de prueba recomendados

Estos escenarios son recomendaciones de prueba y no comportamientos confirmados por la documentación.

Recomendaciones de seguridad

Control de acceso

Permitir la consulta únicamente a sistemas y usuarios autorizados para visualizar información financiera del comercio.

Protección de credenciales

Mantener OpKey1, OpKey2, claveAliado y contrasena en mecanismos seguros de almacenamiento de secretos.

Validación del comercio

Comprobar que el identificador consultado corresponda al establecimiento autorizado para el usuario o proceso solicitante.

Minimización de información

Evitar exponer saldos financieros en interfaces públicas o respuestas accesibles sin autorización.

Trazabilidad

Registrar el comercio consultado, la fecha y hora de la solicitud, el sistema solicitante y los códigos funcionales devueltos.

Protección de registros

No incluir contraseñas ni llaves de autenticación en los logs.

Manejo de errores

Evitar que los mensajes de error expongan credenciales o información financiera a usuarios no autorizados.

Control de consultas repetidas

Aplicar límites razonables de frecuencia desde el sistema integrador, sujetos a las condiciones operativas confirmadas por OEL.

Estas medidas son recomendaciones de implementación para OEL y sus integradores, no funcionalidades adicionales garantizadas por el WSDL.

Relación con otros métodos

Relación con trasferenciaSaldo

saldoComercio y trasferenciaSaldo son operaciones distintas:

• saldoComercio consulta un importe disponible.

• trasferenciaSaldo solicita un movimiento de saldo entre comercios.

El flujo recomendado para un sistema que necesite realizar transferencias es consultar previamente el saldo del comercio de origen, validar las condiciones de negocio y posteriormente ejecutar la transferencia autorizada.

Sin embargo, la consulta previa no garantiza que los fondos permanezcan disponibles ni que la transferencia sea aceptada.

Las recomendaciones de seguridad, conciliación, validación y manejo de errores se presentan como orientación para la integración y no como comportamientos confirmados del servicio.