Envio de Leads ao CVCRM via API

1. Contexto

Parceiros que captam leads em canais externos — landing pages, portais imobiliários, chatbots, ferramentas de automação de marketing — precisam enviar esses contatos ao CVCRM para que entrem no funil de vendas da incorporadora e sejam distribuídos automaticamente para corretores ou gestores.

Este caso de uso cobre o fluxo completo: autenticação, envio do lead, verificação do cadastro e tratamento dos cenários de erro mais comuns.

2. Pré-requisitos

Antes de consumir a API, o parceiro precisa ter em mãos:

⚠️

Atenção: O token está vinculado a um usuário e a um ambiente específico. Usar credenciais de um subdomínio diferente retorna 401.

👉Para saber como se autenticar nas APIs na versão v1 acesse:

Como autenticar nas APIs do CV CRM na v1 com E-mail e Token.

Permissão necessária no perfil do usuário: Leads > Cadastrar/Alterar Lead

Rate limit: 200 requisições/minuto (REST). Exceder esse limite retorna 429 Too Many Requests.

3. Fluxo de Integração

[Sistema Parceiro]
       |
       | 1. Capta lead (form, chatbot, portal)
       ↓
[POST /api/v1/comercial/leads]
       |
       |--- 201 Created → Lead cadastrado com sucesso
       |--- 400 "erro_elterar_lead" → Lead já existe → enviar com permitir_alteracao: true
       |--- 400 campo obrigatório → Revisar payload
       |--- 401 → Credenciais inválidas ou expiradas
       |--- 422 → Erro interno → contatar suporte
       ↓
[GET /api/v1/comercial/leads?idlead={id}]
       |
       | 2. Verificar dados do lead cadastrado
       ↓
[Distribuição automática no CVCRM]
       (corretor / gestor / imobiliária conforme configuração)

4. Autenticação

Todas as requisições exigem os headers email e token:

email: [email protected]
token: 2ed820f89afa16cabb6f1585f9a85b4e6bfc80c3

Os headers são enviados em todas as requisições — não há sessão ou cookie.

5. Endpoint: Cadastrar Lead

Request

POST https://{{dominiodocliente}}.cvcrm.com.br/api/v1/comercial/leads
Content-Type: application/json
email: [email protected]
token: 2ed820f89afa16cabb6f1585f9a85b4e6bfc80c3

Campos obrigatórios

Campos opcionais recomendados

Exemplo de payload completo

{
  "nome": "Ana Paula Ferreira",
  "email": "[email protected]",
  "telefone": "11987654321",
  "origem": "FB",
  "idempreendimento": 48,
  "idfila_distribuicao_leads": 3,
  "documento_tipo": "cpf",
  "documento": "12345678900",
  "sexo": "F",
  "renda_familiar": "7500.00"
}

Response — Sucesso (201 Created)

{
  "idlead": 55,
  "empreendimentos": [
    {
      "idempreendimento": 48,
      "nome": "Empreendimento Qualidade"
    }
  ],
  "corretor": [
    {
      "idcorretor": 12,
      "nome": "José da Silva"
    }
  ],
  "imobiliaria": [
    {
      "idimobiliaria": 43,
      "nome": "Imobiliária do Lead"
    }
  ],
  "gestor": [
    {
      "idgestor": 43,
      "nome": "Nome do gestor"
    }
  ]
}

O idlead retornado deve ser armazenado pelo sistema parceiro para consultas e atualizações futuras.

6. Endpoint: Consultar Lead

Após o cadastro, é possível verificar os dados do lead por idlead, email ou telefone (use apenas um parâmetro por requisição).

Request

GET https://{{dominiodocliente}}.cvcrm.com.br/api/v1/comercial/leads?idlead=55
email: [email protected]
token: 2ed820f89afa16cabb6f1585f9a85b4e6bfc80c3

Filtros disponíveis

Response — Sucesso (200 OK)

{
  "codigo": 200,
  "total": 1,
  "limit": 30,
  "offset": 0,
  "totalConteudo": 1,
  "leads": [
    {
      "idlead": 55,
      "nome": "Ana Paula Ferreira",
      "email": "[email protected]",
      "telefone": "+55(11) 98765-4321",
      "situacao": {
        "id": 1,
        "nome": "Novo Lead"
      },
      "corretor": {
        "id": 12,
        "nome": "José da Silva",
        "email": "[email protected]"
      },
      "empreendimento": [
        {
          "id": 48,
          "nome": "Empreendimento Qualidade"
        }
      ],
      "origem": "Facebook",
      "data_cad": "2026-06-10 14:32:00",
      "score": 5,
      "midias": ["Facebook Ads"],
      "tags": [],
      "campos_adicionais": []
    }
  ]
}

7. Origens disponíveis

O campo origem aceita somente os códigos abaixo. Enviar um valor fora desta lista resultará em ND (Não Definido).

Consulte a lista completa no Portal do Desenvolvedor.

8. Tratamento de Erros

9. Edge Cases

Lead duplicado (mesmo e-mail ou telefone) O CVCRM não permite dois leads com o mesmo e-mail ou telefone. O segundo envio é tratado como uma conversão — o sistema registra a nova entrada na mídia do lead existente. Para atualizar os dados do lead, inclua "permitir_alteracao": true no payload.

Lead sem empreendimento Se idempreendimento não for enviado, o lead entra no sistema sem vínculo a empreendimento. A distribuição seguirá as regras gerais de fila configuradas no CVCRM.

Fila de distribuição não especificada Sem idfila_distribuicao_leads, a atribuição de corretor/gestor seguirá a configuração padrão da incorporadora. Recomenda-se sempre especificar a fila para integrações com múltiplos empreendimentos.

Token expirado O token pode ter data de vencimento configurada. Ao expirar, todas as requisições retornam 401. Implemente um mecanismo de alerta antes do vencimento.

Volume alto (eventos de lançamento) Em eventos com pico de cadastros simultâneos, o rate limit de 200 req/min pode ser atingido. Implemente uma fila de envio com retry e backoff exponencial.

10. Diagnóstico via CVIO

O CVIO é o monitor de requisições do CVCRM. Acesse pelo endereço:

https://{{dominiodocliente}}.cvcrm.com.br/cvio

Ele registra todas as entradas e saídas das APIs com status, timestamp e payload. Os logs ficam disponíveis por 30 dias. Use o CVIO para diagnosticar erros em produção antes de acionar o suporte.

11. Checklist de Go-Live

• Subdomínio do cliente identificado e validado
• Usuário administrativo criado com permissão Leads > Cadastrar/Alterar Lead
• Token gerado com data de vencimento definida
• Envio de lead teste com retorno 201 confirmado
• Consulta de lead (GET) validada com idlead retornado
• Cenário de lead duplicado testado (400 + permitir_alteracao)
• Rate limiting considerado na arquitetura de envio
• Acesso ao CVIO confirmado para monitoramento

12. Referências

• API de Cadastrar Leads (POST)
• API de Retornar Leads (GET)
• Como autenticar com E-mail e Token (v1)
• Módulo Prospectar — Documentação
• Permissões dos Endpoints
• Informações Gerais das APIs