ecommerceSessionID

1. Descripción

El método ecommerceSessionID permite generar un token de sesión de un solo uso que sustituye temporalmente la contraseña del comercio durante la ejecución de operaciones de comercio electrónico.

Su propósito principal es evitar que las credenciales permanentes del comercio sean expuestas cuando una operación de pago se invoca directamente desde el navegador del comprador hacia el Gateway de OEL.

El token generado se devuelve en el campo sessionId y puede enviarse posteriormente como valor del campo contrasena de la operación de pago correspondiente.

Importante: el token está diseñado para utilizarse una sola vez. Cuando se requiere ejecutar otra operación, debe obtenerse un nuevo token.

2. Funcionamiento

El proceso se divide en dos etapas:

Etapa 1. Generación del token

El sistema del comercio invoca ecommerceSessionID, proporcionando su identificador y contraseña permanente.

Si la solicitud es aceptada, el servicio devuelve un token mediante el campo sessionId.

Etapa 2. Ejecución de la operación

El token obtenido se utiliza en lugar de la contraseña permanente del comercio al invocar una operación de comercio electrónico, por ejemplo ecommerceVenta.

De esta manera, el navegador no necesita conocer la contraseña permanente para realizar la solicitud de pago.

Flujo de integración

Este flujo representa el caso de uso en el que el navegador realiza directamente la operación de pago. El comercio debe asegurar que la obtención del token se realice en un componente protegido.

3. Especificaciones técnicas

Namespace

SOAPAction

Endpoint definido en el WSDL

La configuración de ambientes se describirá en su apartado correspondiente.

4. Parámetros de entrada

La solicitud utiliza la estructura cSessionReq.

Consideraciones

• comercioId debe corresponder al comercio para el cual se solicita el token.

• contrasena debe contener la credencial permanente del comercio en esta primera solicitud.

• La contraseña permanente no debe exponerse en el código fuente del navegador ni enviarse al comprador.

5. Encabezado de autenticación

El contrato WSDL declara el encabezado SOAP OpHeader para esta operación.

Estos valores se representan mediante credenciales simbólicas en los ejemplos.

Nota: Estas claves deben enviarse obligatoriamente durante la operación real. El token sessionId en ningun momento sustituyen a las claves del encabezado OpHeader; únicamente se utilizan como reemplazo decontrasena.

6. Ejemplo de solicitud SOAP 1.1

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    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>
    <ecommerceSessionID
        xmlns="https://servidorseguro.operacionesenlinea.com/">
      <request>
        <comercioId>12345</comercioId>
        <contrasena>CONTRASENA_DEL_COMERCIO</contrasena>
      </request>
    </ecommerceSessionID>

Encabezados HTTP para SOAP 1.1

Los valores utilizados en este ejemplo son ficticios y únicamente muestran la estructura de integración.

7. Parámetros de respuesta

La respuesta utiliza la estructura cSessionResp.

Consideraciones sobre la respuesta

El campo más importante para la continuidad del flujo es sessionId, ya que contiene el valor que sustituirá la contraseña permanente del comercio.

La presencia de codigoRespuesta y ccErrorCode permite evaluar el resultado del servicio, pero sus valores deben interpretarse conforme al catálogo oficial de respuestas.

8. 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>
    <ecommerceSessionIDResponse
        xmlns="https://servidorseguro.operacionesenlinea.com/">

Advertencia: esta respuesta es ilustrativa. Los valores 0 no deben interpretarse automáticamente como aprobación o éxito sin el catálogo oficial. La fecha, el token y los mensajes son datos ficticios.

9. Utilización del token en operaciones de comercio electrónico

Una vez obtenido el valor sessionId, este se utiliza como reemplazo de la contraseña permanente del comercio en la siguiente solicitud de pago.

Ejemplo conceptual

Solicitud original con contraseña permanente:

<request>
  <comercioId>12345</comercioId>
  <contrasena>CONTRASENA_DEL_COMERCIO</contrasena>
  <!-- Otros parámetros de la operación -->
</request>

Solicitud utilizando el token:

<request>
  <comercioId>12345</comercioId>
  <contrasena>TOKEN_UN_SOLO_USO_XYZ123</contrasena>
  <!-- Otros parámetros de la operación -->
</request>

El nombre del campo permanece sin cambios: contrasena.

No es necesario incorporar un elemento XML adicional llamado sessionId en la solicitud de venta. El token se envía dentro del campo existente.

Ejemplo de integración con ecommerceVenta

<ecommerceVenta
    xmlns="https://servidorseguro.operacionesenlinea.com/">
  <request>
    <comercioId>12345</comercioId>
    <contrasena>TOKEN_UN_SOLO_USO_XYZ123</contrasena>
    <!-- Continuar con los demás campos de cTCReq,
         respetando su orden definido en el WSDL -->
  </request>
</ecommerceVenta>

Este fragmento demuestra exclusivamente la sustitución de credenciales. No representa una solicitud de venta completa.

10. Restricciones y ciclo de vida del token

10.1. Uso único

Cada token se genera para utilizarse una sola vez.

El integrador no debe reutilizar el mismo valor para ejecutar varias operaciones.

10.2. Asociación con el comercio

El token se solicita proporcionando un comercioId y la contraseña del comercio correspondiente.

La respuesta incluye nuevamente comercioId, por lo que el integrador puede comprobar que el identificador recibido coincide con el solicitado.

10.3. Nueva solicitud

Cuando se necesite ejecutar otra operación, deberá solicitarse un nuevo token.

10.4. Vigencia

El WSDL no especifica un tiempo de expiración del token.

Por tanto, no se establece en esta documentación una duración en segundos o minutos.

10.5. Consumo del token

El carácter de un solo uso está confirmado funcionalmente. El token se considera consumido en cualquiera de las siguientes situaciones:

• Al recibir una solicitud de pago.

• Después de validar las credenciales.

• Al obtener una respuesta del procesador.

• Incluso cuando la operación es rechazada o falla.

Recomendación conservadora: ante un intento de utilización o un resultado incierto, solicitar un nuevo token y verificar previamente que no se haya procesado el cargo original.

11. Consideraciones de seguridad

El mecanismo ecommerceSessionID permite reducir la exposición de la contraseña permanente en integraciones que realizan solicitudes directamente desde el navegador.

No obstante, el token sigue siendo una credencial temporal que debe protegerse.

Se recomienda:

1. Obtener el token desde un backend seguro.

2. No transmitir la contraseña permanente al navegador.

3. Entregar el token únicamente a la sesión de compra que lo requiere.

4. Evitar incluir el token en direcciones URL, registros de consola, herramientas de analítica o logs.

5. Utilizar conexiones HTTPS.

6. Solicitar un token nuevo para cada operación.

7. Evitar conservar tokens que ya fueron utilizados.

8. Proteger el endpoint del comercio que genera tokens mediante controles de autenticación, autorización y prevención de abuso.

El WSDL declara OpHeader también en las operaciones de comercio electrónico.

La sustitución de contrasena por sessionId no significa que OpKey1 y OpKey2 puedan omitirse ni que sea seguro exponerlos en un navegador.

Antes de implementar llamadas directas desde el cliente, es necesario confirmar el mecanismo de manejo de este encabezado y las políticas de seguridad correspondientes.

El uso de un token de sesión para sustituir la contraseña del comercio no equivale a tokenizar los datos de la tarjeta.

Si el navegador o la aplicación maneja directamente datos de tarjeta, el comercio debe evaluar los controles y obligaciones aplicables a esa arquitectura.

12. Manejo de errores

El integrador debe considerar las siguientes situaciones:

La respuesta SOAP de ecommerceSessionID no confirma por sí misma que un pago haya sido realizado. Únicamente forma parte del mecanismo de preparación de una operación posterior.

13. Buenas prácticas de integración

Para implementaciones que utilicen llamadas directas desde el navegador, se recomienda mantener separados los siguientes componentes:

Backend del comercio

Responsable de custodiar las credenciales permanentes y solicitar el token.

Frontend del comercio

Responsable de utilizar el token temporal para realizar la operación permitida, sin acceder a la contraseña permanente.

Gateway de OEL

Responsable de recibir la operación, validar los datos enviados y procesar la solicitud conforme a las reglas del servicio.

14. Métodos relacionados

La compatibilidad operativa de cada método con el token debe verificarse en pruebas de integración, especialmente si existen reglas específicas por tipo de operación.