📘

Antes de começar

Esta página é um complemento à Informações gerais. Se você ainda não leu, recomendamos começar por lá — ela explica a arquitetura das nossas APIs, os métodos HTTP disponíveis e como funciona o CVIO.

🔑 O que é a API Key e por que ela é obrigatória?

Todas as APIs do CV CRM utilizam autenticação baseada em e-mail + token. Esses dois dados funcionam como a sua identidade nas requisições: sem eles configurados corretamente, o sistema não consegue identificar quem está fazendo a chamada e retorna um erro 401 - Unauthorized.

O token é gerado diretamente no painel do gestor e está vinculado a um usuário administrativo do CV CRM. Por isso, é importante entender desde o início: o e-mail utilizado deve pertencer ao mesmo ambiente CVCRM onde os dados serão consumidos.

Por exemplo, se você está integrando com suaempresa.cvcrm.com.br, o e-mail do usuário precisa estar cadastrado nesse domínio — e não em outro ambiente ou subdomínio diferente.

🗂️ Etapa 1: Criando o usuário de acesso

Antes de gerar o token, é necessário ter um usuário administrativo ativo no CV CRM com as permissões adequadas para os endpoints que você vai consumir.

⚠️

Atenção

Cada endpoint do CV CRM exige que o perfil do usuário tenha as permissões correspondentes habilitadas. Acessar uma API sem a permissão correta retorna um erro 403 - Forbidden — o sistema reconhece o usuário, mas nega o acesso ao recurso solicitado.

Antes de começar sua integração, verifique quais permissões são necessárias:

👉 Permissões dos Endpoints da API CVCRM

Para entender como criar e configurar perfis de acesso no painel:

📘

Configuração de Perfis de Acesso - Painel do Gestor

🔐 Etapa 2: Gerando o token de acesso

Com o usuário criado e as permissões configuradas, é hora de gerar o token. Acesse o cadastro de usuários administrativos no CV CRM, localize o usuário desejado e clique na opção "Token".

Você também pode definir uma data de vencimento para o token gerado — recomendamos fazer isso para manter a segurança da sua integração, mas ao chegar na data de vencimento será necessário gerar um novo token para continuar a utilizar as nossas APIs.

👍

Veja o passo a passo detalhado: Como gerar um token - Painel do Gestor

Ao final desta etapa, você terá em mãos dois dados essenciais:

• ✅ E-mail do usuário administrativo
• ✅ Token gerado no painel

Guarde esses dados com segurança. Você vai precisar deles em todas as requisições.

🌐 Etapa 3: Identificando o domínio correto

Esse é um ponto crítico que causa muita confusão. A URL base das APIs do CV CRM varia de acordo com o domínio do cliente, e não existe uma URL genérica que funcione para todos.

O padrão correto é:

https://{{dominiodocliente}}.cvcrm.com.br/api/v1/...

Substitua {{dominiodocliente}} pelo subdomínio da sua empresa. Por exemplo:

⚠️

Atenção

Usar o domínio errado é uma das causas mais comuns de erros 404 - Not Found no endpoint de autenticação. Certifique-se de que está usando o subdomínio correto da sua incorporadora antes de fazer qualquer requisição.

Se você não sabe qual é o seu subdomínio, entre em contato com o administrador do CV CRM da sua empresa ou consulte o endereço que você usa para acessar o painel do gestor — ele segue o mesmo padrão.

💻 Etapa 4: Fazendo sua primeira requisição

Com o e-mail, o token e o domínio corretos em mãos, você está pronto para fazer sua primeira chamada. Veja abaixo um exemplo de requisição usando o endpoint de leads — o mais utilizado no portal.

Exemplo: Consultando um lead (GET)

GET https://{{dominiodocliente}}.cvcrm.com.br/api/v1/comercial/leads
email: [email protected]
token: seu-token-gerado-no-painel

📘

O e-mail e o token são enviados como headers da requisição, não no body. Verifique se o seu cliente HTTP (Postman, Insomnia, código, etc.) está configurando os headers corretamente.

Se a requisição retornar 200 - OK, parabéns — sua API Key está configurada e funcionando! 🎉

Você pode explorar agora os endpoints mais utilizados do CV CRM:

• 📄 GET Lead — Consultar dados de um lead
• 📝 POST Lead — Cadastrar um novo lead
• 👥 Leads Corretores — Consultar leads por corretor

🚦 Entendendo os erros mais comuns

Se algo der errado, a tabela abaixo vai ajudá-lo a identificar rapidamente o que precisa ser ajustado:

🔍 Monitorando suas requisições com o CVIO

Depois de começar a fazer requisições, o CVIO é a sua melhor ferramenta para acompanhar o que está acontecendo. Ele registra todas as entradas e saídas de informações, mostrando status, data, descrição e outros filtros que ajudam a diagnosticar erros rapidamente.

Acesse o CVIO da sua empresa pelo endereço:

👍

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

⚠️ As requisições ficam armazenadas por 30 dias.

✅ Checklist: Tudo pronto para integrar?

Antes de avançar para os tutoriais e referências de API, confira se você já tem tudo configurado:

• Usuário administrativo criado com perfil de acesso adequado
• Token gerado no painel do gestor (com data de vencimento definida)
• E-mail e token salvos com segurança
• Domínio correto da incorporadora identificado
• Primeira requisição realizada com retorno 200

Com tudo isso em ordem, você está pronto para explorar os módulos do CV CRM e começar suas integrações!

🚀 Próximos passos

Agora que sua API Key está configurada, sugerimos continuar a jornada por aqui:

👍

Os módulos do CV — Entenda como o CV CRM está organizado em Prospectar, Vender, Relacionar e Gerenciar, e quais APIs estão disponíveis em cada módulo.

📘

Referências das APIs — Acesse a documentação completa de todos os endpoints disponíveis, com exemplos de requisição e resposta.

📘

Gerenciamento de Permissões de APIs por Perfil e Módulo — Guia completo sobre como configurar permissões para cada tipo de integração.

🫱🏽‍🫲🏿 Estamos aqui para ajudar!

Se tiver qualquer dúvida durante a configuração, entre em contato com o nosso suporte ou use o chat disponível no CV.

👍

Endereço de e-mail do CV CRM: [email protected]

Estamos torcendo pelo sucesso da sua integração! 💚