afiliacionComercio

El método afiliacionComercio permite registrar un nuevo comercio en la plataforma de Operaciones en Línea (OEL) a través del servicio SoapAliados.

Durante el proceso de afiliación, el aliado proporciona la información comercial, fiscal, bancaria y operativa del establecimiento, así como las comisiones pactadas y los productos de pago que se desean habilitar.

Como resultado, el Gateway devuelve información del comercio registrado, incluyendo su identificador, credenciales transaccionales, credenciales de acceso al portal y las comisiones resultantes.

Este método está destinado a integraciones administrativas autorizadas. No procesa una venta ni solicita una autorización bancaria.

Información del servicio

Endpoint de producción

Endpoint de desarrollo

Autenticación

La operación requiere credenciales de acceso al servicio y credenciales de identificación del aliado.

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

Ambos parámetros se incluyen dentro del objeto request.

Las credenciales deben mantenerse en un entorno seguro y nunca exponerse directamente en aplicaciones cliente.

Parámetros de solicitud (Request)

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

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

1. Identificación del aliado e información comercial

Consideraciones funcionales

Los campos afiliacion y giro están definidos como string en el WSDL, aun cuando la especificación funcional solicita valores numéricos.

El catálogo de giros debe utilizarse para determinar la clave correspondiente a la actividad del comercio.

2. Información de facturación y operación comercial

Importante: los cinco campos son estructuralmente requeridos, pero admiten valor = 0

La especificación funcional describe los horarios mediante dos dígitos, por lo cual tendran que expresarse las horas en formato de 24hrs.

La facturación y los importes se expresan siempre en pesos mexicanos.

3. Información fiscal y de facturación

4. Representante legal

Estos datos son requeridos para el procesamiento de tarjetas American Express.

5. Información bancaria

La Información Bancaria es necesaria ya que nos permite registrar la cuenta utilizada para compensar las ventas del comercio.

Consideración técnica: banco es un entero en el WSDL. Si el código del banco requiere ceros a la izquierda, debe confirmarse cómo los interpreta el servicio.

6. Comisiones pactadas

Los cinco campos son obligatorios y se expresan en como porcentajes con dos enteros y dos decimales con valores entre el rango de 0 y 100.

Por ejemplo, el valor 2.50 representa una comisión del 2.50 %.

Las tasas que pueden asignarse a un comercio deben ajustarse a los acuerdos comerciales autorizados para el aliado.

7. Productos habilitados

La selección de un producto en el Request no debe interpretarse automáticamente como confirmación de que el comercio quedó operativo para ese canal. La activación efectiva debe validarse conforme al proceso de OEL.

8. Contacto técnico

Estos datos permiten identificar a la persona responsable de la integración o del soporte técnico del establecimiento.

Ejemplo XML Request — SOAP 1.1

El siguiente ejemplo muestra una solicitud de afiliación con valores exclusivamente ficticios o simbólicos.

No debe ejecutarse directamente: contiene credenciales de ejemplo, identificadores de catálogo ilustrativos y marcadores que deben reemplazarse por datos válidos.

<?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>
    <afiliacionComercio>
      <request>
        <claveAliado>ALIADO_DEMO</claveAliado>
        <contrasena>CLAVE_ALIADO</contrasena>
        <tipo>1</tipo>
        <afiliacion>1</afiliacion>
        <giro>GIRO_CATALOGO</giro>
        <nombreComercial>Comercio Ejemplo</nombreComercial>
        <direccion>Calle Ejemplo 100</direccion>
        <colonia>Colonia Ejemplo</colonia>
        <ciudad>Ciudad Ejemplo</ciudad>
        <estado>Estado Ejemplo</estado>
        <cp>01000</cp>
        <telefono>0000000000</telefono>
        <email>comercio@example.com</email>
        <facturacionMensual>100000.00</facturacionMensual>
        <ticketPromedio>500.00</ticketPromedio>
        <ticketMaximo>5000.00</ticketMaximo>
        <horarioApertura>9</horarioApertura>
        <horarioCierre>20</horarioCierre>
        <rfc>RFC_FICTICIO</rfc>
        <razonSocial>Comercio Demostracion</razonSocial>
        <facturaDireccion>Calle Fiscal 200</facturaDireccion>
        <facturaColonia>Colonia Fiscal</facturaColonia>
        <facturaCiudad>Ciudad Ejemplo</facturaCiudad>
        <facturaEstado>Estado Ejemplo</facturaEstado>
        <facturaCP>01000</facturaCP>
        <facturaTelefono>0000000000</facturaTelefono>
        <facturaContacto>Contacto Ejemplo</facturaContacto>
        <facturaEmail>facturacion@example.com</facturaEmail>
        <legalNombre>Nombre Ejemplo</legalNombre>
        <legalApellido>Apellido Ejemplo</legalApellido>
        <legalNacimiento>FECHA_SIMBOLICA</legalNacimiento>
        <banco>123</banco>
        <clabe>CLABE_FICTICIA</clabe>
        <titularCuenta>Titular Ejemplo</titularCuenta>
        <debito>2.50</debito>
        <credito>3.00</credito>
        <amex>3.50</amex>
        <internacional>4.00</internacional>
        <valeras>2.00</valeras>
        <linkPago>true</linkPago>
        <tpv>true</tpv>
        <eCommerce>false</eCommerce>
        <tecnicoNombre>Contacto Tecnico</tecnicoNombre>
        <tecnicoTelefono>0000000000</tecnicoTelefono>
        <tecnicoEmail>soporte@example.com</tecnicoEmail>
      </request>
    </afiliacionComercio>

Nota: FECHA_SIMBOLICA es deliberadamente un marcador de posición. El código de giro y los datos bancarios también deben reemplazarse por valores válidos antes de realizar una prueba.

Cabeceras HTTP

Para SOAP 1.1:

Parámetros de respuesta (Response)

El servicio devuelve el elemento afiliacionComercioResponse, que contiene afiliacionComercioResult, de tipo cAfiliacionResp.

La respuesta está integrada por 18 parámetros.

Credenciales generadas

El método puede devolver dos conjuntos de credenciales diferentes.

Credenciales transaccionales

• comercioId

• contrasena

Se utilizan para identificar y autenticar al comercio en los servicios transaccionales que las requieran.

Credenciales del portal

• usuarioPortal

• contrasenaPortal

Se utilizan para acceder al portal correspondiente, según los permisos y procedimientos establecidos por OEL.

Importante: estas credenciales deben protegerse inmediatamente después de recibirlas. No deben exponerse en respuestas de APIs públicas ni registrarse en texto plano.

Comisiones resultantes

La respuesta incluye cinco campos de comisión con el prefijo comision_.

Estos valores deben distinguirse de las tasas solicitadas originalmente mediante debito, credito, amex, internacional y valeras.

Se recomienda utilizar las comisiones devueltas para verificar las condiciones registradas, una vez confirmado el resultado exitoso de la afiliación.

Ejemplo XML Response — SOAP 1.1

El siguiente ejemplo representa una respuesta ficticia con los 18 campos definidos en cAfiliacionResp.

Los códigos utilizados no establecen por sí mismos el significado oficial de una afiliación exitosa.

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

  <soap:Body>
    <afiliacionComercioResponse>
      <afiliacionComercioResult>
        <aliadoID>100</aliadoID>
        <aliadoNombre>Aliado Demostracion</aliadoNombre>
        <comercioId>12345</comercioId>
        <contrasena>CLAVE_COMERCIO_GENERADA</contrasena>
        <afiliacion>AFILIACION_EJEMPLO</afiliacion>
        <nombreComercial>Comercio Ejemplo</nombreComercial>
        <razonSocial>Comercio Demostracion</razonSocial>
        <rfc>RFC_FICTICIO</rfc>
        <usuarioPortal>USUARIO_PORTAL_GENERADO</usuarioPortal>
        <contrasenaPortal>CLAVE_PORTAL_GENERADA</contrasenaPortal>
        <comision_debito>2.50</comision_debito>
        <comision_credito>3.00</comision_credito>
        <comision_amex>3.50</comision_amex>
        <comision_internacional>4.00</comision_internacional>
        <comision_valeras>2.00</comision_valeras>
        <codigoRespuesta>0</codigoRespuesta>
        <ccErrorCode>0</ccErrorCode>
        <mensajeRespuesta>RESULTADO_ILUSTRATIVO</mensajeRespuesta>
      </afiliacionComercioResult>
    </afiliacionComercioResponse>

Todos los datos son ficticios.

Las credenciales mostradas son marcadores simbólicos y no representan usuarios ni contraseñas reales.

Interpretación de la respuesta

A4we3ntes de considerar completada una afiliación, el integrador debe validar:

1. El resultado comunicado por codigoRespuesta.

2. El código complementario ccErrorCode.

3. El contenido de mensajeRespuesta.

4. La presencia y validez del identificador comercioId, conforme a las reglas confirmadas por OEL.

5. La información y credenciales generadas, cuando corresponda.

No debe asumirse que la sola presencia de comercioId confirma una afiliación aprobada.

Flujo operativo de afiliación

El flujo recomendado de integración contempla las siguientes etapas.

Paso 1. Identificación del aliado

El sistema integrador obtiene las credenciales autorizadas del aliado y prepara la cabecera SOAP.

Paso 2. Captura de información del comercio

Se recopilan los datos comerciales, fiscales, bancarios, del representante legal y de los contactos correspondientes.

Paso 3. Configuración de condiciones comerciales

Se establecen las comisiones pactadas y se seleccionan los productos que se desean habilitar.

Paso 4. Validación previa

La aplicación verifica formatos, longitudes, datos obligatorios y consistencia de la información.

Paso 5. Envío de solicitud

El integrador invoca afiliacionComercio mediante SOAP.

Paso 6. Procesamiento en OEL

El servicio procesa la solicitud de acuerdo con las reglas internas de afiliación.

Paso 7. Recepción del resultado

La aplicación interpreta los códigos de respuesta y recupera los identificadores y credenciales que hayan sido generados.

Paso 8. Almacenamiento seguro

Cuando la afiliación se confirma, el integrador conserva los datos necesarios para operar el comercio y protege sus credenciales.

Paso 9. Envío de Documentación

Es importante mencionar que para cerrar el proceso de Alta es necesario enviar la documentación que soporte la veracidad de los datos registrados por el Aliado, ya que , mientras estos documentos no sean validados, aunque el comercio pueda transaccionar, el proceso de liquidación y compensación quedara bloqueado hasta concluir satisfactoriamente la verificación de su documentación.

Códigos de respuesta y errores

Los campos principales para evaluar el resultado son:

Deben confirmarse las respuestas correspondientes a los siguientes escenarios:

• Afiliación procesada satisfactoriamente.

• Credenciales del aliado inválidas.

• Comercio previamente registrado.

• RFC duplicado.

• Datos comerciales incompletos.

• Giro no reconocido.

• Tipo de afiliación no permitido.

• Información bancaria inválida.

• Comisiones fuera de los rangos autorizados.

• Producto no habilitado para el aliado.

• Error interno del servicio.

Estos escenarios son casos de prueba recomendados.

También deben contemplarse fallas de comunicación HTTP y errores SOAP.

Condiciones y limitaciones operativas

1. Autorización del aliado

La operación debe ejecutarse con credenciales válidas de un aliado autorizado para afiliar comercios.

La existencia del método en el WSDL no garantiza que cualquier aliado pueda registrar establecimientos o configurar cualquier condición comercial.

2. Alta de comercios

El método está destinado al registro de nuevos comercios.

3. Información fiscal y bancaria

El proceso requiere información fiscal y bancaria conforme a las condiciones funcionales de OEL.

La estructura del WSDL no garantiza que los datos sean válidos ante autoridades fiscales o instituciones financieras.

4. Comisiones

Las comisiones solicitadas deben corresponder a condiciones comerciales autorizadas.

5. Productos de pago

Los parámetros linkPago, tpv y eCommerce permiten indicar los productos solicitados.

6. Credenciales generadas

La respuesta puede incluir credenciales transaccionales y de portal.

Estas deben tratarse como secretos de seguridad y almacenarse mediante mecanismos adecuados.

7. Operaciones duplicadas

Ante una falla de comunicación, el integrador debe verificar si el comercio fue registrado antes de repetir la solicitud.

8. Activación del comercio

El método permite solicitar el alta y recibir información del comercio, una respuesta satisfactoria implica que el establecimiento puede comenzar inmediatamente a procesar pagos.

9. Validaciones externas

Ciertos datos comerciales pueden estar sujetos a validación en sitio.

10. Datos personales

La solicitud incluye datos personales, fiscales y bancarios por lo cual OEL aplica controles de acceso, protección de información, retención y tratamiento de datos acordes con las obligaciones aplicables.

Relación con otros métodos

El identificador comercioId generado durante la afiliación es uno de los datos fundamentales para relacionar al establecimiento con operaciones posteriores.