cancelacionAutomatica

Descripción

El método cancelacionAutomatica permite solicitar la cancelación de una operación de venta mediante el servicio SoapAliados de Operaciones en Línea (OEL).

La solicitud recibe las credenciales del aliado y del comercio, el monto de la operación, el identificador de transacción, el código de aprobación de la venta y una referencia de negocio.

Como resultado, el servicio devuelve información de identificación, datos de la operación y códigos funcionales de respuesta.

Información del servicio

Endpoint de producción

Endpoint de desarrollo

La disponibilidad efectiva del ambiente de pruebas y los permisos necesarios para realizar cancelaciones deberán verificarse con OEL.

Autenticación

La operación utiliza una cabecera SOAP OpHeader y las credenciales del aliado y del comercio incluidas en el objeto request.

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

Las credenciales deben conservarse en un entorno seguro y no exponerse directamente en aplicaciones cliente.

Parámetros de solicitud (Request)

El método recibe un objeto request de tipo cCancelacionAutomaticaReq, integrado por ocho parámetros.

Los campos se presentan en el orden exacto establecido por el WSDL.

Consideraciones de los parámetros

comercioId

Identifica al comercio relacionado con la operación que se desea cancelar.

Debe corresponder al establecimiento autorizado para solicitar la cancelación, conforme a las reglas de OEL.

comercioContrasena

Corresponde a la credencial transaccional del comercio.

No debe confundirse con contrasena, que identifica al aliado.

monto

Este valor debe corresponder al monto de la venta original.

transaccionId

Identificador de transacción proporcionado por el integrador.

Para una cancelación, este campo debe contener el identificador de la venta original.

codigoAprobacion

Este valor corresponde al código de autorización de la venta original.

referencia

Referencia de negocio asociada a la operación.

Este valor se utilizar para relacionar la cancelación con los registros administrativos del sistema integrador, debe coincidir con la referencia de la venta original.

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>
    <cancelacionAutomatica
        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>
        <codigoAprobacion>ABC123</codigoAprobacion>
        <referencia>PEDIDO-DEMO-001</referencia>
      </request>
    </cancelacionAutomatica>

Todos los valores son ficticios o simbólicos.

El ejemplo ilustra la estructura SOAP y utiliza identificadores relacionados con una venta hipotética.

Importante: la utilización del identificador de la venta original en transaccionId es ilustrativa.

Parámetros de respuesta (Response)

El servicio devuelve el elemento cancelacionAutomaticaResponse, que puede contener cancelacionAutomaticaResult, de tipo cCancelacionAutomaticaResp.

El WSDL define 16 parámetros.

1. Identificación del aliado y comercio

Estos campos permiten relacionar la respuesta con el aliado y el comercio correspondientes.

2. Información de la operación

3. Identificadores operativos

4. Resultado funcional

El integrador debe interpretar estos campos conforme a las reglas confirmadas por OEL.

Ejemplo XML Response — SOAP 1.1

El siguiente ejemplo contiene los 16 parámetros de cCancelacionAutomaticaResp, respetando su orden en el WSDL.

Todos los valores son ficticios y no representan una cancelación bancaria real.

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

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

Notas sobre el ejemplo

Los valores 0 en codigoRespuesta y ccErrorCode son ilustrativos y no establecen que estos códigos representen una cancelación aprobada.

Los identificadores de terminal, número de control y afiliación son simbólicos.

Interpretación de la respuesta

La aplicación integradora debe evaluar el resultado funcional y relacionar la respuesta con la operación cuya cancelación fue solicitada.

Resultado de cancelación

Los campos codigoRespuesta, ccErrorCode y mensajeRespuesta permiten conocer el resultado comunicado por el servicio.

Una respuesta HTTP 200 OK no confirma por sí misma que la venta haya sido cancelada.

Correspondencia de la operación

Se recomienda comprobar la correspondencia entre los datos enviados y los devueltos:

Estas verificaciones complementan la interpretación de los códigos funcionales, pero no sustituyen la confirmación de cancelación.

Identificadores de seguimiento

Cuando se reciban, terminalId, numeroControl y afiliacion pueden conservarse para tareas de trazabilidad, soporte y conciliación.

Respuestas incompletas

El integrador debe contemplar respuestas sin objeto de resultado, campos opcionales omitidos y errores SOAP Fault.

Flujo operativo recomendado

Paso 1. Identificar la venta

Localizar en el sistema integrador la operación que se desea cancelar.

Paso 2. Verificar los datos disponibles

Recuperar el identificador del comercio, monto, identificador de transacción, código de aprobación y referencia relacionados con la venta.

Paso 3. Validar la solicitud de cancelación

Comprobar que el usuario o proceso esté autorizado para solicitar la cancelación.

También se recomienda verificar que no exista una cancelación previamente confirmada o pendiente de resolución.

Paso 4. Preparar las credenciales

Obtener las credenciales del aliado y del comercio desde un almacenamiento seguro.

Paso 5. Construir el mensaje SOAP

Preparar la cabecera OpHeader y el objeto cCancelacionAutomaticaReq.

Paso 6. Enviar la solicitud

Invocar cancelacionAutomatica mediante HTTPS.

Paso 7. Evaluar la respuesta

Interpretar los códigos funcionales y recuperar los identificadores devueltos.

Paso 8. Actualizar el estado interno

Cuando exista una confirmación funcional válida, actualizar el registro administrativo de la operación.

Si la respuesta es indeterminada, mantener el estado pendiente de verificación.

Paso 9. Conciliar

Comprobar el resultado mediante los mecanismos de consulta o conciliación disponibles y confirmados por OEL.

Este flujo es una recomendación de integración y no representa necesariamente el procesamiento interno del servicio.

Manejo de cancelaciones duplicadas y reintentos

La prevención de solicitudes duplicadas es especialmente importante en las operaciones de cancelación.

Solicitudes repetidas

En caso de que solicite dos veces la cancelación de la misma venta, la segunda solicitud será rechazada automáticamente siempre y cuando la primera haya sido aceptada.

Tiempo de espera

Si el integrador no recibe respuesta, la cancelación podría encontrarse en una situación indeterminada.

Por ejemplo, la solicitud podría no haberse recibido, estar pendiente de procesamiento o haberse ejecutado sin que la respuesta llegara al cliente.

Recomendación de implementación

Ante una falla de comunicación, se recomienda:

1. Conservar los datos de la solicitud original.

2. Registrar el intento como pendiente de verificación.

3. Consultar el estado de la operación mediante un mecanismo confirmado por OEL.

4. Evitar reintentos automáticos hasta determinar el resultado.

5. Repetir la cancelación únicamente conforme al procedimiento autorizado.

La documentación no confirma qué método de SoapGateway puede utilizarse para verificar específicamente una cancelación iniciada mediante SoapAliados.

Casos de uso

Cancelación de una venta previamente procesada

Un sistema administrativo autorizado puede solicitar la cancelación de una venta, utilizando los datos de identificación y autorización disponibles.

Cancelación relacionada con un pedido

La operación puede vincularse con un pedido del sistema integrador mediante referencia y transaccionId.

Corrección de operaciones

Un comercio puede requerir cancelar una operación como parte de sus procedimientos administrativos.

Conciliación de cancelaciones

Los campos de respuesta pueden utilizarse para conservar trazabilidad y relacionar la solicitud con los registros internos.

Códigos de respuesta y errores

Los campos de resultado son:

Escenarios de prueba recomendados

Estos son escenarios recomendados para pruebas de integración, no comportamientos confirmados del servicio.

Condiciones y limitaciones operativas

1. Requiere una operación relacionada

El método está documentado para cancelar una venta previamente aprobada.

2. Plazo de cancelación

El proceso de Cancelación solo podra solicitarse el mismo día en que se efectuó la venta original.

3. Cancelaciones totales

Solo pueden cancelarse importes iguales al monto de la venta original.

4.transaccionId

Este valor corresponde al mismo transaccionId de la venta original.

Recomendaciones de seguridad y control

Autorización de cancelaciones

Permitir la ejecución únicamente a usuarios y procesos con facultades para cancelar operaciones.

Verificación de la venta original

Antes de solicitar la cancelación, comprobar que los datos disponibles correspondan a la operación esperada.

Protección de credenciales

Mantener OpKey1, OpKey2, claveAliado, contrasena y comercioContrasena fuera de registros de aplicación y componentes cliente.

Control de duplicidad

Registrar los intentos de cancelación para evitar solicitudes repetidas desde diferentes procesos.

Trazabilidad

Conservar el comercio, monto, referencia, identificadores, fecha de solicitud y resultado comunicado por el servicio.

Estados indeterminados

No interpretar automáticamente un timeout como una cancelación fallida.

Conciliación

Relacionar las cancelaciones confirmadas con los registros transaccionales y financieros disponibles.

Separación de funciones

Cuando corresponda, establecer controles administrativos de aprobación antes de solicitar cancelaciones.

Estas medidas son recomendaciones para integradores de OEL, no funcionalidades adicionales garantizadas por el WSDL.

Relación con otros métodos

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