Documento de integração

API de Leads
DP Consórcios

Um endpoint HTTPS para enviar leads de anúncios diretamente ao CRM Comercial da DP. Aceita um lead por vez ou em lote, e é seguro reenviar em caso de falha.

Endereço

POST https://painel.hubdp.com.br/api/public/parceiro-leads

Somente HTTPS. Há também um GET no mesmo endereço, sem autenticação, que responde {"status":"ok"} — serve só para conferir se a URL está certa.

Autenticação

Header obrigatório em todo POST:

x-api-key: Solicitar para a equipe da DP

A chave é enviada por canal separado, nunca dentro deste documento. Sem chave, ou com chave errada, a resposta é 401 com {"ok":false,"error":"nao_autorizado"}.

Corpo da requisição

Content-Type: application/json. Aceita um lead solto ou vários dentro de leads. Máximo de 100 leads por requisição — acima disso a resposta é 413.

{
  "leads": [
    {
      "nome": "Maria Souza",
      "telefone": "(48) 99911-2233",
      "email": "maria@exemplo.com",
      "id_externo": "gads-7781234",
      "campanha": "Consórcio Imóvel - SC",
      "grupo_anuncios": "Imóvel 200k",
      "anuncio": "Anúncio A - Simule agora",
      "palavra_chave": "consórcio imóvel",
      "gclid": "Cj0KCQjw...",
      "cidade": "Criciúma/SC",
      "valor_pretendido": "200000",
      "mensagem": "Quero simular parcela de 200 mil"
    }
  ]
}

Campos

Campo	Obrigatório	O que é
`nome`	sim	Nome de quem preencheu o formulário. Até 200 caracteres.
`id_externo`	sim	Identificador do lead no sistema do parceiro. É a chave anti-duplicidade.
`telefone`	um dos dois	Aceita qualquer formatação. Precisa ter no mínimo 8 dígitos; o CRM guarda só os dígitos.
`email`	um dos dois	—
`campanha`	não	Nome da campanha no Google Ads.
`grupo_anuncios`	não	Nome do grupo de anúncios.
`anuncio`	não	Nome ou identificação do anúncio.
`palavra_chave`	não	Termo que trouxe o clique.
`gclid`	não	Google Click ID, quando disponível.
`cidade`	não	Cidade/UF informada pelo lead.
`valor_pretendido`	não	Aceita `200000`, `"200.000"` ou `"200000,00"`.
`mensagem`	não	Texto livre que o lead escreveu. Até 2.000 caracteres.

Telefone ou email é obrigatório — pelo menos um dos dois. Lead sem nenhuma forma de contato não é trabalhável, então é recusado.

Telefone com menos de 8 dígitos é tratado como ausente: se houver email, o lead entra sem telefone; se não houver, é recusado com mensagem dizendo qual valor chegou.

Campos desconhecidos são ignorados, não causam erro. A distribuição interna dos leads é definida pela DP — não há campo para endereçar o lead a um vendedor específico.

Duplicidade: `id_externo`

Esta é a parte mais importante da integração. O id_externo é o identificador do lead no sistema do parceiro. O CRM guarda esse valor e recusa gravar duas vezes o mesmo id_externo.

Reenviar é seguro. Se a requisição der timeout, se a fila reprocessar, se a integração tentar de novo — mande o mesmo corpo outra vez. O lead não vai duplicar.
Cada lead precisa de um id_externo próprio e estável. Não use data/hora, número aleatório ou contador que reinicia: use o id do registro no banco do parceiro, ou o id do formulário no Google.
Reenviar não sobrescreve o lead. Se um vendedor da DP já anotou algo, o reenvio não desfaz. A resposta apenas informa duplicado.

Resposta

200 quando tudo entrou, 207 quando parte falhou. Sempre com o resultado de cada lead:

{
  "ok": true,
  "recebidos": 2,
  "criados": 1,
  "duplicados": 1,
  "erros": 0,
  "resultados": [
    { "id_externo": "gads-7781234", "status": "criado", "lead_id": "e8628b11-..." },
    { "id_externo": "gads-7781200", "status": "duplicado" }
  ]
}

Status de cada lead

Status	Significa	O que fazer
criado	Entrou no CRM.	Nada.
duplicado	Esse `id_externo` já existia.	Nada — é o resultado esperado de um reenvio.
erro	Esse lead não entrou; `erro` explica.	Corrigir e reenviar só esse.

Um lead com erro não derruba os outros do lote. Por isso o 207: tratar 207 como sucesso total esconderia o lead que ficou de fora.

Códigos da requisição inteira

200

Tudo entrou. Nada a fazer.

207

Parte falhou. Ver resultados e reenviar só os que deram erro.

400

corpo_invalido — não era JSON. Corrigir o corpo.

401

nao_autorizado — chave ausente ou errada. Conferir x-api-key.

413

lote_grande — mais de 100 leads. Dividir em várias requisições.

5xx

Problema do lado da DP. Reenviar com espera crescente.

Erro 5xx e nova tentativa

Em 500, 502, 503 ou timeout, tente de novo — 1 min, 5 min, 15 min, 1 h — e depois avise a DP. Como a deduplicação é por id_externo, reenviar o mesmo lead nunca duplica: se ele já tinha entrado antes da falha, a resposta vem duplicado e está tudo certo.

503 endpoint_nao_configurado significa que falta configuração do lado da DP — nesse caso avise direto, tentar de novo não resolve.

Exemplo com curl

curl -X POST https://painel.hubdp.com.br/api/public/parceiro-leads \
  -H "x-api-key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Maria Souza","telefone":"48999112233","id_externo":"gads-7781234","campanha":"Consórcio Imóvel - SC"}'

O que a DP faz com o lead

Entra no CRM Comercial na fase Novo, com origem Anúncios.
É atribuído automaticamente a um vendedor da equipe responsável por esta origem.
Campanha, grupo, anúncio, palavra-chave e GCLID ficam registrados no lead, para a DP medir qual campanha traz venda.