OpEstadoCuenta

El método OpEstadoCuenta permite solicitar información de estado de cuenta asociada a un comercio registrado en el Gateway de Pagos de OEL.

La consulta utiliza las credenciales del comercio, un parámetro denominado periodo y, opcionalmente, información del subcomercio y de la versión de integración.

A diferencia de OpTransacciones y OpCortesDiarios, este método no recibe fechas de inicio y fin. El período de consulta se especifica mediante un valor numérico entero.

La respuesta contiene una estructura XML dinámica, formada por un esquema XML y contenido adicional, en lugar de un objeto con campos previamente enumerados en el WSDL.

Información del servicio

Se recomienda utilizar TLS 1.2 o superior, conforme a los requisitos de seguridad aplicables a la integración.

Autenticación

La operación utiliza la cabecera SOAP OpHeader, mediante las credenciales asignadas al comercio por OEL.

Adicionalmente, el cuerpo de la solicitud contempla comercioId y contrasena, utilizados para identificar al comercio.

Las credenciales deben mantenerse protegidas y no incorporarse en repositorios públicos, registros de diagnóstico ni ejemplos de documentación.

Parámetros de solicitud (Request)

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

Consideraciones sobre los parámetros

comercioId

Identifica al comercio que solicita la información. Debe utilizarse el identificador asignado por OEL.

contrasena

Corresponde a la contraseña de autenticación del comercio. Debe mantenerse protegida y transmitirse exclusivamente mediante conexiones seguras.

periodo

Es un parámetro de tipo entero (int) utilizado para indicar el período de consulta. En donde cero (0) se utiliza para referirse al mes actual, menos uno (-1) para referirse al mes anterior, menos 2 (-2) para referirse a dos mese atras y así sucesivamente.

subcomercio

Permite proporcionar un identificador de subcomercio.

version

Identifica la versión del SDK o integración utilizada para realizar la solicitud, cuando corresponda.

Ejemplo XML Request — SOAP 1.1

El siguiente ejemplo muestra la estructura de una solicitud de estado de cuenta utilizando valores ficticios y simbólicos.

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

  <soap:Header>
    <OpHeader>
      <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
      <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
    </OpHeader>
  </soap:Header>

  <soap:Body>
    <OpEstadoCuenta>
      <request>
        <comercioId>12345</comercioId>
        <contrasena>CLAVE_COMERCIO</contrasena>
        <periodo>-1</periodo>
        <subcomercio>SUBCOMERCIO_ID</subcomercio>
        <version>VERSION_SDK</version>
      </request>
    </OpEstadoCuenta>

Todos los valores son ilustrativos.

En particular, periodo=-1 se utiliza únicamente para mostrar la representación de un entero en XM, el cual es un valor admitido por el servicio y representa el período correspondiente al ultimo mes de operación.

Para enviar la solicitud mediante SOAP 1.1, utiliza las siguientes cabeceras HTTP:

Estructura de respuesta (Response)

El servicio devuelve un mensaje SOAP que contiene el elemento OpEstadoCuentaResponse.

Dentro de este elemento se encuentra OpEstadoCuentaResult.

A diferencia de otros métodos del Gateway, OpEstadoCuentaResult no está definido mediante un tipo de respuesta con propiedades de negocio enumeradas.

El WSDL establece una estructura compuesta por:

1. Un elemento de esquema XML (s:schema).

2. Un elemento adicional admitido mediante s:any.

La definición estructural es equivalente a:

Esta definición permite que la respuesta incorpore un esquema XML y contenido cuya estructura concreta se describe dinámicamente.

Elementos de respuesta confirmados

El WSDL no define los nombres, tipos ni la cantidad de columnas financieras que podría contener el resultado.

Ejemplo XML Response — Estructura ilustrativa

El siguiente ejemplo muestra una respuesta ficticia para ilustrar cómo puede presentarse un esquema XML acompañado de contenido.

Los nombres EstadoCuentaEjemplo y DatoIlustrativo son inventados exclusivamente para explicar la estructura. No representan campos oficiales de OEL ni una respuesta capturada del servicio.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns="https://servidorseguro.operacionesenlinea.com/">

  <soap:Body>
    <OpEstadoCuentaResponse>
      <OpEstadoCuentaResult>

Este ejemplo demuestra la organización estructural definida por el WSDL, pero no debe utilizarse como contrato de datos real.

La implementación del servicio podría devolver un formato diferente para el contenido dinámico, como un documento XML estructurado con sus propias tablas, filas y columnas.

Para documentar esas columnas con precisión será necesario contar con una respuesta real del servicio, utilizando datos de prueba.

Interpretación de la respuesta

Esquema XML

El elemento s:schema proporciona información sobre la estructura de los datos contenidos en el resultado.

El integrador debe utilizar esta información para comprender los elementos y tipos de datos devueltos.

Contenido dinámico

El elemento definido mediante s:any permite incluir contenido XML cuya estructura no está enumerada directamente en el WSDL.

Por lo tanto, el integrador no debe asumir que siempre existirán columnas específicas, como importes, comisiones, fechas de liquidación o saldos, hasta confirmar que forman parte de las respuestas del servicio.

Resultado de la consulta

El contrato no define un campo fijo codigoRespuesta, estatus o mensaje dentro de OpEstadoCuentaResult.

Por ello, el manejo de errores debe contemplar fallas HTTP, errores SOAP y cualquier mecanismo funcional de error que OEL documente adicionalmente.

Ausencia de información

El WSDL permite que OpEstadoCuentaResult esté ausente.

Sin embargo, no especifica cómo representa el servicio un estado de cuenta sin movimientos, un período inexistente o una consulta sin resultados.

Estas situaciones deben validarse mediante pruebas de integración.

Códigos de respuesta y errores

El método OpEstadoCuenta no define un catálogo fijo de códigos de respuesta dentro del contrato WSDL.

A diferencia de OpVenta y otros métodos transaccionales, su resultado no contiene una propiedad codigoRespuesta declarada directamente.

Los integradores deben contemplar:

• Errores de transporte HTTP.

• Errores de protocolo SOAP (SOAP Fault).

• Errores de autenticación.

• Errores relacionados con valores de periodo no admitidos.

• Respuestas sin contenido o con estructura distinta de la esperada.

Consideraciones técnicas

• Período de consulta: este indica el periodo o mes a consultat haciendo uso de la siguiente nomenclatura:

  • 0 (mes actual)

  • -1 (mes anterior)

  • -2 (dos meses atras)

  • -3 (tres meses atras)

  • y así sucesivamente.

• Estructura dinámica: procesar el esquema y el contenido XML sin depender de nombres de columnas confirmados.

• Deserialización: utilizar un mecanismo compatible con la estructura XML devuelta por el servicio.

• Cambios de esquema: contemplar que la estructura dinámica podría variar entre versiones o configuraciones.

• Precisión numérica: utilizar tipos decimales adecuados cuando el esquema devuelto incluya importes monetarios.

• Seguridad: proteger las credenciales y utilizar conexiones HTTPS seguras.

• Datos sensibles: evitar registrar indiscriminadamente el contenido de la respuesta hasta conocer los datos que incluye.

• Validación XML: tratar el contenido devuelto como datos externos y aplicar controles de procesamiento XML seguro.

Relación con otros métodos