Integración a través del archivo XML

La integración es el proceso mediante el que se configura el envío de los datos sobre las acciones de conversión en tu sitio web al sistema de Admitad.

La acción de conversión puede ser una compra, un registro, una solicitud completada u otra acción que necesites, realizada por un usuario que ha sido llevado a tu sitio web por un afiliado de Admitad.

Información general: características y recomendaciones

Solo podrás iniciar la integración si en tu programa:
- ya se ha generado un enlace de seguimiento en la sección General Settings;
- ya se ha añadido una acción de conversión y se ha configurado la tarifa correspondiente en la Actions.

Si no tienes gestor, tienes que formar el enlace de seguimiento tú mismo (guía), y añadir al menos una acción y una tarifa (guía).
Si tienes un gestor personal, él/ella hará todos estos ajustes por ti.

La integración es una fase obligatoria para que puedas continuar con tu trabajo. Sin llevarla a cabo, es imposible poner en marcha un programa de afiliación en Admitad.
Para acelerar la integración, te recomendamos que involucres a tu propio especialista y le des estas instrucciones.

Una vez finalizada la integración, todos los datos sobre las acciones de conversión, como fecha de la acción, ID e importe del pedido, etc., se enviarán automáticamente a Admitad.

Qué es la integración a través de XML y cómo funciona

Qué es la integración a través de XML y cómo funciona La integración de archivos a través de XML es una forma de integrar tu sitio web con el sistema de Admitad, para lo cual debes crear en tu servidor un archivo XML con una estructura concreta, en el que se cargarán los datos sobre las acciones de los usuarios en tu sitio web.

Cómo funciona: mediante el enlace permanente al archivo XML, que se almacena en tu servidor, el servidor de Admitad Partner Network accederá a este archivo a intervalos predeterminados y cargará los datos de las nuevas acciones en las estadísticas de Admitad.

Para garantizar que el archivo XML solo pueda ser visualizado por los especialistas de Admitad Partner Network, puedes restringir el acceso a este archivo. Por ejemplo, con un nombre de usuario y una contraseña o especificando la dirección IP del servidor de Admitad Partner Network.

Te recomendamos que configures la carga de información al fichero XML con la mayor frecuencia posible, para que:

la información de las estadísticas de Admitad Partner Network se actualice de forma rápida;
los afiliados tengan la oportunidad de conseguir datos actualizados sobre la eficiencia de su trabajo.

Para consultar otros métodos de integración, lee el artículo Choosing an integration method.

Cómo efectuar la integración a través de un archivo XML

Para integrar tu página web mediante un archivo XML, sigue los pasos que te indicamos a continuación (más abajo encontrarás las instrucciones para cada uno de ellos):

configura el parámetro admitad_uid para que se inscriba en la cookie;
configura la deduplicación de las acciones de conversión;
prepara el archivo XML;
testea la integración personalizada.

Si además de la versión web de la página web, tienes la versión móvil de la página y/o un formulario de pedido rápido o pedido en 1 clic, entonces los datos sobre estos pedidos también deben incluirse en el archivo XML común.

Cómo configurar la grabación del valor del parámetro GET admitad_uid en las cookies

El valor de admitad_uid se registra cuando el usuario entra en la página web. Tienes que almacenarlo en las cookies durante el número de días indicado en tu contrato con Admitad (por defecto son 90 días).

Para hacerlo, usa un script para configurar el registro del valor del parámetro admitad_uid en cookies.

Con este fin, añade un código para rastrear el valor del parámetro admitad_uid en todas las páginas de tu página web, ya que el usuario puede entrar en cualquier página del sitio web.

La cookie o su duración no tienen que modificarse cuando se navega desde fuentes gratuitas como la búsqueda orgánica, etc. Admitad funciona según el modelo de atribución de Last Paid Click, en el que la acción tiene que atribuirse a la última fuente de tráfico de pago.

Debajo hay ejemplos para JavaScript y PHP script. Puedes usar este lenguaje de programación o cualquier otro.

Fíjate en los comentarios de los ejemplos de código. Los comentarios se añaden después de //.

if (isset($_GET['admitad_uid'])) {
$days = 90; // Número de días que se almacena la cookie
setcookie('_aid', $_GET['admitad_uid'], time() + 60 * 60 * 24 * $days, '/');
}

function get_admitad_uid() {
if (!isset($_COOKIE['_aid']) {
return null;
}

return $_COOKIE['_aid'];
}

<script type="text/javascript">
// Número de días que se almacena la cookie
var days_to_store = 90;

//Parámetros de creación de cookies con UID admitad
var uid_cookie_name = 'admitad_uid'; // Nombre de la cookie que almacena el UID
var uid_channel_name = 'admitad_uid'; // Función para conseguir la fuente del parámetro GET

function getParamFromUriAdmitad (get_param_name) {
   var pattern = get_param_name + '=([^&]+)';
   var re = new RegExp(pattern);
   return (re.exec(document.location.search) || [])[1] || '';
};

// función para guardar la fuente en la cookie con el nombre cookie_name
function setAdmitadCookie (param_name, cookie_name) {
   var param = getParamFromUriAdmitad(param_name);
   if (!param) { return; }
   var period = days_to_store * 60 * 60 * 24 * 1000;   // en segundos
   var expiresDate = new Date((period) + +new Date);
   var cookieString = cookie_name + '=' + param + '; path=/; expires=' + expiresDate.toGMTString();
   document.cookie = cookieString;
   document.cookie = cookieString + '; domain=.' + location.host;
};

// registro de cookie
setAdmitadCookie(uid_channel_name, uid_cookie_name);

</script>

Cómo configurar la deduplicación

La deduplicación es un método de tratamiento de datos que permite identificar correctamente la fuente de tráfico de pago para atribuirle un pedido y eliminar las acciones de conversión duplicadas, si las tuvieras.

La fuente de tráfico de pago es cualquier recurso de terceros al que tú pagas para llevar a los usuarios a tu sitio web en determinadas condiciones: por cada clic, visualización de anuncio, solicitud, registro o compra.
Por ejemplo, la publicidad de target y contextual, los posts de pago en los canales líderes de opinión, etc.

Configurar la deduplicación es un paso obligatorio para realizar la integración, incluso si actualmente solo estás trabajando con una fuente de tráfico de pago: la red de afiliación Admitad.

Al configurar la deduplicación, la información sobre la acción se pasa a Admitad según el modelo de atribución de Last Paid Click: si la última fuente de pago ha sido un afiliado de Admitad Partner Network, la acción se le contará a Admitad.

Puedes usar los siguientes métodos para configurar la deduplicación de las acciones de conversión:

Método 1

1. Configura la creación de la cookie en todas las páginas del sitio web que almacena la última fuente de tráfico de pago. Por defecto, Admitad pasa el parámetro utm_source=admitad.

2. Configura la transmisión de la información del pedido al archivo XML para los casos en los que la cookie de la fuente de tráfico almacene el valor del parámetro admitad.

Método 2

Si ha habido una transición con el parámetro GET de una fuente de tráfico distinta a la de Admitad, configura la eliminación de la cookie admitad_uid.

Cómo preparar un archivo XML para la integración

Prepara el archivo XML para la integración. Para hacerlo, añádale los parámetros obligatorios. También puedes añadir otros parámetros al archivo si es necesario.

Los parámetros tienen que incluir los datos sobre el pedido realizado por el usuario.
Ten en cuenta que tendrás que implementar la lógica de reemplazo de estos parámetros tú mismo.
Ejemplos de ficheros XML

El conjunto de parámetros obligatorios y opcionales depende del tipo de acción de conversión que esperas recibir del usuario.

Tipos de acción:

Sale — el usuario ha comprado un producto o ha realizado/pagado un pedido.
Lead — cliente potencial: el usuario ha rellenado el formulario y enviado sus datos: solicitud de servicio, registro, etc.

Haz clic en el tipo de acción que quieres para saber qué parámetros son necesarios.

Para ver qué acciones están disponibles en tu programa de afiliación, ve a la sección Actions de tu cuenta personal.

Parámetros para la acción Sale

En la columna Parameter name, los parámetros principales están marcados en negrita, y los alias - nombres adicionales para el parámetro principal - están marcados en cursiva.
Es decir, en los ajustes puedes especificar el parámetro alternativo, no el principal, y el sistema de Admitad Partner Network también podrá procesarlo.

Nombre del parámetro	Descripción	Tipo	Comentario
uid, key	Identificador de Admitad Partner Network	Línea	El valor generado que se pasa al parámetro `admitad_uid` en el momento en que el usuario entra en el sitio web. Si en tu programa permites la publicidad contextual, cuando los usuarios hagan clic en los anuncios contextuales de los afiliados de Google Ads, en lugar del valor uid en el parámetro `admitad_uid` se introducirá el valor gclid generado por Google. Para que el seguimiento de acciones funcione correctamente, tu servidor tiene que recibir y transmitir el valor completo del parámetro gclid. Más información sobre la longitud del parámetro gclid Ejemplo:CjwKCAjwmJeYBhAwEiw AXlg0AfVR-r9TC-9ecMaEOJO7 rbkmyt6j9QNyDFKqZ9YQTF dWxO2lQxvhPBoCO1sQAvD_BwE
order_id, oid	Tu identificador interno de pedido	Línea, 1-100 caracteres	Tu ID interno de pedido. ¡Importante! Asegúrate de poder encontrar el pedido con este ID en tu sistema CRM, ya que en el futuro se usará para la verificación.
action_code, ac, product,product_code	Código de la acción de conversión	Número entero	Variable — aquí tienes que introducir el código de la acción correspondiente en los ajustes de tu programa. Cómo encontrar el código de la acción
tariff_code, tc	Código de la tarifa	Número entero	Variable — aquí tienes que introducir el código de la tarifa correspondiente en los ajustes de tu programa. Cómo encontrar el código de la tarifa
currency_code	Código de la divisa	Línea, 3 caracteres	Se especifica en la norma ISO 4217. Solo se admiten valores alfabéticos. Ejemplo: RUB, EUR, USD.
position_id	Número del producto en la cesta	Número entero	Variable con un valor que varía de 1 a N, donde N = position_count.
position_count	Cantidad de productos en la cesta	Número entero	Es una variable con valor N, que depende del contenido de la cesta del usuario.
quantity	Cantidad de artículos del producto	Número entero
payment_type	Tipo de acción de conversión	Línea, 4 caracteres	En una constante, el valor es "sale".
product_id	Tu identificador interno de pedido	Línea, 1-100 caracteres	Es el ID del producto, que tiene que coincidir con el ID del feed del producto si estás usando esta herramienta. Más sobre el feed de productos
price	Precio de un producto de la cesta	Número entero o fraccional	Es obligatorio usar el punto como separador de las partes enteras y las fracciones. Ejemplo: correcto — 2.65; incorrecto — 2.65.
datetime_action, now	Fecha y hora de la acción	Línea, 19 caracteres	Formato: AAAA-MM-DD hh:mm:ss. Ejemplo: 2022-08-25 00:00:00

Si quieres, puedes añadir algún parámetro más.

Nombre del parámetro

Descripción

Tipo

Comentario

promocode

Código de descuento personalizado

Línea, 255 caracteres

Usa este parámetro si tienes que configurar la transmisión de los códigos de descuento personalizados.

tracking

Información adicional del pedido

Línea, 255 caracteres

Usa este parámetro para pasar la información adicional a los especialistas de Admitad Partner Network durante la fase de verificación.

Parámetros para la acción Lead

Nombre de parámetro	Descripción	Tipo	Comentario
uid, key	Identificador de Admitad Partner Network	Línea	El valor generado que se pasa al parámetro `admitad_uid` en el momento en que el usuario entra en el sitio web. Si en tu programa permites la publicidad contextual, cuando los usuarios hagan clic en los anuncios contextuales de los afiliados de Google Ads, en lugar del valor uid en el parámetro `admitad_uid` se introducirá el valor gclid generado por Google. Para que el seguimiento de acciones funcione correctamente, tu servidor tiene que recibir y transmitir el valor completo del parámetro gclid. Más información sobre la longitud del parámetro gclid Ejemplo: CjwKCAjwmJeYBhAwEiwAXlg0AfVR -r9TC-9ecMaEOJO7rbkmyt6 j9QNyDFKqZ9YQTFdWxO2l QxvhPBoCO1sQAvD_BwE
order_id, oid	Tu identificador interno de pedido	Línea, 1-100 caracteres	Tu ID interno de pedido. ¡Importante! Asegúrate de poder encontrar el pedido con este ID en tu sistema CRM, ya que en el futuro se usará para la verificación. Si para tu programa de afiliación tienes que configurar varias acciones de conversión, pero el ID de usuario no se cambia, añade un prefijo al ID del pedido. Más información
action_code, ac, product, product_code	Código de la acción de conversión	Número entero	Variable — aquí tienes que introducir el código de la acción correspondiente en los ajustes de tu programa. Cómo encontrar el código de la acción
tariff_code, tc	Código de la tarifa	Número entero	Variable — aquí tienes que introducir el código de la tarifa correspondiente en los ajustes de tu programa. Cómo encontrar el código de la tarifa
datetime_action, now	Fecha y hora de la acción	Línea, 19 caracteres	Formato: AAAA-MM-DD hh:mm:ss. Ejemplo: 2022-08-25 00:00:00

Si quieres, puedes añadir algún parámetro más.

Nombre de parámetro	Descripción	Tipo	Comentario
currency_code	Código de la divisa	Línea, 3 caracteres	Se especifica en la norma ISO 4217. Solo se admiten valores alfabéticos. Ejemplo: RUB, EUR, USD.
position_id	Número del producto en la cesta	Número entero	Es la variable con un valor que varía de 1 a N, donde N = position_count.
position_count	Cantidad de productos en la cesta	Número entero	Es una variable con valor N, que depende del contenido de la cesta del usuario.
quantity	Cantidad de artículos del producto	Número entero
payment_type	Tipo de acción de conversión	Línea, 4 caracteres	En una constante, el valor es "lead".
product_id	Tu identificador interno de producto	Línea, 1-100 caracteres	Es el ID del producto, que tiene que coincidir con el ID del feed del producto si estás usando esta herramienta. Más sobre el feed de productos
price	Precio de un producto de la cesta	Número entero o fraccional	Es obligatorio usar el punto como separador de las partes enteras y las fracciones. Ejemplo: correcto — 2.65; incorrecto — 2.65.
promocode	Código de descuento personalizado	Línea, 255 caracteres	Usa esta opción si tienes que configurar la transmisión de los códigos de descuento personalizados. Ver más
tracking	Información adicional del pedido	Línea, 255 caracteres	Usa este parámetro para pasar la información adicional a los especialistas de Admitad Partner Network durante la fase de verificación.

Ejemplos de archivos XML

En esta sección te mostramos algunos ejemplos de archivos XML en función del tipo de acción de conversión del usuario.

Haz clic en el ejemplo para verlo.

Abajo se muestra el ejemplo de una cesta de compra con tres productos.

Producto	Nombre del producto	Precio	Número de productos	Importe del producto
1	Motosierra	2000	3	6000
2	Lámpara de mesa	1790	2	3580
3	Máquina de soldar	4050	1	4050
			Total	13 630

Cada uno de los productos tiene que ir insertado en una etiqueta distinta<payment>.
En el ejemplo siguiente, los valores de los parámetros indicados se modifican dentro de las <payment>etiquetas :

cantidad (quantity);
precio (price);
número de serie del producto en la cesta (position_id);
código de la acción de conversión (action_code);
código de tarifa (tariff_code);
identificador interno del producto (product_id).

<?xml version="1.0" encoding="UTF-8"?>
<payment_list version="2">
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <product_id>125</product_id>
        <tracking>Herramientas portátiles - motosierra</tracking>
        <quantity>3</quantity>
        <currency_code>RUB</currency_code>
        <price>2000</price>
        <position_id>1</position_id>
        <payment_type>sale</payment_type>
        <action_code>1</action_code>
        <tariff_code>1</tariff_code>
        <position_count>3</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <product_id>57</product_id>
        <tracking>Lámpara de mesa</tracking>
        <quantity>2</quantity>
        <currency_code>RUB</currency_code>
        <price>1790</price>
        <position_id>2</position_id>
        <payment_type>sale</payment_type>
        <action_code>2</action_code>
        <tariff_code>2</tariff_code>
        <position_count>3</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <product_id>71</product_id>
        <tracking>Máquina de soldar</tracking>
        <quantity>1</quantity>
        <currency_code>RUB</currency_code>
        <price>4050</price>
        <position_id>3</position_id>
        <payment_type>sale</payment_type>
        <action_code>2</action_code>
        <tariff_code>1</tariff_code>
        <position_count>3</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
</payment_list>

Debajo se muestra el ejemplo de una acción de conversión para el sector bancario (tipo de acción — lead).

Producto	Nombre del producto	Precio	Número de productos	Importe del producto
1	Registro	-	-	-

<?xml version="1.0" encoding="UTF-8"?>
<payment_list version="2">
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <payment_type>lead</payment_type>
        <action_code>1</action_code>
        <tariff_code>1</tariff_code>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
</payment_list>

Cómo configurar el envío de información sobre los códigos de descuento personalizados

Los códigos de descuento personalizados son unos códigos de descuento que llevan una palabra clave única a través de la que se realiza el seguimiento de las acciones de conversión. Estos códigos promocionales se asignan a unos afiliados concretos. Más información sobre los códigos de descuento personalizados

Si tienes pensado trabajar con los códigos de descuento personalizados:

1. Asegúrate de en el formulario de pedido en el sitio web aparezca el campo Promo code.

2. Ingresa el código de descuento único del formulario de compra en el parámetro promocode.

3. Comprueba que todos los pedidos con el código de descuento único se remitan a Admitad Partner Network. Para hacerlo, testea la solicitud.

Tienes que pasar la información del pedido a Admitad Partner Network si el pedido tiene:

tanto admitad_uid, como el código de descuento personalizado;
solo el código de descuento personalizado;
solo admitad_uid.

La información sobre el pedido con el código de descuento personalizado no debe difundirse a través de otros canales.

Cómo testear un archivo XML después de configurarlo

1. Una vez que hayas creado un archivo XML con la estructura descrita anteriormente y hayas configurado el envío de datos sobre las acciones del usuario a este archivo, obtén el enlace para hacer pruebas en la sección Integration.

1.1 En tu cuenta personal, ve a la sección Integration (menú → Program → Integration).

1.2 Después, haz clic en Next y, en la página Integration methods, cambia a la pestaña Custom integration.

1.3 En la pestaña Custom integration, selecciona XML y haz clic en Next.

1.4 Baja por la página hasta el bloque Integration testing y copia el enlace de prueba del campo correspondiente.

2. Haz los pedidos de prueba y asegúrate de que:

El valor del parámetro admitad_uid se procese en todas las páginas del sitio web y se almacene en la cookie.
La vida útil de la cookie con admitad_uid corresponda al tiempo indicado en el contrato o, si no hay contrato, a un periodo de 90 días.
La cookie no se borre cuando el usuario pase por la búsqueda orgánica.
Para comprobarlo, cuando hagas el pedido de prueba:
- 1. Primero, haz clic en el enlace de afiliación de prueba.
- 2. Después, haz clic en el enlace orgánico.
- 3. Haz el pedido y comprueba que aparece en el sistema.
El envío de los datos al archivo XML funciona para todas las acciones y tarifas de conversión de tu programa de afiliación.
Para comprobar que el seguimiento funcione correctamente en cada caso, haz varios pedidos.
Para cada artículo de la cesta de compra se crea una etiqueta <payment> diferente.
Si el número de pedido y el importe se transmiten correctamente, el precio de cada producto debe transmitirse sin los códigos de descuento ni los gastos de envío, es decir, solo el importe que el usuario ha pagado por el producto.

3. Después, comprueba los demás ajustes si los estás usando.

Si usas los códigos de descuento de personalizados, haz el pedido de prueba de esta forma:
- 1. Entra en tu sitio web a través de un enlace directo sin parámetros.
- 2. Al pagar, usa el código de descuento personalizado y asegúrate de que el pedido se atribuye a Admitad Partner Network.
Si usas otras fuentes de pago, haz el pedido de prueba de esta forma:
- 1. Haz clic en el enlace afiliado desde otra fuente.
- 2. Sigue el enlace afiliado de Admitad Partner Network.
- 3. Realiza el pedido y asegúrate de que se cuente para Admitad Partner Network.
Si tienes:
- versión móvil del sitio web,
- formulario de pedido rápido
- y/o formulario de pedido en 1 clic,
comprueba que el seguimiento esté configurado para todas las plataformas y métodos de compra.

4. Una vez realizados los pedidos de prueba, tienes que informar a los especialistas de Admitad Partner Network de cómo acceder al archivo XML con la información sobre estos pedidos. Los especialistas cargarán y procesarán el archivo en un plazo de 3-4 días.

5. Si el seguimiento se ha configurado correctamente, las acciones aparecerán en las estadísticas de Admitad Partner Network dentro de una hora.

Para comprobarlo, ve a tu cuenta personal de Admitad → Reports → On actions y asegúrate de que las estadísticas muestran correctamente la acción de conversión y sus datos:

el nombre de la acción de conversión en la columna Rate de las estadísticas coincide con el nombre de esta acción en la sección Actions;
El ID de la acción en la columna Order ID coincide con el ID de la acción en tu sistema;
el importe del pedido en Admitad coincide con el importe del pedido de prueba.

Informa al técnico de Admitad Partner Network de que las pruebas se han realizado con éxito. Después de eso, el programa se pondrá en preparación para el lanzamiento.

6. Si la acción no ha aparecido en las estadísticas en una hora, asegúrate de que:

has enviado el enlace correcto del archivo al especialista técnico de Admitad Partner Network;
has indicado correctamente todos los parámetros obligatorios;
has utilizado correctamente las mayúsculas en las etiquetas.

Para detectar el error, ve a la sección Request log (Integration → Integration test). El texto sobre el error se muestra en el campo Result.

Corrige el error y vuelve a realizar la prueba. Más sobre la sección Request log

FAQ

¿Dónde puedo encontrar el valor de action_code?

1. En tu cuenta personal, ve a la sección Integration (menú → Program → Integration).

2. Después, haz clic en Next y, en la página Integration methods, cambia a la pestaña Custom integration.

3. En la pestaña Custom integration, selecciona XML y haz clic en Next.

4. En la tabla, en la columna Action, encuentra la acción con el código que necesitas.
El valor del parámetro action_code aparece en la fila con esta acción en la columna Action code (bloque Integration setup: unique parameter values for your program).

¿Dónde puedo encontrar el valor del parámetro tariff_code?

1. En tu cuenta personal, ve a la sección Integration (menú → Program → Integration).

2. Después, haz clic en Next y, en la página Integration methods, cambia a la pestaña Custom integration.

3. En la pestaña Custom integration, selecciona XML y haz clic en Next.

4. En la segunda tabla de la página, en la columna Rate, busca la tarifa para la cual necesitas el código.

El valor del parámetro tariff_code aparece en la fila con esta tarifa en la columna Rate code (bloque Integration setup: unique parameter values for your program).

¿Cómo introducir el parámetro order_id en varias acciones si el número de pedido es el ID de usuario?

En algunos programas de afiliación, por ejemplo, en los de la categoría Online Games, en las estadísticas suele usarse el ID del usuario en el sistema en vez del número de pedido.

Por lo tanto, si tienes que añadir varias acciones de conversión para este tipo de programas, tienes que añadir un prefijo al ID del pedido (parámetro order_id). En este caso, hay que usar los prefijos, con el nombre de los que quedará claro a qué acción de conversión te estás refiriendo.

Acción de conversión Parámetro y su valor Prefijo utilizado

Registro order_id=reg_123123 reg_

Conseguir el nivel 5 order_id=lvl5_123123 lvl5_

Volver a los parámetros obligatorios

Acción de conversión	Parámetro y su valor	Prefijo utilizado
Registro	order_id=reg_123123	reg_
Conseguir el nivel 5	order_id=lvl5_123123	lvl5_