ventaAutomatica

El método ventaAutomatica permite solicitar el procesamiento de una venta para un comercio previamente afiliado a Operaciones en Línea (OEL), utilizando el servicio SoapAliados.

La operación recibe las credenciales del aliado, la identificación y contraseña del comercio, el monto de la venta y dos identificadores opcionales para relacionarla con los registros del sistema integrador.

La respuesta contempla información del comercio, importe, identificadores de transacción, código de aprobación, fecha y hora de procesamiento, datos de terminal, campos asociados a EMV y códigos funcionales de resultado.

Importante: Para poder hacer uso de este metodo es necesario realizar una configuración previa, por lo cual tendrá que contactar a OEL para verificar la viabilidad de hacer uso de esta operación.

Información del servicio

Endpoint de producción

Endpoint de desarrollo

La existencia de este endpoint en la documentación no garantiza por sí sola que el ambiente esté disponible o que las credenciales proporcionadas tengan habilitada la operación.

Autenticación

El método utiliza dos niveles de identificación:

Cabecera SOAP OpHeader

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

Credenciales de negocio

El objeto request contempla:

Parámetros de solicitud (Request)

La operación recibe un objeto request de tipo cVentaAutomaticaReq, compuesto por siete parámetros.

Consideraciones de los parámetros

comercioId

Identifica al establecimiento que solicita la operación.

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

comercioContrasena

Representa la contraseña o credencial transaccional del comercio.

No debe confundirse con contrasena, que corresponde al aliado.

monto

Representa el importe de la venta.

transaccionId

Identificador proporcionado por el sistema integrador para relacionar la venta con sus propios registros.

Se recomienda generar un identificador único por intento lógico de venta, ya que el servicio puede llegar a impedir o rechazar cargos duplicados.

referencia

Permite asociar la venta con un pedido, folio o referencia del sistema integrador.

El contrato no define un formato obligatorio, longitud máxima ni reglas de unicidad.

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>
    <ventaAutomatica
        xmlns="https://servidorseguro.operacionesenlinea.com/">
      <request>
        <claveAliado>ALIADO_DEMO</claveAliado>
        <contrasena>CLAVE_ALIADO</contrasena>
        <comercioId>12345</comercioId>
        <comercioContrasena>CLAVE_COMERCIO</comercioContrasena>
        <monto>250.00</monto>
        <transaccionId>TXN-DEMO-000001</transaccionId>
        <referencia>PEDIDO-DEMO-001</referencia>
      </request>
    </ventaAutomatica>

Los identificadores, credenciales y valores de este ejemplo son ficticios.

La solicitud ilustra únicamente la estructura SOAP. No demuestra que un comercio de prueba esté habilitado ni que el servicio pueda ejecutar la venta sin configuraciones adicionales.

Parámetros de respuesta (Response)

El servicio devuelve el elemento ventaAutomaticaResponse, que puede contener ventaAutomaticaResult, de tipo cVentaAutomaticaResp.

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

1. Identificación del aliado y comercio

Estos campos permiten identificar a las partes relacionadas con la operación.

2. Identificación y resultado financiero de la venta

codigoAprobacion

Código de aprobación bancaria, típicamente de seis dígitos.

El integrador no debe asumir que el campo siempre estará presente ni utilizarlo como único indicador de aprobación.

fechaTransaccion y horaTransaccion

Ambos campos son cadenas de texto y representan la fecha y hora en la que se proceso la operación.

3. Datos de terminal y EMV

Los campos aid, tvr, tsi, apn, al y arqc están asociados a información EMV.

Consideración importante: aunque la respuesta contemple estos campos, la solicitud de ventaAutomatica no contiene información EMV ni datos de lectura de tarjeta.

4. Información de afiliación

Este campo puede ayudar a identificar la afiliación asociada al procesamiento de la venta.

5. Resultado funcional

Ejemplo XML Response — SOAP 1.1

El siguiente ejemplo representa una respuesta estructuralmente válida que contiene los 21 campos definidos en cVentaAutomaticaResp, respetando el orden del WSDL.

Los valores son ficticios y no representan una autorización bancaria real.

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

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

Notas sobre el ejemplo:

Los valores de aprobación, fecha, hora y EMV son cadenas simbólicas. No deben utilizarse para pruebas funcionales que requieran datos bancarios o EMV válidos.

Los valores 0 de los códigos de resultado se incluyen únicamente para ilustrar el tipo XML. No establecen que dichos códigos signifiquen aprobación para este método.

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

Interpretación de la respuesta

La aplicación integradora debe interpretar el resultado de la venta utilizando los códigos funcionales y la información devuelta por el servicio.

Resultado de autorización

El resultado de la operación debe determinarse mediante codigoRespuesta, ccErrorCode y mensajeRespuesta, conforme al catálogo confirmado por OEL.

El campo codigoAprobacion puede aportar información adicional cuando exista una autorización bancaria, pero no sustituye la validación del resultado funcional.

Identificación de la transacción

Se recomienda relacionar transaccionId, referencia, comercioId y monto con el registro interno de la solicitud.

Esto permite asociar la respuesta con el pedido o proceso de negocio que originó la venta.

Datos de terminal

Cuando se reciban, terminalId y los campos EMV pueden conservarse conforme a las políticas técnicas y de seguridad aplicables.

No debe asumirse que todos estarán disponibles en cada operación.

Respuestas incompletas

El WSDL permite que ventaAutomaticaResult esté ausente.

También permite la omisión de diversos campos dentro del resultado.

El integrador debe validar la existencia del objeto antes de procesar sus propiedades y contemplar respuestas 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 que solicita la venta y recuperar su credencial transaccional.

Paso 3. Validar la operación

Comprobar que el pedido o solicitud de cobro esté autorizado para procesamiento y que el importe corresponda al monto esperado.

Paso 4. Generar identificadores

Crear un transaccionId para relacionar el intento de venta con los registros internos y, cuando corresponda, una referencia de negocio.

Paso 5. Construir la solicitud SOAP

Incluir la cabecera OpHeader y los siete parámetros contemplados en cVentaAutomaticaReq.

Paso 6. Enviar la solicitud

Invocar ventaAutomatica mediante HTTPS.

Paso 7. Procesar la respuesta

Evaluar los campos funcionales y conservar los identificadores e información necesarios para conciliación.

Paso 8. Actualizar el estado interno

Registrar el resultado confirmado de la operación.

Si la respuesta es indeterminada, mantener un estado pendiente de verificación en lugar de marcar automáticamente la venta como rechazada.

Paso 9. Conciliar

Relacionar el resultado con los mecanismos de consulta y conciliación que OEL tenga disponibles para el comercio.

Este flujo constituye una recomendación de integración; no describe necesariamente todos los pasos internos de OpGateway.

Manejo de transacciones duplicadas y reintentos

La prevención de cargos duplicados es una consideración crítica para ventaAutomatica.

Identificador de transacción

El campo transaccionId permite identificar una solicitud desde el sistema integrador.

Sin embargo, el WSDL no confirma que OEL lo utilice como llave de idempotencia.

Por tanto, enviar dos solicitudes con el mismo transaccionId no garantiza que el servicio procese una sola venta.

Tiempo de espera

Si el cliente no recibe respuesta, la operación podría encontrarse en cualquiera de estas situaciones:

• No fue recibida por el servicio.

• Fue recibida, pero no procesada.

• Fue procesada y rechazada.

• Fue procesada y autorizada, pero la respuesta no llegó al integrador.

El contrato no permite distinguir estos casos únicamente a partir de un timeout.

Recomendación de implementación

Ante una respuesta indeterminada, el integrador debe evitar repetir automáticamente la venta.

Primero debe verificar su resultado mediante un mecanismo de consulta o conciliación confirmado por OEL.

Casos de uso

Automatización de procesos de cobro autorizados

La operación puede formar parte de un proceso automatizado de venta, siempre que el comercio esté habilitado y se cumplan las condiciones comerciales, técnicas y de autorización establecidas por OEL.

El contrato no confirma que la operación permita cobros recurrentes, cargos sin presencia del titular ni almacenamiento de instrumentos de pago.

Códigos de respuesta y errores

El servicio contempla:

Escenarios de prueba recomendados

Los escenarios anteriores son recomendaciones para certificación, no comportamientos confirmados del servicio.

Condiciones y limitaciones operativas

1. La operación procesa una venta

El método está descrito como una operación transaccional.

2. No recibe datos de tarjeta

El mecanismo que determina el instrumento de pago debe confirmarse con OEL.

3. Requiere identificación del comercio

La solicitud incluye comercioId y contempla comercioContrasena.

4. No establece límites de monto

El campo monto es de tipo decimal, sin restricciones de mínimo, máximo o precisión.

5. No contempla cancelación dentro del mismo método

La cancelación se documenta mediante la operación independiente cancelacionAutomatica.

Recomendaciones de seguridad

Ejecución desde sistemas autorizados

Consumir ventaAutomatica únicamente desde componentes de backend autorizados. Evitar exponer las credenciales directamente a navegadores o aplicaciones cliente.

Protección de credenciales

Almacenar OpKey1, OpKey2, claveAliado, contrasena y comercioContrasena mediante mecanismos seguros de gestión de secretos.

Validación del importe

Comprobar que el monto solicitado corresponda al pedido o proceso autorizado antes de invocar el servicio.

Control de duplicados

Mantener un registro interno de intentos y estados para evitar solicitudes repetidas desde el mismo proceso de negocio.

Trazabilidad

Registrar identificadores de operación, comercio, referencia, importe, fecha de solicitud y códigos de resultado, sin almacenar credenciales en los logs.

Manejo de estados indeterminados

No interpretar automáticamente una interrupción de comunicación como una venta fallida.

Protección de información EMV

Tratar los campos EMV conforme a las políticas de seguridad aplicables y conservar únicamente la información necesaria para operación, soporte y conciliación.

Control de acceso

Limitar la ejecución de ventas a procesos y usuarios expresamente autorizados.

Estas medidas son recomendaciones para la integración de OEL, no funcionalidades de seguridad adicionales garantizadas por el WSDL.

Relación con otros métodos

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