Referências das Apis

Cadastra Leads

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

1 INTRODUCAO

1.1 Definição

A interface viabiliza o cadastro e a modificação de leads para o sistema CV. As ações são executadas através do envio de um JSON, referente à requisição, contendo os dados dos campos a serem cadastrados ou modificados.

O cadastro pode ser proveniente do:

(1) Sistema CV - cadastro, edição ou importação;
(2) Site do cliente;
(3) Integrações - RD Station, Facebook, Contako.

1.2 Usuários

Os tipos de usuário que podem enviar requisições são:

  • Gestor (usuário administrativo) - pode cadastrar ou alterar todo e qualquer dado pertinente ao lead, estando a alteração restrita para os campos: (1) origem; (2) interações.
  • Imobiliária - pode cadastrar ou alterar todo e qualquer dado pertinente ao lead que seja responsável, estando a alteração restrita para os campos: (1) origem; (2) interações; (3) gestor; (4) imobiliária
  • Corretor - pode cadastrar ou alterar todo e qualquer dado pertinente ao lead que seja responsável, estando a alteração restrita para os campos: (1) origem; (2) interações; (3) gestor; (4) imobiliária; (5) corretor.

1.3 Influências

Pode haver uma cadeia de funcionalidades que influencia o lead, assim como um lead poderá influenciar uma cadeia de funcionalidades.

A cadeia de funcionalidades que influencia um lead é:

  • Empreendimentos - um lead pode possuir um, vários ou nenhum empreendimento associado.
  • Responsáveis - um lead pode possuir como responsáveis: (1) um gestor [usuário administrativo]; (2) uma imobiliária; e (2) um corretor, desde que esteja associado à imobiliária do lead.
  • Simulações - um lead pode possuir uma, várias ou nenhuma simulação associada.
  • Reservas - um lead pode possuir uma, várias ou nenhuma reserva associada.
  • Pré-cadastros - um lead pode possuir um, vários ou nenhum pré-cadastro associado.
  • Contatos - um lead pode possuir um, vários ou nenhum contato associado.
  • Interações - um lead pode possuir uma, várias ou nenhuma interação cadastrada.
  • Conversões - um lead pode possuir uma, várias ou nenhuma conversão cadastrada.

1.4 Pré-requisitos

Alguns pré-requisitos precisam ser obrigatoriamente atendidos:

  • Situações - Precisam existir situações ativas com flag 'Início', 'Cancelado' e 'Fim'.

  • Permissão - Para editar um lead o campo 'permitir_alteracao' precisa existir no JSON da requisição e ter o valor 'true'.

2 ESPECIFICAÇÕES DAS AÇÕES

2.1 Cadastro de leads

O cadastro de um lead é efetuado utilizando dois campos principais: (1) e-mail; (2) telefone. Um lead pode ser cadastrado mediante a três situações desses campos: (1) com e-mail e telefone; (2) apenas com e-mail; (3) apenas com telefone.

O telefone pode ser enviado com o DDI do país ou não, caso o código não seja informado será considerado o DDI do Brasil. O campo deve ser informado da seguinte forma nomedocampo_ddi, e no valor é sempre necessário colocar o simbolo de mais (+). Exemplo: 'telefone_ddi' : '+55', 'telefone_alternativo_ddi' : '+71'.

Caso o JSON da requisição de cadastro do lead possua apenas o campo “e-mail”, o lead é cadastrado deixando o campo “telefone” vazio e o campo “e-mail” será sua chave. Não podem existir dois ou mais leads no sistema que tenham o mesmo e-mail.

Caso o JSON da requisição de cadastro do lead possua apenas o campo “telefone”, o lead é cadastrado deixando o campo “e-mail” vazio e o campo “telefone” será sua chave. Não podem existir dois ou mais leads no sistema que tenham o mesmo número de telefone.

2.2 Situação

Ao cadastrar um novo lead é verificado se o JSON da requisição possui o campo “idsituacao”: (1) caso o campo não exista ou o valor seja nulo, vazio ou numérico sem que esse ID retorne uma situação ativa, a situação do lead será cadastrada com a flag “Início”; (2) caso o valor seja numérico e o ID de uma situação ativa, a situação do lead será cadastrada com a flag “Início” e em seguida alterada para o novo valor enviado.

Ao editar um lead é verificado se o JSON da requisição possui o campo “idsituacao”: (1) caso o campo não exista ou o valor seja nulo, vazio ou numérico sem que esse ID retorne uma situação ativa (1.1) e a situação atual do lead seja “Cancelado”, então a situação do lead será modificada para “Início” se não possuir responsável; (1.2) e a situação atual do lead seja diferente de “Cancelado”, a situação permanece a mesma; (2) caso o valor seja numérico, a situação do lead deve ser modificada para o novo valor enviado.

2.3 Empreendimentos

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “idempreendimento” preenchido. Caso exista um ou mais valores, adiciona ao lead apenas os valores que estiverem ativos tanto no banco de dados quanto no painel.

2.4 Unidades

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “idunidade” preenchido. Caso exista e esteja ativo é adicionado ao lead, assim como o “idempreendimento” desta unidade.

2.5 Responsável

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “idusuario” preenchido: (1) caso a requisição tenha sido enviada pelo módulo “gestor”, adiciona o novo gestor ao lead; (2) caso a requisição tenha sido enviada pelos módulos “imobiliária” ou “corretor”, segue para a verificação do próximo campo.

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “idimobiliaria” preenchido: (1) caso a requisição tenha sido enviada pelo módulo “gestor”, adiciona a nova imobiliária ao lead; (2) caso a requisição tenha sido enviada pelos módulos “imobiliária” ou “corretor”, segue para a verificação do próximo campo.

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “idcorretor” preenchido: (1) caso a requisição tenha sido enviada pelos módulos “gestor” ou “imobiliária”, se o corretor estiver vinculado a imobiliária, adiciona o novo corretor ao lead; (2) caso a requisição tenha sido enviada pelo módulo “corretor”, segue para a verificação do próximo campo.

Se for uma reativação a situação poderá ser alterada para 'Enviado Gestor/SDR', 'Enviado Imobiliária' ou 'Enviado Corretor'.

2.6 Reservas

Ao cadastrar um novo lead ou editar um lead existente é verificado se o e-mail ou o telefone no JSON da requisição pertence a alguma reserva existente no sistema CV, seja como titular ou associado da mesma. Existindo uma ou mais reservas elas são associadas ao lead.

Durante essa ação, a situação do lead só será alterada para “Reserva”, caso uma das reservas associadas tenha a situação diferente de: (1) Distrato; (2) Cancelada; ou (3) Vencida. Havendo uma reserva com situação igual a “Vendida” e o ano da venda sendo igual ao ano de cadastro do lead, a situação do lead será alterada para “Fim”.

2.7 Pré-cadastros

Ao cadastrar um novo lead ou editar um lead existente é verificado se o e-mail ou o telefone no JSON da requisição pertence a algum pré-cadastro existente no sistema CV, seja como titular ou associado do mesmo. Existindo um ou mais pré-cadastros eles são associados ao lead.

Durante essa ação, a situação do lead só será alterada para “Pré-cadastro”, caso um dos pré-cadastros associados tenha a situação diferente de: (1) Fim; ou (2) Cancelado.

2.8 Origem

Ao cadastrar um lead: (1) caso seja enviado o campo “origem” no JSON da requisição, ele será cadastrado como a origem do lead; (2) caso não exista uma “origem” no JSON da requisição, se existir o campo 'modulo', recebe esse valor, se não existir, recebe o valor padrão do sistema (ND).

Desta forma, a “origem” de um lead sempre será preenchida. A origem de um lead é única e não pode ser editada.

Ao editar um lead, caso seja enviado o campo “origem” no JSON da requisição, ele deve ser tratado como a origem de uma conversão, se existir o campo “conversao”.

2.9 Conversão

Ao cadastrar um lead, uma “conversão” pode ser enviada no JSON da requisição. Caso seja enviada uma “conversão”, sua origem será a mesma origem do lead.

Ao cadastrar ou editar um lead, caso seja enviada uma “conversão” que ainda não exista no sistema, ela será cadastrada. Existe um CRUD para registrar conversões. Se uma conversão for enviada no JSON da requisição com o nome diferente de alguma conversão já registrada no sistema, então ela será cadastrada como uma nova conversão.

Ao editar um lead, uma “conversão” pode ser enviada no JSON da requisição: (1) caso seja enviado um campo “conversão” e um campo “origem”, essa origem deve ser tratada como a origem da conversão; (2) caso seja enviada uma “conversão” sem uma “origem”, se existir o campo 'modulo', recebe esse valor, se não existir, recebe o valor padrão do sistema (ND).

2.10 Interações

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “interacoes” preenchido. Caso exista um ou mais valores, adiciona a(s) interação(ões) ao lead, com seus respectivos valores de “tipo” e “descricao”, obrigatoriamente. A descrição possui limite máximo de 32000 caracteres.

*Tipos: 'A' - 'Anotação' / 'L' - 'Ligação' / 'E' - 'E-mail' / 'S' - 'SMS' / 'W' - 'Whatsapp'.

*Situações do tipo Ligação: 'A' - 'Atendida' / 'NA' - 'Não Atendida' / 'NE' - 'Não Existe'.

Ao cadastrar a nova interação é verificado a existência do campo “audio_url” ou “audio_base64”. Caso exista é adicionado um áudio a interação. *Extensões permitidas: 'mp3', 'ogg' e 'wav'.

Logo após é verificado se a interação possui o campo “tarefa” preenchido. Caso exista, adiciona a tarefa, com seus respectivos valores obrigatórios de “nome”, “data”, “situacao”, “prioridade”, “tipo_responsavel” e “idresponsavel” e opcional de “lembrete_tarefa” ('S' - 'Sim' / 'N' - 'Não').

*Situações: 'P' - 'Pendente' / 'C' - 'Concluído' / 'A' - 'Em andamento' / 'CA' - 'Cancelado'.

*Prioridades: 'A' - 'Alta' / 'N' - 'Normal' / 'B' - 'Baixa'.

*Tipo do responsável: 'G' - 'Gestor' / 'C' - 'Corretor' / 'I' - 'Imobiliária' / 'P' - 'PDV'.

2.11 Visitas

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “visita” preenchido. Caso exista um ou mais valores, adiciona a(s) visita(s) ao lead, com seus respectivos valores de “nome”, “data”, “idresponsavel” e “tipo_responsavel”.

*Outros campos permitidos: “descricao”, “situacao” ['P' - 'Pendente' (valor padrão) / 'A' - 'Em Andamento' / 'C' - 'Concluído' / 'CA' - 'Cancelado'], “idpdv”, “visita_virtual” ['S' - 'Sim' / 'N' - 'Não'] e “idtipovisita”.

Durante essa ação, se a automatização de leads estiver ativa, a situação do lead será alterada para “Visita Agendada”, caso a situação da visita seja 'Pendente' ou 'Em Andamento' ou para “Visita Concluída”, caso a situação da visita seja 'Concluído'.

2.12 Avatar

Ao cadastrar um novo lead ou editar um lead existente, a imagem do avatar pode ser alterada por integração, via URL (endereço da imagem).

2.13 Ponto de Venda

Ao cadastrar um novo lead ou editar um lead existente é verificado se o JSON da requisição possui o campo “idpdv” preenchido. Neste caso não existe uma verificação específica e o PDV é cadastrado no lead.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
≤ 100

Endereço de e-mail cadastrado no lead. *Observação: Será obrigatório se não for passado nenhum valor no campo 'telefone'.

string
required
≤ 15

Número de telefone cadastrado no lead. *Observação: Será obrigatório se não for passado nenhum valor no campo 'email'.

string
≤ 15

Código de país de cadastro de telefone no lead. *Observação: Se não passado nenhum valor será considerado DDI do Brasil.

string
≤ 100

Trata a origem como vindo de um dos painéis caso não venha nenhuma outra origem na API.
*Para que o link de resposta da requisição gerado seja válido, deve ser passado o campo modulo.

string
≤ 100

Nome do cliente do lead.
*Observação: No cadastro, se não for passado nenhum valor receberá 'Sem nome'. Não será permitida a alteração do nome se não for passado nenhum valor no parâmetro origemcv.

boolean

Permite alterar / incluir informações no lead, caso o lead já exista.
*Observação: Obrigatório na alteração do lead.

integer
≤ 10

codigointerno do lead.
*Observação: Não será permitido o cadastro/edição se o codigointerno informado estiver associado a outro lead.

integer
≤ 10

ID do lead que será editado.

integer
≤ 10

Ponto de venda associado ao lead.
*Pode ser enviado apenas um ID.

string
≤ 45

Slug da mídia que está gerando o lead.
*Observação: Caso não exista uma mídia cadastrada com o slug informado, será cadastrada uma nova mídia.

integer
≤ 10

ID da mídia que está gerando o lead.
*Observação: Será sobreposto pelo campo midia, caso ambos sejam informados.

integer
≤ 10

ID do motivo de escolha do empreendimento.
*Pode ser enviado apenas um ID.

integer
≤ 10

ID do usuário administrativo que será vinculado ao lead como responsável (Gestor).

string
≤ 100

E-mail do usuário administrativo que será vinculado ao lead como responsável. Uma alternativa para caso o usuário não saiba qual id de usuário administrativo passar.

integer
≤ 10

ID da imobiliária que será vinculada ao lead como responsável.

string

Data em que a imobiliária foi vinculada ao lead.

integer
≤ 10

ID do corretor que será vinculado ao lead como responsável. No entanto, o corretor só será adicionado ao lead se passar também o idimobiliaria.

string
≤ 100

E-mail do corretor que será vinculado ao lead. Uma alternativa para caso o usuário não saiba qual id de corretor passar.

string

Data em que o corretor foi vinculado ao lead.

string
≤ 100

Endereço de e-mail alternativo cadastrado no lead.

string
≤ 15

Número de telefone alternativo cadastrado no lead.

string
≤ 15

Código de país de telefone alternativo. *Observação: Se não passado nenhum valor será considerado DDI do Brasil.

string
≤ 4

Tipo do documento cadastrado no lead.
*Opções: 'cpf' / 'cnpj'

string
≤ 20

Documento cadastrado no lead.
*Observação: Será sobreposto pelo campo 'documento_cnpj', caso ambos sejam informados.

string
≤ 20

Documento cadastrado no lead.

string
≤ 1

Sexo cadastrado no lead.
*Opções: 'M' / 'F'

string
≤ 10

Renda familiar cadastrada no lead.

string
≤ 9

CEP cadastrado no lead.

string
≤ 100

Endereço cadastrado no lead.

string
≤ 10

Número cadastrado no lead.

string
≤ 100

Complemento cadastrado no lead.

string
≤ 100

Bairro cadastrado no lead.

integer
≤ 10

ID do estado cadastrado no lead.

integer
≤ 10

ID da cidade cadastrada no lead.

integer
≤ 10

ID da situação do lead.

string
≤ 100

Motivo de cancelamento do lead.
*Observação: Caso não exista uma motivo cadastrado com o nome informado, será cadastrado um novo motivo. Somente será inserido se o idsituacao informado for de situação cancelada.

string
≤ 100

Descrição do motivo de cancelamento do lead.
*Observação: Esse campo é obrigatório caso o motivo de cancelamento cadastrado tenha descrição como obrigatória.

string
≤ 100

Submotivo de cancelamento do lead.
*Observação: Caso não exista um submotivo cadastrado com o nome informado, não será cadastrado um novo submotivo. Somente será inserido se o idsituacao informado for de situação cancelada.

string
≤ 2

Origem (ID) do lead.
*Opções: 'AP' - 'Aplicativo' / 'AT' - 'Módulo de Atendimento' / 'BC' - 'Busca Compartilhada' / 'BO' - 'Busca Orgânica' / 'CH' - 'Chat Online' / 'CB' - 'ChatBot' / 'DP' - 'Display' / 'EM' - 'Email' / 'FB' - 'Facebook' / 'GO' - 'Google' / 'IT' - 'InstaPage' / 'IG' - 'Instagram' / 'LI' - 'Ligação' / 'LK' - 'LinkedIn' / 'MP' - 'Mídia Paga' / 'OP' - 'Outras publicidades' / 'CL' - 'Painel Cliente' / 'CO' - 'Painel Corretor' / 'GE' - 'Painel Gestor' / 'IM' - 'Painel Imobiliária' / 'PV' - 'Painel PDV' / 'PT' - 'Phonetrack' / 'PO' - 'Portais' / 'RF' - 'Referência' / 'SC' - 'Social' / 'TD' - 'Tráfego Direto' / 'TW' - 'Twitter' / 'SI' - 'WebSite' / 'UK' - 'Desconhecido' / 'ND' - 'Não Definido' / 'VO' - 'Vendas Online' / 'RM' - 'Remarketing' / 'PR' - 'Pinterest' / 'TT' - 'Tik Tok' / 'CV' - 'CVCRM' / 'WA' - 'Whatsapp' / 'OU' - 'Outros' / 'AV' - 'Avendre'. Caso não seja enviado no JSON da requisição, se existir o campo 'modulo', recebe esse valor, se não existir, recebe o valor padrão do sistema (ND).

string

Data de vencimento do lead.
*Observação: Essa data poderá ser alterada caso o lead seja associado à responsáveis provenientes de filas.

string
≤ 100

Perfil da rede social Facebook do lead.

string
≤ 100

Perfil da rede social Twitter do lead.

string
≤ 100

Perfil da rede social Instagram do lead.

string
≤ 100

Foto ou logo do cliente do lead. Enviado através de URL.

integer
≤ 10

O empreendimento de interesse do lead.
*Observação: Pode ser enviado uma lista com o(s) empreendimento(s) de interesse do lead. Exemplo: [2, 3]

integer
≤ 10

A unidade de interesse do lead.
*Observação: O empreendimento da unidade também será incluído como interesse do lead.

integer
≤ 10

ID de reserva que será associada ao lead. No caso do cadastro também será o ID da reserva que iniciou o cadastro do lead.

integer
≤ 10

ID de pré-cadastro que será associado ao lead. No caso do cadastro também será o ID do pré-cadastro que iniciou o cadastro do lead.

boolean

Informa se será permitida a troca de atendente (gestor, corretor e/ou imobiliaria) do lead.
*Observação: Caso o valor seja 'false' e o lead já tenha gestor, corretor e/ou imobiliária, esses serão mantidos mesmo que novos valores tenham sido enviados para a API.

boolean

Informa se não ocorrerá associação do lead a gestor, corretor e/ou imobiliária.
*Observação: Caso o valor seja 'true' e o lead já tenha gestor, corretor e/ou imobiliária, esses serão mantidos mesmo que novos valores tenham sido enviados para a API.

boolean

Informa se será utilizada fila de distribuição de leads de gestor.

boolean

Informa se será utilizada fila de distribuição de leads de imobiliárias e corretores.
*Observação: Substitui a variável da configuração.

boolean

Informa se será utilizada fila de distribuição de leads de imobiliárias e corretores.

integer

ID da fila de distribuição de leads, caso seja informado o lead entrará na fila sem verificar as regras.

boolean

Informa se será ignorado o envio de email de cadastro do lead.

string
≤ 100

Nome da fonte de uma nova entrada de um lead existente.
*Observação: Se não for informado receberá o valor padrão do 'modulo', se existir.

string

Data que a conversão do lead foi cadastrada.
*Observação: Deve ser enviado no formato BR.

boolean

Informa se a conversão será cadastrada.

string
≤ 2

Integração que está gerando o lead.
*Opções: 'RD' - 'RD Station' / 'SS' - 'SharpSpring' / 'FB' - 'Facebook'.

string
≤ 100

ID do lead na base de integração que está gerando o cadastro.

integer
≤ 10

ID do formulário de integração Facebook.

boolean

O valor 'false' informa que o lead não será reativado.

boolean

O valor 'true' sempre irá pegar o último da ordem da fila de distribuição.

boolean

O valor 'true' força a pegar o gestor ou o corretor que esteja online em alguma fila de distribuição.

boolean

O valor 'true' vai mudar a ordem do corretor para último.

boolean

O valor 'true' ao receber um post de lead não dispara webhook.

integer

Possibilidade de venda do lead.
*Observação: Deve ser um valor entre 1 e 5.

campos_adicionais
object

O(s) campo(s) extra(s) e seu(s) respectivo(s) valor(es), cadastrado(s) por uma construtora.

interacoes
array of objects

As interações que foram efetuadas no lead. Pode conter uma array com informações de tarefas agendadas para essa interação.
*Array de arrays contendo obrigatoriamente os campos:
'tipo',
'descricao',
'tarefa': uma array contendo obrigatoriamente os campos:
'nome',
'data',
'situacao',
'prioridade',
'tipo_responsavel'.

interacoes
visita
array of objects

As visitas agendadas no lead.
*Array de arrays contendo obrigatoriamente os campos:
'nome',
'data',
'tipo_responsavel',
'idresponsavel'.

visita
tags
array of strings

Array com a(s) tag(s) do lead.

tags
idproduto
array of int64s

Array com o(s) ID(s) do(s) Produto(s) do lead.

idproduto
produto
array of strings

Array com o(s) nome(s) do(s) Produto(s) do lead.
*Observação: Caso não exista um produto com este nome, será cadastrado.

produto
boolean

O valor 'true' remove gestor do lead.

boolean

O valor 'true' remove imobiliária e o corretor do lead.

boolean

O valor 'true' remove corretor do lead.

integer

Id do momento do lead.
*Observação: Caso não exista um momento com este id ou não possua os empreendimentos e situação associados ao lead, não será atualizado.

boolean

O valor 'true' força a redistribuição do lead, alterando o atendente, mesmo que já exista um atendente atribuído, independentemente de ser um novo cadastro ou uma reativação.

string

Resumo do lead.

Headers
string
required
string
required
string
Responses

Updated 11 days ago

Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 11 days ago