Conversion API PT
From Wiki
Conversion API
Este serviço aceita lotes de pedidos e os registra no sistema Awin. A API permite que transações sejam enviadas de forma autenticada do seu servidor diretamente para o servidor da Awin.
Criando o First Party Cookie Awin
Antes de explicar como enviar os pedidos, primeiro vamos esclarecer como capturar o "awc", que é uma parte necessária de cada transação válida. O "awc" é uma informação que a Awin anexa ao seu site no momento do clique. Essa informação é usada como uma chave para atribuir conversões a editores específicos com segurança e precisão. Também é utilizado para garantir que a conversão seja registrada se ocorrer dentro da janela de atribuição acordada. Você precisa configurar seu site para registrar o valor do awc em um cookie com as flags 'Secure' e 'HTTPOnly' quando o usuário acessar o seu site. O valor dentro desse cookie deve ser usado para preencher o parâmetro "cks" na conversão. Para criar o First Party Cookie da Awin usando a informação dentro do parâmetro "awc", por favor, utilize o seguinte código, ou similar:
<?php
function setAwc() {
if (!empty($_GET['awc'])) {
setcookie("awc",$_GET['awc'],time()+ 60 * 60 * 24 * 365,"/", "example.com", true, true);
}
}
?>Autenticação
No cabeçalho, forneça um token válido. Para descobrir como obter um token, consulte a página de API authentication and authorization. Para utilizar seu token para autenticação, envie-o utilizando os cabeçalhos. Utilize "x-api-key" como a chave e o seu token como o valor.
Enviando informações de transação com a API de Conversão
Endpoint (POST)
https://api.awin.com/s2s/advertiser/{advertiser_id}/orders
{advertiser_id} é o ID da sua conta de anunciante.
Cada lote de solicitações pode ter no máximo 1000 pedidos.
JSON request Body
{
"orders":[
{
"orderReference": "#1100011",
"amount": 111,
"channel": "aw",
"currency": "BRL",
"voucher": "10_OFF",
"isTest": false,
"awc": "1001_xxx_xxx",
"customerAcquisition": "NEW",
"commissionGroups": [
{
"code": "DEFAULT",
"amount": 111
}
...
],
"custom": {"1":"s2sAPI"},
"basket": [
{
"id": "123",
"name": "Fish",
"price": 111,
"quantity": 1,
"commissionGroupCode": "DEFAULT",
"category": "Food",
"sku": "111"
}
...
]
}
...
],
"webhook": {
"url": "https://example-webhook-url.com"
}
}
Order:
| Nome do Campo | Mandatório? | Tipo | Descrição | ||||
| orderReference | Sim | String | - | amount | Sim | Float | O valor subtotal do pedido após a adição dos descontos, mas antes da inclusão de taxas adicionais, como impostos, custos de entrega ou taxas de serviço. O valor deve ser um número decimal, separadores de milhares não são aceitos. O ponto decimal deve ser representado por um ponto, por `exemplo:` '1083.29'. Se o tipo de transação for um lead, então declare o número de leads, por `exemplo:` '1'. |
| channel | Sim | String | O nome do canal identificado como o último referenciador do clique. Use "aw" para Awin. Para informações sobre o Parâmetro de Canal, consulte https://wiki.awin.com/index.php/Advertiser_Tracking_Guide_PT/De-duplication#Channel_Parameter | ||||
| awc | Sim | String | - | currency | Sim | String | O código ISO da moeda utilizada na transação (BRL). |
| voucher | Não | String | O código do voucher usado na transação. `Exemplo:` 10_OFF | ||||
| isTest | Não | Boolean | Quando o rastreamento está no modo ao vivo, deve ser falso. Quando o rastreamento está no modo teste, também deve ser falso. Quando definido para o modo teste, as solicitações de rastreamento recebidas não são processadas. | ||||
| CustomerAcquisition | Não | String | Tipo de cliente. Os valores ENUM aceitos são NEW e RETURNING. | ||||
| commissionGroups | Sim | Array | Use grupos de comissão para atribuir toda ou parte da transação a uma porcentagem ou valor de comissão. Os grupos são criados e mantidos no Gerenciamento de Comissões na plataforma Awin. | ||||
| custom | Não | Object | A chave é um número (máximo 127) e o valor é um valor personalizado. | ||||
| basket | Não | Array | Array de objetos dos itens do carrinho. |
Commission Groups:
| Nome do Campo | Mandatório? | Tipo | Descrição |
| code | Sim | String | Os caracteres aceitos para o código do Grupo de Comissão são alfanuméricos (usar letras maiúsculas), sublinhado (_), ponto (.) e hífen (-). |
| amount | Sim | Float | O valor total gasto no grupo de comissão fornecido. O valor deve ser um número decimal, sem separadores de milhares. O ponto decimal deve ser representado por um período. |
Itens no carrinho:
| Nome do Campo | Mandatório? | Tipo | Descrição |
| id | Sim | String | O ID do produto. Deve ser único e é truncado em 75 caracteres. |
| name | Sim | String | O nome do produto. É truncado em 255 caracteres. |
| price | Sim | Float | O valor deve ser um número decimal, sem separadores de milhares. O ponto decimal deve ser representado por um período. |
| quantity | Sim | Integer | A quantidade de itens comprados. O valor deve ser um número inteiro. |
| commissionGroupCode | Sim | String | O código do grupo de comissão ao qual o produto pertence. Use “DEFAULT” a não ser que instruído o contrário. |
| category | Sim | String | Use isso para registrar a categoria à qual o produto pertence. É truncado em 255 caracteres.. |
| sku | Sim | String | Use isso para registrar o SKU (unidade de manutenção de estoque) do produto. É truncado em 255 caracteres. |
Webhook:
| Nome do Campo | Mandatório? | Tipo | Descrição |
| url | Não | String | Esta é a URL para onde a resposta do status da transação será enviada. |
Resposta de exemplo
{
"message": "",
"batchId": "1111-1692271186-8274157a-bd07-4b7a-a8d4-ddb21e741d11",
"successfulOrders": [
{
"orderReference": "#1100011",
"amount": 10,
"channel": "aw",
"currency": "BRL",
"voucher": "10_OFF",
"isTest": false,
"awc": "1111_xxx_xxx",
"customerAcquisition": "NEW",
"commissionGroups": [
{
"code": "DEFAULT",
"amount": 1.2
},
...
],
"custom": {
"1": "s2sAPI"
},
"basket": [
{
"id": "125",
"name": "Fish",
"price": 10,
"quantity": 1,
"commissionGroupCode": "DEFAULT",
"category": "Food",
"sku": "11111"
}
...
],
"advertiserId": 1111,
"correlationId": "e653481f-94d6-497d-8279-8c925b3a1cc8"
}
...
],
"failedOrders": [
{
"order":
{
"orderReference": "#1100012",
"amount": "123",
"channel": "aw",
"currency": "BRL",
"voucher": "10_OFF",
"isTest": false,
"awc": "1111_xxx_xxx",
"customerAcquisition": "NEW",
"commissionGroups": [
{
"code": "DEFAULT",
"amount": 1
},
...
],
"custom": {
"1": "s2sAPI"
},
"basket": [
{
"id": "",
"name": "",
"price": 20,
"quantity": 1,
"commissionGroupCode": "DEFAULT",
"category": "",
"sku": ""
},
...
],
"advertiserId": 1111,
"correlationId": "55d2ee39-eae1-440c-a3ff-bc2fba496c8f"
},
"errors": [
{
"field":"amount",
"message":"Property 'amount' must be of type 'number'"
},
...
]
},
...
]
}
- batchId : Identificador único para cada transação.
- correlationId : Identificador único para cada pedido dentro da transação.
| Código de resposta | Descrição |
| 200 | OK. Todas as conversões foram registradas corretamente. |
| 202 | Accepted. Seus requests foram recebidos, e serão processados posteriormente. |
| 206 | Partially OK. Alguns pedidos foram registrados com sucesso, enquanto outros encontraram erros. |
| 400 | Bad Request. Todos os objetos na solicitação são inválidos, ou o payload está malformado, ou havia mais de 1000 pedidos na solicitação. |
| 401 | Unauthorized. Credenciais de autenticação inválidas. Por favor, forneça credenciais válidas para acessar o recurso. |
| 406 | Not acceptable. Seu pedido foi rejeitado porque não pode ser processado imediatamente e alguns ou todos os pedidos são inválidos. |
| 500 | Internal Server Error. Não é possível processar seus pedidos no momento. Por favor, tente novamente mais tarde. |
Detalhes Webhook
O recurso de notificação por Webhook pode ser usado por anunciantes que desejam receber os detalhes de processamento em tempo real dos pedidos enviados para a API S2S. O Notificador enviará a solicitação de Webhook com os detalhes de todos os pedidos assim que todos os pedidos forem processados. Se houver dúvidas sobre um pedido que falhou, por favor, compartilhe o código com o ID do pedido.
Exemplos de notificação Webhook
{
"batchId": "15716-1697459823-d5d0d86d-eb5b-423b-a70e-03551219eb67",
"successfulOrders": [
{
"orderReference": "#1100011",
"correlationId": "52ee5b94-e5eb-4d21-88ee-22fe07cd1238"
}
],
"pendingOrders": [
{
"orderReference": "#2200022",
"correlationId": "52ee5b94-e5eb-4d21-88ee-22fe07cd1248"
}
],
failedOrders": [
{
"orderReference": "#3300033",
"correlationId": "52ee5b94-e5eb-4d21-88ee-22fe07cd1258",
"code": "VAL_NO_CLICKS_MATCHED",
"message": "No clicks matched to transaction"
}
],
"timestamp": 16492495245
}