Conversões

Postback do servidor

POST/v1/conversions

Informe uma conversão do seu servidor quando o pedido for confirmado ou o pixel não carregou. Envie o ID de clique, o evento e, se houver, um valor.

Quando usar

Use um postback para um pedido que o seu servidor confirma depois: um webhook de pagamento, um pedido por telefone, uma etapa do CRM. A sua página guarda o dw_sid do endereço de destino, na sua própria sessão ou no cookie _dw_sid que o pixel define, e o repassa quando cria o pedido. Exige um plano com rastreamento de conversões.

Autentique com o segredo de postback do site (Authorization: Bearer dwps_…, mostrado uma vez quando você o cria ou gira) ou com uma chave de API com o escopo conversions:write.

Corpo da requisição

clickIdstringobrigatórioO valor dw_sid do endereço de destino, exatamente como chegou.

eventstringobrigatórioO nome do evento: um entre purchase, lead, signup, ou uma meta que você criou. Letras minúsculas, dígitos e sublinhados.

valuenumberopcionalO valor, como número. Um reembolso é um valor negativo.

currencystringopcionalUm código ISO 4217 como USD. Obrigatório quando há um valor. Os valores nunca são convertidos entre moedas.

orderIdstringopcionalO seu número de pedido, até 64 caracteres. Enviar o mesmo de novo é ignorado.

occurredAtstringopcionalQuando aconteceu, como horário ISO 8601. Agora se ausente. Deve estar dentro da janela de atribuição.

metadataobjectopcionalAté 10 valores de texto curtos. Uma chave ou valor que pareça dado pessoal é recusado.

Envie

exemploPOST /v1/conversions

curl -X POST https://api.dotwick.com/v1/conversions \  -H "Authorization: Bearer dwps_YOUR_POSTBACK_SECRET" \  -H "Content-Type: application/json" \  -d '{    "clickId": "v1.k3m9x2q7c4v1b6n8.a1b2c3d4e5f6.ffk.Hk2LmN0pQ4r",    "event": "purchase",    "value": 49.5,    "currency": "USD",    "orderId": "ORD-1001"  }'

Resposta

A chamada responde antes de a conversão ser atribuída. O resto acontece em segundo plano: um ID de clique de outro espaço de trabalho é recusado, um fora da janela é guardado como não atribuído e uma repetição do mesmo orderId é ignorada.

202 Accepted

{  "status": "queued"}

Erros

400validation_failedUm ID de clique malformado, um valor sem moeda, um campo desconhecido ou metadados com dados pessoais.

401unauthorizedO segredo de postback ou a chave de API é desconhecido.

403feature_not_in_planO plano do espaço de trabalho não inclui rastreamento de conversões.

429rate_limitedRequisições demais; espere o Retry-After.

Sem dados pessoais

O corpo é estrito: um campo que não está listado acima, inclusive um e-mail ou um telefone, faz a requisição inteira falhar.
Chaves de metadados como email, phone, name e address são recusadas, assim como um valor que pareça um e-mail ou um telefone.