Guia · Enviar um lead

🎯

O que este guia faz

O caso de integração mais comum: um portal, o site da imobiliária ou uma landing page captura um interessado e entrega esse lead ao CRM, que o distribui para um corretor na fila de atendimento.

Escopo necessário: leads:write

🗺️ O caminho do lead

flowchart LR
  A["Portal / site /<br/>landing page"] -->|"POST /leads"| B["Imoview Next"]
  B --> C["Fila de atendimento"]
  C --> D["Corretor"]
  B -.->|"mesmo external_id"| E["deduped: true<br/>(não duplica)"]

1️⃣ Monte a requisição

Envie um POST para /leads com a chave no header. Os campos são flexíveis para casar com o vocabulário de cada portal.

curl -X POST https://api.imoviewnext.com.br/pub/v1/leads \
  -H "Authorization: Bearer imn_seuconvenio_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "email": "[email protected]",
    "phone": "+55 31 99999-0000",
    "message": "Tenho interesse no apartamento do bairro Savassi.",
    "imovel": "AP1234",
    "external_id": "site-8842"
  }'

2️⃣ Campos aceitos

📘

A origem (mídia) vem da chave, não do corpo

Cada chave de API representa uma origem. Campos como portal, midia e origem no corpo são ignorados nesta rota.

🏡 Lead de proprietário (captação)

O proprietário que quer vender ou alugar entra pela mesma rota, com fluxo: "captacao" e o imóvel em imovelOfertado. Ele vai para as filas de captador e vira uma captação no CRM.

curl -X POST https://api.imoviewnext.com.br/pub/v1/leads \
  -H "Authorization: Bearer imn_seuconvenio_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fluxo": "captacao",
    "name": "Carlos Lima",
    "phone": "+55 31 98888-0000",
    "imovelOfertado": {
      "tipo": "Apartamento",
      "finalidade": "venda",
      "cidade": "Belo Horizonte",
      "bairro": "Savassi",
      "valorVenda": 850000,
      "quartos": 3
    },
    "external_id": "site-captacao-311"
  }'

🚧

Exige o módulo de Captação

Convênio sem o módulo de Captação responde 409 CAPTACAO_REQUIRES_MODULE. O escopo continua leads:write.

3️⃣ Resposta

{ "statusCode": 201, "portalName": "Site próprio" }

4️⃣ Reenvio seguro (idempotência)

A rota é idempotente por external_id: reenviar o mesmo id devolve 200 com deduped: true, em vez de criar um segundo lead.

{ "statusCode": 200, "deduped": true }

👍

Pode reenviar sem medo

Sem external_id, corpos byte a byte idênticos também são tratados como reentrega. Ou seja: você pode reenviar com segurança após um 429 (limite excedido) ou uma falha de rede, sem duplicar o lead.

⚠️ Erros comuns

➡️ Depois que o lead entra

Para acompanhar e conduzir o atendimento que nasceu do lead (anotar, agendar visita, registrar parecer, incluir proposta), veja Conduzir o atendimento.