cambioComisiones

El método cambioComisiones permite modificar las comisiones asociadas a un comercio previamente afiliado a la plataforma de Operaciones en Línea (OEL), mediante el servicio SoapAliados.

La operación recibe el identificador del comercio y cinco valores de comisión correspondientes a distintas categorías de tarjetas. Como resultado, devuelve información del establecimiento, las comisiones reportadas por el servicio y los códigos funcionales de respuesta.

Este método realiza una operación administrativa de modificación. No procesa ventas, devoluciones, cancelaciones ni movimientos de saldo.

Información del servicio

Endpoint de producción

Endpoint de desarrollo

El WSDL proporcionado utiliza una capitalización distinta en la ruta del servicio. Debe confirmarse con OEL la dirección canónica antes de integrar el ambiente productivo.

Autenticación

La operación utiliza la cabecera SOAP OpHeader y las credenciales del aliado incluidas dentro del 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 del aliado

Las credenciales deben almacenarse de manera segura y utilizarse únicamente desde sistemas autorizados.

Parámetros de solicitud (Request)

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

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

Identificación del comercio

El campo comercioId identifica el establecimiento cuyas condiciones comerciales se desean modificar.

Este identificador puede obtenerse previamente mediante afiliacionComercio o utilizarse para consultar la configuración del establecimiento mediante detalleComercio.

Comisiones solicitadas

Los cinco campos de comisión utilizan el tipo XML decimal.

Los valores de las comisiones estan expresados en terminos de porcentaje expresados con dos enteros y dos decimales.Los valores enviados a traves de los campos de cambioComisionesson nuevas comisiones para cada categoría.

Para mantener consistencia entre ambos métodos, los ejemplos siguientes representan los valores como porcentajes.

Estos valores son exclusivamente ficticios. No representan tasas comerciales oficiales, autorizadas o recomendadas por OEL.

Obligatoriedad de las cinco comisiones

Los campos debito, credito, amex, internacional y valeras son estructuralmente obligatorios.

Esto significa que una solicitud válida conforme al esquema debe incluir los cinco elementos, incluso cuando el objetivo comercial sea modificar únicamente una categoría.

Por ello, antes de solicitar un cambio se recomienda consultar las comisiones actuales mediante detalleComercio, determinar los valores finales deseados y enviar el conjunto completo.

Esta es una recomendación de integración, no una garantía de actualización atómica.

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>
    <cambioComisiones
        xmlns="https://servidorseguro.operacionesenlinea.com/">
      <request>
        <claveAliado>ALIADO_DEMO</claveAliado>
        <contrasena>CLAVE_ALIADO</contrasena>
        <comercioId>12345</comercioId>
        <debito>2.50</debito>
        <credito>3.00</credito>
        <amex>3.50</amex>
        <internacional>4.00</internacional>
        <valeras>2.00</valeras>
      </request>
    </cambioComisiones>

Todos los datos son ficticios o simbólicos.

Para ejecutar la solicitud deben reemplazarse las credenciales y el identificador del comercio por valores válidos, y utilizarse exclusivamente tasas autorizadas para el establecimiento.

Parámetros de respuesta (Response)

El servicio devuelve el elemento cambioComisionesResponse, que puede contener cambioComisionesResult, de tipo cComisionesResp.

El objeto de respuesta define doce parámetros.

Identificación del comercio

Los campos aliadoID, nombreAliado, comercioId y nombreComercial permiten identificar al aliado y al establecimiento relacionados con la operación.

Es recomendable verificar que el comercioId devuelto corresponda al comercio solicitado, siempre que la operación haya concluido satisfactoriamente.

Comisiones devueltas

Los campos debito, credito, amex, internacional y valeras contienen los valores de comisión reportados por el servicio y se interpretaran como comisiones aplicadas. Debe tener en consideración que las tasas se actualizan de forma inmediata.

Códigos de resultado

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

Ejemplo XML Response — SOAP 1.1

El siguiente ejemplo contiene los doce parámetros de cComisionesResp, en el orden establecido por el WSDL.

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

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

Los valores son ficticios.

Interpretación de la respuesta

La aplicación debe evaluar tanto el resultado funcional como los valores de comisión devueltos.

Resultado funcional

Los campos codigoRespuesta, ccErrorCode y mensajeRespuesta deben interpretarse conjuntamente, conforme al catálogo de respuestas que confirme OEL.

Una respuesta HTTP satisfactoria no debe considerarse prueba suficiente de que las condiciones comerciales fueron modificadas.

Correspondencia del comercio

Se recomienda comprobar que el comercioId de la respuesta corresponda al establecimiento para el que se solicitó el cambio.

Comparación de comisiones

Cuando la respuesta indique que la operación fue procesada satisfactoriamente, se recomienda comparar los valores solicitados con los valores devueltos.

Por ejemplo:

Esta tabla es ilustrativa y no representa una operación real.

Una coincidencia entre valores solicitados y devueltos ayuda a verificar la respuesta.

Verificación posterior

Se recomienda consultar detalleComercio después de un cambio confirmado para verificar las comisiones registradas.

Si la información no coincide, el integrador debe conservar la trazabilidad de ambas operaciones y seguir el procedimiento de aclaración acordado con OEL.

Flujo operativo de modificación de comisiones

Paso 1. Identificar al comercio

Obtener el comercioId del establecimiento cuyas comisiones se desean modificar.

Paso 2. Consultar las comisiones actuales

Invocar detalleComercio para conocer los valores registrados antes de realizar la modificación.

Paso 3. Determinar las nuevas condiciones comerciales

Establecer las cinco tasas que se enviarán en la solicitud, conforme a las condiciones comerciales autorizadas.

Paso 4. Validar los valores

Comprobar que los importes decimales tengan el formato esperado y se encuentren dentro de los límites autorizados para el aliado y el comercio.

Paso 5. Construir la solicitud SOAP

Preparar el mensaje con OpHeader, las credenciales del aliado, el identificador del comercio y las cinco comisiones.

Paso 6. Enviar la solicitud

Invocar cambioComisiones mediante HTTPS.

Paso 7. Evaluar la respuesta

Interpretar los códigos funcionales y comparar las comisiones reportadas por el servicio.

Paso 8. Consultar la configuración registrada

Cuando corresponda, ejecutar detalleComercio para comprobar los valores que el servicio devuelve después de la modificación.

Paso 9. Registrar la operación

Conservar un registro administrativo del cambio solicitado, sus valores anteriores y nuevos, el resultado y los identificadores necesarios para auditoría.

Casos de uso

Actualización de condiciones comerciales

Permite solicitar un cambio en las tasas asociadas a un establecimiento cuando se acuerdan nuevas condiciones entre las partes autorizadas.

Ajuste de comisiones por categoría

El aliado puede necesitar modificar la tasa correspondiente a una categoría de tarjeta.

Aunque comercialmente se desee ajustar una sola tasa, el contrato requiere enviar los cinco campos de comisión.

Actualización posterior a la afiliación

Después de registrar un comercio mediante afiliacionComercio, puede ser necesario modificar las comisiones inicialmente configuradas.

Verificación de condiciones registradas

El método puede combinarse con detalleComercio para comprobar los valores devueltos después de una modificación.

Conciliación administrativa

Un sistema de administración puede conservar el historial de solicitudes de cambio para contrastar las condiciones pactadas con las comisiones reportadas por OEL.

El contrato no proporciona por sí mismo un historial de modificaciones ni un reporte de vigencias.

Códigos de respuesta y errores

Los campos de resultado son:

Escenarios de prueba recomendados

Estos son escenarios recomendados para certificación, no códigos ni comportamientos confirmados por el WSDL.

Condiciones y limitaciones operativas

1. Requiere un comercio existente

El método recibe un identificador comercioId.

No permite registrar un establecimiento nuevo. Para ello se utiliza afiliacionComercio.

2. Requiere credenciales de aliado

La operación utiliza la cabecera OpHeader y las credenciales del aliado.

3. Las cinco comisiones son obligatorias

Los cinco campos de tasa son obligatorios.

4. Límites comerciales

Los campos de comisión son de tipo decimal y los valores de estos deben ser igual o mayores a las tasas minimas acordadas previamente con OEL.

5. Fecha de aplicación

Las nuevas comisiones solicitadas entran en vigor de manera inmediata una vez aceptadas por el servicio.

6. No incluye historial de cambios

El método no devuelve valores anteriores, versiones de comisiones ni identificadores de auditoría.

Si el integrador necesita ese historial, deberá conservarlo en sus propios sistemas.

7. No modifica otros datos comerciales

La solicitud no incluye parámetros para modificar domicilio, RFC, cuenta bancaria, contactos o productos habilitados.

Recomendaciones de seguridad y control administrativo

Por tratarse de una operación que modifica condiciones económicas, se recomienda implementar controles adicionales.

Autorización previa

Permitir modificaciones únicamente a usuarios o procesos con facultades para administrar condiciones comerciales.

Validación de tasas

Comprobar que los valores solicitados correspondan a condiciones autorizadas antes de invocar el servicio.

Registro de valores anteriores

Consultar y conservar las comisiones existentes antes de solicitar una modificación.

Auditoría

Registrar el comercio afectado, las tasas anteriores, las tasas solicitadas, la fecha de la solicitud, el sistema responsable y los códigos devueltos.

Protección de credenciales

Evitar que OpKey1, OpKey2, claveAliado y contrasena aparezcan en registros de aplicación, repositorios o respuestas de APIs públicas.

Control de concurrencia

Coordinar las modificaciones para evitar que dos procesos envíen cambios incompatibles al mismo establecimiento.

Verificación posterior

Consultar detalleComercio para contrastar las comisiones registradas con las solicitadas.

Manejo de reintentos

Ante respuestas indeterminadas, verificar primero el estado del comercio antes de repetir la modificación.

Estas medidas son recomendaciones de OEL para sus integradores y no garantías documentadas del comportamiento interno de OEL.

Relación con otros métodos

El flujo administrativo recomendado es:

afiliacionComercio → detalleComercio → cambioComisiones → detalleComercio

La segunda consulta permite verificar los valores registrados después de la modificación.