Integração com um arquivo XML

A integração é um processo de configuração do envio de dados de ações em seu site ao sistema Admitad.

Uma ação é uma compra, registro, inscrição concluída ou outra ação que você precisa executar por um usuário indicado pelo afiliado da Admitad ao seu site.

Informações gerais: características e recomendações

Você pode iniciar a integração somente se o seu programa:
- já tiver um link de rastreamento gerado na seção General Settings;
- já tiver uma ação adicionada e a taxa correspondente configurada na seção Actions.

Se você não tiver um gestor, crie um link de rastreamento por conta própria (instruções) e adicione pelo menos uma ação e uma taxa (instruções).
Se você tiver um gestor pessoal, ele configurará tudo para você.

A integração é um passo obrigatório para continuar trabalhando. Sem ela, você não pode lançar um programa afiliado na Admitad.
Para acelerar a integração, recomendamos que você peça ajuda ao seu próprio especialista técnico e passe essas instruções para ele.

Quando a integração for concluída, todos os dados de ações (a data da ação, o ID do pedido, seu valor, entre outros) serão enviados para a Admitad automaticamente.

O que é uma integração com um arquivo XML e como funciona

A integração com um arquivo XML é uma forma de integrar seu site ao sistema Admitad. Você precisa criar um arquivo XML de uma determinada estrutura para seu site em seu servidor, onde serão carregados os dados de ações de usuários de seu site.

Como funciona: usando o link permanente para um arquivo XML compartilhado por você, que está armazenado em seu servidor, o servidor Admitad Partner Network acessa esse arquivo com uma frequência pré-determinada e carrega dados de novas ações nos relatórios da Admitad.

Você pode restringir o acesso ao arquivo XML para garantir que apenas os especialistas da Admitad Partner Network possam visualizá-lo. Por exemplo, usando um login e senha ou especificando o endereço IP do servidor Admitad Partner Network.

Recomenda-se configurar o upload de informações para um arquivo XML sempre que possível para:

os dados nos relatórios da Admitad Partner Network serem atualizados prontamente;
os afiliados terem a oportunidade de receber dados atualizados sobre a eficácia do seu trabalho.

Para outras formas de integração, consulte o artigo "Escolhendo uma forma de integração".

Como integrar com um arquivo XML

Para integrar seu site usando um arquivo XML, siga estes passos (confira as instruções para cada um deles abaixo):

configure a gravação do valor do parâmetro admitad_uid no cookie;
configure a deduplicação de ações;
prepare um arquivo XML;
teste a integração configurada.

Se, além da versão web do site, você tiver uma versão móvel e/ou um formulário de pedido rápido ou de compra com um clique, os dados desses pedidos também devem ser incluídos no arquivo XML geral.

Como configurar a gravação do valor do parâmetro GET admitad_uid em cookies

O valor admitad_uid é registrado quando o usuário acessa o site. Você precisa salvá-lo nos cookies pelo número de dias especificado no acordo com a Admitad (90 dias por padrão).

Para isso, use o script para configurar a gravação do valor do parâmetro admitad_uid nos cookies.

Para isso, adicione o código de rastreamento do valor do parâmetro admitad_uid a todas as páginas do seu site, pois o usuário pode seguir o link para qualquer página do site.

Um cookie ou seu tempo de vida não devem mudar ao acessar o site de fontes gratuitas, como busca orgânica, pois a Admitad trabalha com o modelo de atribuição Last Paid Click, o que significa que a ação é atribuída à última fonte de tráfego paga.

Abaixo estão exemplos de scripts JavaScript e PHP. Você pode usar essas ou qualquer outra linguagem de programação.

Preste atenção aos comentários nos exemplos de código. Os comentários são adicionados após o símbolo //.

if (isset($_GET['admitad_uid'])) {
$days = 90; // Número de dias de armazenamento de 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 dias de armazenamento de cookie
var days_to_store = 90;

// opções de criação de cookie com UID Admitad
var uid_cookie_name = 'admitad_uid'; // nome do cookie com o UID armazenado
var uid_channel_name = 'admitad_uid'; // função para obter uma fonte do 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] || '';
};

// função para gravar a fonte no cookie com o nome 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;   // em 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;
};

// gravação do cookie
setAdmitadCookie(uid_channel_name, uid_cookie_name);

</script>

Como configurar a deduplicação

A deduplicação é um método de processamento de dados que permite identificar corretamente uma fonte de tráfego paga para atribuir um pedido a ela, bem como eliminar ações duplicadas, se houver.

Uma fonte de tráfego paga é qualquer recurso de terceiros ao qual você paga por atrair usuários ao seu site sob certas condições: por cada acesso ao site, visualização de anúncios, solicitação, cadastro ou compra.
Por exemplo, publicidade direcionada e contextual, postagens pagas em canais de influenciadores, etc.

Configurar a deduplicação é um passo obrigatório para a integração, mesmo se você estiver trabalhando com apenas uma fonte de tráfego paga: a rede de afiliação Admitad.

Ao configurar a deduplicação, os dados de ações são transferidos à Admitad de acordo com o modelo de atribuição Last Paid Click: se a última fonte paga for um afiliado da Admitad Partner Network, a ação deve ser atribuída à Admitad.

Para configurar a deduplicação de ações, você pode usar os seguintes métodos:

Método 1

1. Configure a criação de cookie em todas as páginas do site que armazena a última fonte de tráfego paga. Por padrão, o Admitad utiliza o parâmetro utm_source=admitad.

2. Configure a transferência de dados do pedido para um arquivo XML para os casos em que o cookie com a fonte de tráfego armazena o valor do parâmetro admitad.

Método 2

Em caso de transição com um parâmetro GET da fonte de tráfego diferente da Admitad, configure a exclusão do cookie admitad_uid.

Como preparar um arquivo XML para integração

Prepare um arquivo XML para integração. Para isso, adicione os parâmetros necessários a ele. Se necessário, você pode adicionar parâmetros adicionais ao arquivo.

Os dados do pedido feito pelo usuário devem ser substituídos nos parâmetros.
Importante! Você mesmo precisa implementar a lógica para substituir esses parâmetros.
Exemplos de arquivos XML

O conjunto de parâmetros necessários e adicionais para configuração depende do tipo de ação que você espera receber do usuário.

Tipos de ação:

Sale: o usuário comprou um produto ou fez/pagou um pedido.
Lead: o usuário preencheu um formulário e enviou seus dados: solicitação de serviço, cadastro, etc.

Clique no tipo de ação desejado para ver quais parâmetros são necessários.

Para verificar quais ações estão disponíveis em seu programa afiliado, vá para a seção Actions and rewards em sua conta pessoal.

Parâmetros para a ação Sale

Na coluna Nome de parâmetro, os parâmetros principais estão em negrito, e os aliases em itálico são nomes adicionais para o parâmetro principal.
Dessa forma, você pode especificar nas configurações não o parâmetro principal, mas seu alias, e o sistema Admitad Partner Network também poderá processá-lo.

Nome de parâmetro	Descrição	Tipo	Observação
uid, key	ID Admitad Partner Network	String	Valor gerado que é transmitido no parâmetro `admitad_uid` quando o usuário acessa o site. Se você permitir publicidade contextual em seu programa, quando os usuários clicarem nos anúncios contextuais do Google Ads de afiliados, em vez do valor uid, o gclid gerado pelo Google será atribuído ao parâmetro `admitad_uid`. Para que o rastreamento de ações funcione corretamente, seu servidor deve ser capaz de receber e transmitir o valor inteiro do parâmetro gclid. Saiba mais sobre o comprimento do parâmetro gclid Exemplo:CjwKCAjwmJeYBhAwEiw AXlg0AfVR-r9TC-9ecMaEOJO7 rbkmyt6j9QNyDFKqZ9YQTF dWxO2lQxvhPBoCO1sQAvD_BwE
order_id, oid	Seu ID de pedido interno	Número de caracteres: 1−100	Seu ID de pedido interno. Importante! Certifique-se de encontrar o pedido por este ID em seu sistema CRM, pois ele será usado no futuro para verificação.
action_code, ac, product,product_code	Código de ação	Número inteiro	Variável: o código da ação correspondente das configurações do seu programa deve ser substituído aqui. Como encontrar o código de uma ação
tariff_code, tc	Código de taxa	Número inteiro	Variável: o código da taxa correspondente das configurações do seu programa deve ser substituído aqui. Como encontrar o código de taxa
currency_code	Código de moeda	Número de caracteres: 3	Definido na ISO 4217. Somente valores compostos exclusivamente de letras são válidos. Exemplo: BRL, EUR, USD.
position_id	Posição do produto no carrinho	Número inteiro	Uma variável cujo valor muda de 1 para N, onde N = position_count.
position_count	Quantidade de itens no carrinho	Número inteiro	Uma variável com valor N, que depende do conteúdo do carrinho montado pelo usuário.
quantity	Número de unidades de produto em uma posição	Número inteiro
payment_type	Tipo de ação	Número de caracteres: 4	Valor, constante: "sale".
product_id	Seu ID de produto interno	Número de caracteres: 1−100	O ID do produto, que deve corresponder ao ID do feed de produtos, se você estiver usando esta ferramenta. Saiba mais sobre o feed de produtos
price	O custo de um produto no carrinho	Número inteiro ou fracionário	Deve ser usado um ponto como separador entre o inteiro e a parte fracionária. Exemplo: correto: 2.65; incorreto: 2,65.
datetime_action, now	Data e hora da ação	Número de caracteres: 19	Formato: AAAA-MM-DD hh:mm:ss. Exemplo: 2022-08-25 00:00:00

Você pode adicionar parâmetros adicionais, se desejar.

Nome de parâmetro

Descrição

Tipo

Observação

promocode

Código de promoção personalizado

Número de caracteres: 255

Use esta opção se precisar configurar a transmissão de códigos de promoção personalizados.

Saiba mais

tracking

Informações adicionais do pedido

Número de caracteres: 255

Use este parâmetro para compartilhar informações adicionais com os especialistas da Admitad Partner Network na etapa de verificação.

Parâmetros para a ação Lead

Na coluna Parameter name, os parâmetros principais estão em negrito, e os aliases em itálico são nomes adicionais para o parâmetro principal.
Dessa forma, você pode especificar nas configurações não o parâmetro principal, mas seu alias, e o sistema Admitad Partner Network também poderá processá-lo.

Nome de parâmetro	Descrição	Tipo	Observação
uid, key	ID Admitad Partner Network	String	Valor gerado que é transmitido no parâmetro `admitad_uid` quando o usuário faz login no site. Se você permitir publicidade contextual em seu programa, quando os usuários clicarem nos anúncios contextuais do Google Ads de afiliados, em vez do valor uid, o gclid gerado pelo Google será atribuído ao parâmetro `admitad_uid`. Para que o rastreamento de ações funcione corretamente, seu servidor deve ser capaz de receber e transmitir o valor inteiro do parâmetro gclid. Saiba mais sobre o comprimento do parâmetro gclid Exemplo: CjwKCAjwmJeYBhAwEiwAXlg0AfVR -r9TC-9ecMaEOJO7rbkmyt6 j9QNyDFKqZ9YQTFdWxO2l QxvhPBoCO1sQAvD_BwE
order_id, oid	Seu ID de pedido interno	Número de caracteres: 1−100	Seu ID de pedido interno. Importante! Certifique-se de encontrar o pedido por este ID em seu sistema CRM, pois ele será usado no futuro para verificação. Se você precisar configurar várias ações para seu programa afiliado, mas o ID de usuário não mudar, adicione um prefixo ao ID do pedido. Saiba mais
action_code, ac, product, product_code	Código de ação	Número inteiro	Variável: o código da ação correspondente das configurações do seu programa deve ser substituído aqui. Como encontrar o código de uma ação
tariff_code, tc	Código de taxa	Número inteiro	Variável: o código da taxa correspondente das configurações do seu programa deve ser substituído aqui. Como encontrar o código de taxa
datetime_action, now	Data e hora da ação	Número de caracteres: 19	Formato: AAAA-MM-DD hh:mm:ss. Exemplo: 2022-08-25 00:00:00

Você pode adicionar parâmetros adicionais, se desejar.

Nome de parâmetro	Descrição	Tipo	Observação
currency_code	Código de moeda	Número de caracteres: 3	Definido na ISO 4217. Somente valores compostos exclusivamente de letras são válidos. Exemplo: BRL, EUR, USD.
position_id	Posição do produto no carrinho	Número inteiro	Uma variável cujo valor muda de 1 para N, onde N = position_count.
position_count	Quantidade de itens no carrinho	Número inteiro	Uma variável com valor N, que depende do conteúdo do carrinho montado pelo usuário.
quantity	Número de unidades de produto em uma posição	Número inteiro
payment_type	Tipo de ação	Número de caracteres: 4	Valor, constante: "lead".
product_id	Seu ID de produto interno	Número de caracteres: 1−100	O ID do produto, que deve corresponder ao ID do feed de produtos, se você estiver usando esta ferramenta. Saiba mais sobre o feed de produtos
price	O custo de um produto no carrinho	Número inteiro ou fracionário	Deve ser usado um ponto como separador entre o inteiro e a parte fracionária. Exemplo: correto: 2.65; incorreto: 2,65.
promocode	Código de promoção personalizado	Número de caracteres: 255	Use esta opção se precisar configurar a transmissão de códigos de promoção personalizados. Saiba mais
tracking	Informações adicionais do pedido	Número de caracteres: 255	Use este parâmetro para compartilhar informações adicionais com os especialistas da Admitad Partner Network na etapa de verificação.

Exemplos de arquivos XML

Esta seção apresenta exemplos de arquivos XML dependendo do tipo de ação do usuário.

Para visualizar o exemplo desejado, clique nele.

Abaixo está um exemplo de um carrinho com três itens.

Posição do produto	Nome do produto	Preço	Quantidade do produto	Valor total dos produtos por posição
1	Motosserra	650	3	1.950
2	Luminária de mesa	90	2	260
3	Máquina de solda	450	1	450
			Total	2.660

Cada item deve ser colocado em uma tag separada <payment>.
No exemplo abaixo, dentro da tag <payment>, são alterados os valores dos seguintes parâmetros:

quantidade (quantity);
preço (price);
número do produto no carrinho (position_id);
código de ação (action_code);
código de taxa (tariff_code);
ID do produto interno (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>Ferramentas manuais - Motosserra</tracking>
        <quantity>3</quantity>
        <currency_code>BRL</currency_code>
        <price>650</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>Luminária de mesa</tracking>
        <quantity>2</quantity>
        <currency_code>BRL</currency_code>
        <price>90</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 solda</tracking>
        <quantity>1</quantity>
        <currency_code>BRL</currency_code>
        <price>450</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>

Abaixo está um exemplo de uma ação para o setor bancário (tipo de ação: lead).

Posição do produto	Nome do produto	Preço	Quantidade do produto	Valor total dos itens por posição
1	Cadastro	-	-	-

<?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>

Como configurar o envio de informações para códigos de promoção personalizados

Os códigos de promoção personalizados são códigos de promoção que contêm uma palavra-chave exclusiva pela qual as ações são rastreadas. Esses códigos de promoção são atribuídos a afiliados específicos. Saiba mais sobre códigos de promoção personalizados

Se você planeja trabalhar com códigos de promoção personalizados:

1. Certifique-se de que o campo Promo code esteja presente no formulário de pedido no site.

2. Insira um código de promoção exclusivo do formulário de pedido no parâmetro promocode.

3. Certifique-se de que todos os pedidos com esse código de promoção exclusivo sejam enviados para a Admitad Partner Network. Para isso, teste a requisição.

Você precisa enviar dados do pedido para a Admitad Partner Network se a requisição tiver:

o parâmetro admitad_uid e também um código de promoção personalizado;
apenas um código de promoção personalizado;
apenas o parâmetro admitad_uid.

Os dados do pedido com um código de promoção personalizado não devem ser enviados para outros canais.

Como testar o arquivo XML configurado

1. Depois de criar um arquivo XML com a estrutura descrita acima e configurar o envio de dados de ações de usuários, você receberá um link para teste na seção Integration.

1.1 Em sua conta pessoal, vá para a seção Integration (Program → Integration).

1.2 Em seguida, clique em Next e, na página Integration methods, mude para a guia Custom integration.

1.3 Na guia Custom integration, selecione XML e clique em Next.

1.4 Deslize para baixo até o bloco Integration testing e copie o link de teste do campo correspondente.

2. Faça pedidos de teste e certifique-se de que:

O valor do parâmetro admitad_uid é processado em todas as páginas do site e armazenado em um cookie.
O tempo de vida do cookie com admitad_uid corresponde ao período especificado no contrato ou, se não houver contrato, ao período de 90 dias.
O cookie não é excluído quando o usuário navega pela busca orgânica.
Para verificar isso, ao fazer um pedido de teste:
- 1. Primeiro, siga o link de afiliado de teste.
- 2. Depois, siga o link orgânico.
- 3. Faça um pedido e verifique se ele será exibido no sistema.
O envio de dados para um arquivo XML funciona para todas as ações e taxas do seu programa afiliado.
Para isso, faça vários pedidos para verificar se o rastreamento funciona corretamente em cada caso.
Cada item no carrinho tem sua própria tag <payment>.
O número e o valor do pedido são transferidos corretamente. O preço de cada produto deve ser transmitido descontando códigos de promoção e entrega, ou seja, o valor exato que o usuário pagou pelo produto.

3. Em seguida, verifique outras configurações se houver.

Se você usar códigos de promoção personalizados, faça um pedido de teste da seguinte maneira:
- 1. Acesse seu site por meio de um link direto sem parâmetros.
- 2. Use um código de promoção personalizado ao fazer um pedido e certifique-se de que o pedido seja atribuído à Admitad Partner Network.
Se você usar outras fontes pagas, faça um pedido de teste de acordo com o seguinte esquema:
- 1. Siga um link de afiliado de outra fonte.
- 2. Siga o link de afiliado da Admitad Partner Network.
- 3. Faça um pedido e certifique-se de que ele seja atribuído à Admitad Partner Network.
Se você tem:
- a versão móvel do site,
- o formulário de pedido rápido
- e/ou o formulário de compra com um clique,
verifique se o rastreamento está configurado para todas as plataformas e métodos de compra.

4. Depois de fazer pedidos de teste, informe os especialistas da Admitad Partner Network sobre como obter acesso ao arquivo XML com os dados desses pedidos. Eles vão fazer upload e processar o arquivo dentro de 3–4 dias.

5. Se o rastreamento estiver configurado corretamente, dentro de uma hora, as ações aparecerão nos relatórios da Admitad Partner Network.

Para verificar, acesse sua conta pessoal da Admitad → Reports → On actions e certifique-se de que a ação e os dados correspondentes sejam exibidos corretamente nos relatórios:

o nome da ação na coluna Rate nos relatórios corresponde ao nome da mesma na seção Actions;
o ID da ação na coluna Order ID corresponde ao ID da ação em seu sistema;
o valor do pedido na Admitad corresponde ao valor do pedido de teste.

Notifique o especialista técnico da Admitad Partner Network que o teste foi bem-sucedido. Depois disso, começará a preparação do programa para o lançamento.

6. Se a ação não aparecer nos relatórios dentro de uma hora, confira se:

o link correto do arquivo foi enviado para o especialista técnico da Admitad Partner Network;
foram especificados corretamente todos os parâmetros necessários;
a caixa correta foi usada nas tags.

Para identificar um erro, vá para a seção Request log (Program → Integration → Integration test). O texto do erro será indicado no campo Result.

Corrija o erro e faça o teste novamente. Saiba mais sobre a seção Registro de solicitações

Perguntas Frequentes

Onde encontrar o valor do parâmetro action_code?

1. Em sua conta pessoal, vá para a seção Integration (Program → Integration).

2. Em seguida, clique em Next e, na página Integration methods, mude para a guia Custom integration.

3. Na guia Custom integration, selecione XML e clique em Next.

4. Na tabela da página, na coluna Action, encontre aquela cujo código você precisa.
O valor do parâmetro action_code é apresentado na linha com esta ação na coluna Action code (bloco Integration setup: unique parameter values for your program).

Onde encontrar o valor do parâmetro tariff_code?

1. Em sua conta pessoal, vá para a seção Integration (Program → Integration).

2. Em seguida, clique em Next e, na página Integration methods, mude para a guia Custom integration.

3. Na guia Custom integration, selecione XML e clique em Next.

4. Na segunda tabela da página, na coluna Rate, encontre aquela cujo código você precisa.

O valor do parâmetro tariff_code é apresentado na linha com esta taxa na coluna Rate code (bloco Integration setup: unique parameter values for your program).

Como gravar o parâmetro order_id para várias ações se o número de pedido for o ID de usuário ?

Em alguns programas afiliados, por exemplo, nos programas da categoria Jogos online, os relatórios geralmente não usam o número de pedido, mas o ID de usuário no sistema.

Portanto, se você precisar adicionar várias ações para esses programas, adicione um prefixo ao ID do pedido (parâmetro order_id). Use prefixos que ajudam a identificar ações em um instante.

Ação Parâmetro e seu valor Prefixo usado

Cadastro order_id=reg_123123 reg_

Recebendo nível 5 order_id=lvl5_123123 lvl5_

Voltar aos parâmetros necessários

Ação	Parâmetro e seu valor	Prefixo usado
Cadastro	order_id=reg_123123	reg_
Recebendo nível 5	order_id=lvl5_123123	lvl5_