enviaVoucher

El método enviaVoucher permite solicitar al Gateway de Pagos de OEL el envío del comprobante mediante correo electrónico, de una venta previamente procesada.

La operación recibe las credenciales del comercio, información de identificación de la venta y una dirección de correo electrónico mediante el parámetro email.

Su finalidad es solicitar el envío del voucher correspondiente a una transacción existente, sin requerir que el integrador genere el comprobante a partir de los datos de autorización.

El método devuelve un resultado de procesamiento mediante códigos y mensajes de respuesta.

Información del servicio

El nombre de la operación distingue mayúsculas y minúsculas y debe utilizarse exactamente como enviaVoucher.

Autenticación

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

Adicionalmente, el cuerpo de la solicitud incluye comercioId y contrasena.

Las credenciales deben protegerse y no incorporarse en código fuente público ni en registros técnicos.

Parámetros de solicitud (Request)

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

Consideraciones sobre los parámetros

comercioId

Identifica al comercio que solicita el envío del comprobante.

Debe utilizarse el identificador asignado por OEL.

contrasena

Corresponde a la contraseña de autenticación del comercio.

Debe transmitirse mediante conexiones seguras y mantenerse protegida.

modo

Permite indicar el modo de operación utilizado por la integración.

monto

Representa el importe asociado a la venta cuyo comprobante se solicita.

Se recomienda utilizar el importe registrado en la transacción original.

transaccionId

Identifica la transacción cuyo voucher se desea enviar.

Se recomienda conservar el identificador retornado por el Gateway al procesar la venta original.

codigoAprobacion

Corresponde al código de aprobación bancaria asociado a la operación.

Es obligatorio y se utiliza como parte de la identificación de la venta.

referencia

Permite relacionar la solicitud con la referencia utilizada durante el procesamiento original.

Se recomienda mantener el mismo valor de la venta.

email

Contiene la dirección de correo electrónico a la que se solicita enviar el voucher.

El envío a un destinatario determinado requiere proporcionar una dirección de correo electrónico, se recomienda validar la dirección antes de invocar el servicio.

dirIp

Permite proporcionar una dirección IP asociada a la solicitud.

subcomercio

Permite identificar un subcomercio cuando la operación se realiza dentro de una estructura comercial que lo utiliza.

version

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

Ejemplo XML Request — SOAP 1.1

El siguiente ejemplo muestra una solicitud de envío de voucher utilizando valores ficticios y simbólicos.

La dirección cliente@example.com pertenece a un dominio reservado para documentación y no corresponde a un destinatario real.

<?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>
    <enviaVoucher>
      <request>
        <comercioId>12345</comercioId>
        <contrasena>CLAVE_COMERCIO</contrasena>
        <modo>MODO_CONFIGURADO</modo>
        <monto>500.00</monto>
        <transaccionId>ID_TRANSACCION_ORIGINAL</transaccionId>
        <codigoAprobacion>CODIGO_APROBACION</codigoAprobacion>
        <referencia>VENTA000001</referencia>
        <email>cliente@example.com</email>
        <dirIp>192.0.2.10</dirIp>
        <subcomercio>SUBCOMERCIO_ID</subcomercio>
        <version>VERSION_SDK</version>
      </request>
    </enviaVoucher>

Todos los valores son exclusivamente ilustrativos.

El ejemplo muestra el orden de los elementos establecido por cVoucherReq, pero no representa una solicitud ejecutable sin credenciales y datos válidos.

Cabeceras HTTP

Para enviar la solicitud mediante SOAP 1.1:

Parámetros de respuesta (Response)

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

Dentro de este elemento se encuentra enviaVoucherResult, de tipo cVoucherResp.

La respuesta contiene 4 parámetros.

La respuesta permite conocer el resultado comunicado por el Gateway, pero no proporciona por sí sola evidencia de entrega final del correo.

Ejemplo XML Response — Resultado ilustrativo

El siguiente ejemplo muestra una respuesta ficticia con los cuatro campos definidos en cVoucherResp.

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

  <soap:Body>
    <enviaVoucherResponse>
      <enviaVoucherResult>
        <codigoRespuesta>0</codigoRespuesta>
        <procReturnMsg>RESULTADO_SIMBOLICO</procReturnMsg>
        <ccErrorCode>0</ccErrorCode>
        <ccReturnMsg>MENSAJE_SIMBOLICO</ccReturnMsg>
      </enviaVoucherResult>
    </enviaVoucherResponse>

Los valores utilizados son exclusivamente ilustrativos.

Los valores codigoRespuesta=0 y ccErrorCode=0 deben interpretarse como una confirmación oficial de envío.

Interpretación de la respuesta

Procesamiento de la solicitud

El método devuelve información sobre el resultado del procesamiento mediante codigoRespuesta, procReturnMsg, ccErrorCode y ccReturnMsg.

Validación de la transacción original

El Request incluye monto, transaccionId, codigoAprobacion y referencia.

Estos datos permiten relacionar la solicitud con una venta.

Códigos de respuesta y errores

El método utiliza los siguientes campos para comunicar el resultado:

Consideraciones técnicas

Consulta de una venta existente

El método está orientado a solicitar el comprobante de una venta previamente procesada.

No requiere transmitir nuevamente PAN, Track 2 ni datos EMV.

Identificadores originales

Se recomienda utilizar los valores originales de transaccionId, monto, codigoAprobacion y referencia.

Esto reduce el riesgo de inconsistencias entre la solicitud y los datos registrados en el Gateway.

Validación del correo electrónico

Antes de invocar el servicio, la aplicación debe validar que el destinatario haya proporcionado una dirección con formato adecuado. También debe contemplar la posibilidad de que la dirección sea sintácticamente válida, pero no exista o no pueda recibir mensajes.

Protección de datos personales

La dirección de correo electrónico debe tratarse como dato personal.

Se recomienda limitar su almacenamiento, protegerla durante la transmisión y evitar su exposición innecesaria en registros técnicos.

Solicitudes duplicadas

Ante una falla de comunicación, el integrador no debe asumir que la solicitud de envío no fue procesada.

Manejo de respuestas indeterminadas

Una falla HTTP, un tiempo de espera agotado o un SOAP Fault no necesariamente indican que el correo no haya sido solicitado.

Se recomienda distinguir entre errores de transporte, errores funcionales del Gateway y confirmaciones de entrega.

Formato del comprobante

El voucher se envía como contenido HTML dentro del correo.

Trazabilidad

Se recomienda registrar de forma segura:

• Identificador de la transacción original.

• Referencia de la venta.

• Fecha y hora de la solicitud de envío.

• Resultado comunicado por el Gateway.

• Identificador interno de la solicitud en la aplicación, cuando corresponda.

No deben registrarse credenciales ni datos personales innecesarios.

Flujo operativo sugerido

El siguiente flujo es una propuesta de integración basada en la finalidad del método.

Paso 1. Venta procesada

La aplicación procesa una venta y conserva los identificadores retornados por el Gateway.

Paso 2. Solicitud de comprobante

El tarjetahabiente o el comercio solicita recibir el voucher mediante correo electrónico.

Paso 3. Captura del destinatario

La aplicación obtiene y valida la dirección de correo electrónico.

Paso 4. Preparación de la solicitud

La aplicación recupera los datos de la venta original:

• transaccionId

• monto

• codigoAprobacion

• referencia

Paso 5. Invocación de enviaVoucher

La aplicación envía la solicitud SOAP con los datos de la operación y el correo electrónico del destinatario.

Paso 6. Procesamiento por el Gateway

El Gateway procesa la solicitud de acuerdo con sus reglas internas.

Paso 7. Evaluación del resultado

La aplicación interpreta los códigos de respuesta y comunica al usuario el estado que efectivamente haya confirmado el servicio.

No debe mostrarse una confirmación definitiva de entrega si el Gateway únicamente confirmó el procesamiento de la solicitud.