Servicios Aliados

SoapAliados es el servicio de integración SOAP de Operaciones en Línea (OEL) que permite a los aliados comerciales administrar establecimientos afiliados, configurar sus condiciones comerciales, consultar información financiera y ejecutar determinadas operaciones transaccionales.

A través de este servicio, los sistemas externos pueden comunicarse directamente con la infraestructura de OEL para automatizar procesos administrativos y financieros, reduciendo la necesidad de realizar estas operaciones manualmente.

La API está diseñada para integraciones de servidor a servidor y utiliza mensajes XML mediante los protocolos SOAP 1.1 y SOAP 1.2 sobre HTTPS.

¿Qué puedes hacer con SoapAliados?

El servicio proporciona funcionalidades agrupadas en cinco áreas principales.

Administración de comercios

Permite incorporar establecimientos a la plataforma de OEL y consultar sus datos de registro.

Entre sus capacidades se encuentran la afiliación de nuevos comercios, la generación de credenciales y la consulta de información comercial, fiscal, bancaria y operativa.

Configuración comercial

Permite administrar las comisiones aplicables a los establecimientos afiliados.

Incluye la actualización de tasas asociadas a diferentes categorías de tarjetas y medios de pago, de acuerdo con la configuración autorizada para cada comercio.

Operaciones transaccionales

Facilita la ejecución de determinadas operaciones de venta y cancelación mediante los servicios transaccionales de OEL.

Estas operaciones están disponibles para los aliados y comercios que cuenten con las autorizaciones y configuraciones correspondientes.

Administración financiera

Permite consultar saldos disponibles y solicitar transferencias de fondos entre comercios.

Consultas y reportes

Ofrece operaciones para obtener información relacionada con cortes diarios y estados de cuenta de los comercios afiliados.

Estas funcionalidades permiten integrar información financiera y operativa con sistemas administrativos, contables o de conciliación.

Información general del servicio

Ambientes de integración

Producción — URL indicada en el Manual de Integración v1.3

Desarrollo — URL indicada en la especificación técnica v2.0

WSDL de referencia

Autenticación

Todas las operaciones del servicio requieren autenticación mediante una cabecera SOAP denominada OpHeader.

Esta cabecera contiene dos valores proporcionados por OEL:

La estructura de la cabecera es la siguiente:

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

Credenciales del aliado

Además de la cabecera SOAP, las operaciones incorporan generalmente dos parámetros de autenticación dentro del objeto request:

Las credenciales de cabecera y las credenciales de negocio cumplen funciones diferentes y deben enviarse conforme al contrato de cada método.

Recomendaciones de seguridad

• Mantener todas las credenciales exclusivamente en el backend.

• Utilizar mecanismos seguros para almacenar y administrar secretos.

• No incluir contraseñas ni llaves en repositorios, archivos públicos o registros de diagnóstico.

• Configurar credenciales independientes para los ambientes de desarrollo y producción cuando OEL las proporcione.

• Limitar el acceso a las operaciones financieras y administrativas según los permisos de cada integración.

Catálogo de operaciones

El WSDL proporcionado contiene las siguientes diez operaciones.

Administración de comercios

Operaciones transaccionales

Administración financiera

Consultas y reportes

Estructura de una solicitud SOAP

Las operaciones utilizan mensajes SOAP enviados mediante HTTP POST.

Cada solicitud contiene tres componentes principales:

1. Envelope: elemento raíz del mensaje SOAP.

2. Header: cabecera de autenticación OpHeader.

3. Body: operación que se desea ejecutar y sus parámetros de entrada.

Ejemplo de solicitud SOAP 1.1

El siguiente ejemplo muestra la estructura general de una consulta de saldo mediante saldoComercio.

Petición HTTP

Cuerpo XML

<?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>CLAVE_ALIADO_ASIGNADA</claveAliado>
        <contrasena>CONTRASENA_ALIADO_ASIGNADA</contrasena>
        <comercioId>12345</comercioId>
      </request>
    </saldoComercio>

Los identificadores y credenciales utilizados son ficticios o simbólicos. Este ejemplo ilustra la estructura del mensaje y requiere credenciales válidas para su ejecución.

Ejemplo de respuesta SOAP 1.1

<?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/">

Esta respuesta es exclusivamente ilustrativa. Los valores mostrados no representan una operación real ni establecen por sí mismos el significado oficial de los códigos de resultado.

El nombre del elemento SaldoDisponible debe conservarse exactamente, incluyendo su letra inicial mayúscula.

Manejo de respuestas y errores

La mayoría de las operaciones utilizan tres campos para comunicar el resultado de su ejecución:

El integrador debe distinguir entre:

• Errores de transporte: problemas de conectividad, certificados, tiempos de espera o comunicación HTTP.

• Errores SOAP: respuestas de tipo SOAP Fault, que pueden indicar problemas de procesamiento del mensaje.

• Resultados funcionales: respuestas del servicio que contienen códigos y mensajes propios de la operación.

  
  

En operaciones que modifican información o mueven fondos, una interrupción de comunicación no debe interpretarse automáticamente como una operación rechazada. Es necesario confirmar el resultado antes de intentar repetirla.

Flujo recomendado de integración

1. Obtener las credenciales

Solicitar a OEL las llaves de cabecera y las credenciales del aliado correspondientes al ambiente de integración.

2. Configurar la comunicación

Validar el acceso HTTPS, la compatibilidad TLS, la resolución DNS y las reglas de conectividad necesarias para consumir el endpoint.

3. Implementar el cliente SOAP

Construir