Um lead pode ter várias vendas
Recompra é uma chamada nova, não uma atualização da anterior. Cada venda tem
seu valor, sua data e seu produto.
O lead expõe o consolidado:
O painel soma total; o funil conta o lead uma vez, não uma por venda.
sold_at é a data da compra
Não a data em que você está lançando. Essa distinção parece burocrática até a
primeira vez que ela morde: uma venda de 31/07 lançada em 06/08 com a data errada
aparece na semana seguinte, e o ROAS de duas semanas fica errado ao mesmo tempo.
O offset é obrigatório. Sem fuso a API responde 422. Ver
Primeiros passos para o porquê. Idempotência: external_source + external_id
Se a venda vem de uma plataforma, mande o id da transação de lá:
O par é único por empresa. O reenvio devolve 200 com duplicate: true em vez
de criar outra venda.
Isso é o que torna seguro:
- reprocessar um webhook que falhou no meio
- rodar de novo um script de importação
- a plataforma reenviar o mesmo postback (todas reenviam)
Sem external_id não há idempotência. Duas chamadas iguais viram duas vendas
e a receita dobra. Se a venda tem um id na origem, mande sempre — inclusive em
importação de histórico, senão o dia em que você ligar o webhook a base duplica.
Remover
DELETE /v1/sales/{id} apaga a venda. O lead não volta de etapa: ele pode ter
outras vendas, e mesmo sem nenhuma, escolher a etapa anterior seria inventar
histórico. Mova o lead explicitamente se quiser desfazer o ganho.
Produtos
product_id é opcional e precisa existir no catálogo da empresa
(Configurações → Funil → Produtos). Um product_id de outra empresa responde
404, nunca 403.