Jornada do cliente: Do lead à reserva

🗺️ Visão Geral

Este caso de uso descreve como usar as APIs do CVCRM para implementar o fluxo de venda online de ponta a ponta: desde a captura de um interessado em um empreendimento até a reserva de uma unidade em seu nome.

É o fluxo mais comum em integrações com portais imobiliários, landing pages de lançamentos e aplicativos próprios de incorporadoras. Ao final, você terá um lead registrado, uma unidade verificada como disponível, um cliente cadastrado e uma reserva confirmada no CVCRM — tudo via API, sem intervenção manual.

🔧 O problema que este fluxo resolve

Sem integração, o processo de reserva exige que o corretor: receba o contato do interessado, consulte a tabela de disponibilidade manualmente, cadastre o cliente no sistema e registre a reserva. Cada etapa manual introduz latência e risco de erro — especialmente em lançamentos com alta concorrência por unidades.

Com a integração, esse processo acontece automaticamente assim que o interessado preenche um formulário ou realiza uma ação em qualquer canal conectado ao CVCRM.

✅ Pré-requisitos

Antes de começar, certifique-se de ter:

• Domínio da base: ex. suaempresa.cvcrm.com.br
• E-mail e Token de integração para se autenticar nas API v1 gerados no Painel do Gestor → Usuários → Token
  → Como gerar um token
  →Como autenticar nas APIs com e-mail e token
• Bearer Token de integração para se autenticar nas API v3+ gerados na API de autenticação. →Como autenticar nas APIs com Bearer Token
• Perfil de acesso com permissões habilitadas para: Leads, Reservas, Clientes e Empreendimentos
  → Gerenciamento de permissões
• ID do empreendimento (idempreendimento_cv) que será ofertado
• ID do corretor (idcorretor_cv) responsável pela venda

🔑 Autenticação: entendendo as versões

As APIs do CVCRM utilizam dois modelos de autenticação. É fundamental identificar a versão de cada endpoint para usar o método correto.

Todas as APIs deste fluxo principal são v1, com exceção do GET de consulta de cliente (etapa 3a), que é v3.

Autenticação v1 — e-mail + token

Inclua em todas as requisições v1:

email: [email protected]
token: SEU_TOKEN_FIXO

Autenticação v3 — Bearer Token

Para endpoints v3, primeiro obtenha o token via login:

POST https://{seudominio}.cvcrm.com.br/api/v3/auth/token
Content-Type: application/json

{
  "email": "[email protected]",
  "senha": "sua-senha",
  "painel": "gestor"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 21600
}

Use o access_token no header de todas as chamadas v3:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

O token expira em 6 horas (21600 segundos). Implemente renovação automática: ao receber um 401, reautentique e repita a chamada.

📋 APIs utilizadas neste fluxo

🔄 Fluxo de integração

[Canal externo]
     │
     │ Interessado preenche formulário
     ▼
┌────────────────────────────────┐
│  1. POST Lead (v1)              │  → Lead registrado e distribuído para fila
└───────────────┬────────────────┘
                │
                │ Com idempreendimento em mãos
                ▼
┌────────────────────────────────┐
│  2. GET Mapa Disponibilidade   │  → Valida unidade como "disponivel"
│     (v1)                       │
└───────────────┬────────────────┘
                │
                │ Unidade confirmada
                ▼
┌────────────────────────────────┐
│  3a. GET Cliente (v1)          │  → Cliente já existe? Recupera idpessoa_cv
│      OU                        │
│  3b. POST Cliente (v1)         │  → Cadastra novo cliente, retorna idpessoa_cv
└───────────────┬────────────────┘
                │
                │ Com idpessoa_cv + idunidade_cv
                ▼
┌────────────────────────────────┐
│  4. POST Reserva (v1)          │  → Reserva criada, unidade bloqueada
└────────────────────────────────┘

👣 Passo a passo

🧲 Etapa 1 — Cadastrar o Lead

Registra o interessado na base de leads da incorporadora. Se o lead já existir (mesmo e-mail e/ou telefone), o CVCRM realiza uma conversão — permitir_alteracao: true garante que o fluxo não seja interrompido por duplicidade.

Request

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

{
  "nome": "Ana Beatriz Silva",
  "email": "[email protected]",
  "telefone": "11987654321",
  "origem": "SI",
  "idempreendimento": 42,
  "idfila_distribuicao_leads": 7,
  "permitir_alteracao": true,
  "midia": "landing-page-lancamento-jardins"
}

Campos obrigatórios:email e/ou telefone (ao menos um)

Campos relevantes:

Response esperado — 200 OK

{
  "codigo": 200,
  "mensagem": "Lead cadastrado com sucesso",
  "idlead": 18734
}

O idlead retornado pode ser usado posteriormente para associar o lead à reserva via campo idreserva na API de leads.

🏗️ Etapa 2 — Consultar o Mapa de Disponibilidade

Valida se a unidade de interesse ainda está disponível antes de criar a reserva. O idEmpreendimento é passado como path parameter.

Request

GET https://{seudominio}.cvcrm.com.br/api/v1/comercial/mapadisponibilidade/42
Content-Type: application/json
email: [email protected]
token: SEU_TOKEN

Query params opcionais:

Response esperado — 200 OK (trecho)

{
  "empreendimento": "Jardins Residencial",
  "unidades": [
    {
      "idunidade": 1021,
      "nome": "Apto 302 - Torre A",
      "situacao": "disponivel",
      "valor": 485000.00
    },
    {
      "idunidade": 1022,
      "nome": "Apto 303 - Torre A",
      "situacao": "reservado",
      "valor": 490000.00
    }
  ]
}

Situações possíveis de unidade:

Se a unidade desejada não estiver disponivel, apresente as alternativas disponíveis antes de prosseguir. Guarde o idunidade para a etapa de reserva.

👤 Etapa 3 — Gerenciar o Cliente

Existem dois cenários: o cliente já está cadastrado no CVCRM (use GET v1 para recuperar o idpessoa_cv) ou é um novo cliente (use POST v1 para cadastrá-lo).

🔍 Etapa 3a — Verificar se o cliente já existe

POST https://{seudominio}.cvcrm.com.br/api/v1/cadastros/clientes
Content-Type: application/json
email: [email protected]
token: SEU_TOKEN

Se o cliente for encontrado, o response trará o idpessoa_cv. Use esse ID diretamente na etapa 4 e pule a etapa 3b.
Se retornar vazio ou 404, prossiga para o cadastro na etapa 3b.

➕ Etapa 3b — Cadastrar novo cliente

POST https://{seudominio}.cvcrm.com.br/api/v1/cadastros/clientes
Content-Type: application/json
email: [email protected]
token: SEU_TOKEN

{
  "idpessoa_int": "EXT-9043",
  "nome": "Ana Beatriz Silva",
  "documento_tipo": "cpf",
  "documento": "12345678900",
  "email": "[email protected]",
  "telefone": "11987654321",
  "data_nasc": "1990-05-15",
  "estado_civil": 4,
  "sexo": "F"
}

Campos obrigatórios:

Valores para estado_civil:

⚠️

Os campos obrigatórios variam conforme a configuração de Campos Obrigatórios definida por empreendimento (Empreendimentos → Reservas e Simulações → Campos Obrigatórios). Valide essa configuração antes de definir o contrato da integração.

Response esperado — 200 OK

{
  "codigo": 200,
  "mensagem": "Cadastro de cliente realizado com sucesso",
  "idpessoa_cv": 9043
}

📌 Etapa 4 — Cadastrar a Reserva

Com idpessoa_cv e idunidade_cv em mãos, crie a reserva. Este é o passo final: bloqueia a unidade e registra a intenção de compra na base de reservas da incorporadora.

A API utiliza um padrão de identificador duplo para cada entidade: aceita o ID do CVCRM (_cv) ou o ID interno do seu sistema (_int). Informe ao menos um de cada par.

Request

POST https://{seudominio}.cvcrm.com.br/api/v1/comercial/reservas
Content-Type: application/json
email: [email protected]
token: SEU_TOKEN

{
  "idpessoa_cv": 256,
  "idpessoa_int": "P457",
  "idempreendimento_cv": 32,
  "idempreendimento_int": "E3",
  "idunidade_cv": 14,
  "idunidade_int": "UN258",
  "idcorretor_cv": 15,
  "idcorretor_int": "CO15",
  "idreserva_int": "EX1234",
  "idtipovenda": 3,
  "condicoes": [
    {
      "idserie_cv": 1,
      "idserie_int": "S125",
      "quantidade_parcelas": 2,
      "valor_parcela": 1234.56,
      "primeiro_vencimento": "27/09/2025",
      "idindexador": 1,
      "idportador": 3,
      "retirar_comissao": "N"
    }
  ],
  "associado": {
    "idpessoa_cv": 257,
    "idpessoa_int": "P458",
    "idtipo_associacao": 1,
    "participacao_contrato": "S",
    "percentual_participacao": 12.5
  },
  "espacos_complementares": [
    {
      "idespaco_cv": 939,
      "idespaco_int": "EC939",
      "valor": 1234.56
    }
  ]
}

Campos e padrão de identificadores:

⚠️

A API POST de reserva permite incluir apenas um associado no momento da criação. Para adicionar até 6 associados, use PUT /api/v1/comercial/reservas/{idreserva} após criar a reserva.

Response esperado — 200 OK

{
  "codigo": 200,
  "mensagem": "Cadastro de reserva realizado com sucesso",
  "idreserva": 5521
}

⚠️ Edge cases e tratamento de erros

📡 Monitoramento

Todas as requisições são registradas no CVIO, o painel de monitoramento de transações do CVCRM. Use-o para auditar chamadas, verificar payloads e diagnosticar erros em produção.

Acesse em: https://{seudominio}.cvcrm.com.br/cvio

As transações ficam disponíveis por 30 dias.

📚 Referências

• API Cadastrar Lead (POST v1)
• API Retornar Leads (GET v1)
• API Mapa de Disponibilidade (GET v1)
• API Cadastrar Cliente (POST v1)
• API Cadastrar Reserva (POST v1)
• Autenticação v1: e-mail e token
• Permissões dos endpoints
• CVIO — Monitoramento de transações