Documentação Técnica — Webhook de Vendas

Guia para integração do CRM/sistema comercial com o dashboard da ValoresAds.

Esta página não contém credenciais reais. A URL com token e o segredo do webhook devem ser enviados separadamente pela ValoresAds em canal seguro.

Visão geral

O Webhook de Vendas recebe pedidos emitidos e confirmações de vendas vindas do CRM ou sistema comercial do cliente. Ele permite cruzar o investimento em mídia (Meta Ads, Google Ads) com o resultado comercial real (pedidos e vendas confirmadas), gerando métricas de custo por venda confirmada, ROAS confirmado e ticket médio por vendedor.

Endpoint

http

POST https://hub.valoresads.com.br/api/public/sales/webhook?token=TOKEN_DA_CONEXAO

Autenticação

Envie os seguintes headers em toda requisição:

headers

Authorization: Bearer SEGREDO_DO_WEBHOOK
Content-Type: application/json

Eventos suportados

order_created — usado quando o pedido é emitido no CRM/sistema comercial.
sale_confirmed — usado quando a venda é confirmada no dia seguinte ou após validação interna.

Produtos aceitos

EFPURIFICADORVIP

Apenas esses três valores são aceitos em product_type.

Payload — pedido emitido

json

{
  "event_type": "order_created",
  "batch_id": "cliente-2026-07-24-001",
  "date": "2026-07-24",
  "items": [
    {
      "order_external_id": "PED-1001",
      "seller_name": "Maria Silva",
      "seller_external_id": "vend_001",
      "product_type": "PURIFICADOR",
      "quantity": 1,
      "unit_value": 1500.00,
      "order_value": 1500.00
    },
    {
      "order_external_id": "PED-1002",
      "seller_name": "João Santos",
      "seller_external_id": "vend_002",
      "product_type": "VIP",
      "quantity": 1,
      "unit_value": 1000.00,
      "order_value": 1000.00
    },
    {
      "order_external_id": "PED-1003",
      "seller_name": "Ana Costa",
      "seller_external_id": "vend_003",
      "product_type": "EF",
      "quantity": 1,
      "unit_value": 2000.00,
      "order_value": 2000.00
    }
  ]
}

Payload — venda confirmada

json

{
  "event_type": "sale_confirmed",
  "batch_id": "cliente-2026-07-25-001",
  "date": "2026-07-25",
  "items": [
    {
      "order_external_id": "PED-1001",
      "confirmed_value": 1500.00,
      "confirmation_status": "confirmed"
    },
    {
      "order_external_id": "PED-1002",
      "confirmed_value": 700.00,
      "confirmation_status": "partial"
    },
    {
      "order_external_id": "PED-1003",
      "confirmed_value": 0,
      "confirmation_status": "canceled"
    }
  ]
}

Status de confirmação aceitos

confirmed — venda confirmada integralmente.
partial — venda confirmada parcialmente.
canceled — pedido cancelado.
pending — pedido ainda pendente.

Regra importante sobre order_external_id

O campo order_external_id é obrigatório e deve ser o mesmo no pedido emitido e na confirmação da venda.

Ele é usado para atualizar a mesma venda, evitar duplicidade e cruzar o pedido emitido com a venda confirmada posteriormente.

cURL de exemplo

bash

curl -X POST "https://hub.valoresads.com.br/api/public/sales/webhook?token=TOKEN_DA_CONEXAO" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEGREDO_DO_WEBHOOK" \
  -d '{
    "event_type": "order_created",
    "batch_id": "cliente-2026-07-24-001",
    "date": "2026-07-24",
    "items": [
      {
        "order_external_id": "PED-1001",
        "seller_name": "Maria Silva",
        "seller_external_id": "vend_001",
        "product_type": "PURIFICADOR",
        "quantity": 1,
        "unit_value": 1500.00,
        "order_value": 1500.00
      }
    ]
  }'

Checklist para o TI

Recebeu a URL real do webhook enviada pela ValoresAds.
Recebeu o segredo real enviado pela ValoresAds.
Está usando POST.
Está usando Content-Type: application/json.
Está usando Authorization: Bearer.
Está enviando order_created quando o pedido é emitido.
Está enviando sale_confirmed quando a venda é confirmada.
Está mantendo o mesmo order_external_id entre pedido e confirmação.
Está usando apenas EF, PURIFICADOR ou VIP como product_type.
Está enviando valores numéricos sem símbolo de moeda.
Está tratando resposta HTTP 200 como sucesso.

Respostas esperadas

Status	Significado
200	Recebido com sucesso.
400	Payload inválido.
401	Token ou segredo inválido.
404	Conexão não encontrada.
409	Confirmação enviada para pedido inexistente, quando não houver dados suficientes para criar/atualizar.

Observação final

Após a configuração, a ValoresAds pode realizar um envio de validação controlado para confirmar se os dados chegaram corretamente ao dashboard.

Em caso de dúvida, envie este documento ao responsável técnico.