Cadastra Leads

🔒 Autenticação necessária

Esta API utiliza autenticação via e-mail e token nos headers da requisição. Consulte o tutorial completo antes de fazer sua primeira chamada: Como autenticar nas APIs do CV CRM (v1 — E-mail e Token)

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;<br/> (2) Site do cliente;<br/> (3) Integrações - RD Station, Facebook, Contako.<br/>

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.

{
  "email": "nivaldoolivasegundo@gmail.com",
  "telefone": "(79) 98833-0011",
  "telefone_ddi": "+55",
  "modulo": "gestor",
  "nome": "Nivaldo Oliva II",
  "permitir_alteracao": true,
  "codigointerno": 6478776,
  "idlead": 38413,
  "idpdv": 4,
  "midia": "pdv_externo",
  "idmidia": 1,
  "idmotivo_escolha": 2,
  "idusuario": 82,
  "email_gestor": "email_gestor@mail.com.br",
  "idimobiliaria": 2,
  "data_associacao_imobiliaria": "2021-05-04 14:45:00",
  "idcorretor": 4,
  "email_corretor": "email_corretor@mail.com.br",
  "data_associacao_corretor": "2021-05-04 10:45:00",
  "email_alternativo": "nivaldoolivasegundo@hotmail.com",
  "telefone_alternativo": "(79) 98821-3311",
  "telefone_alternativo_ddi": "+71",
  "documento_tipo": "cpf",
  "documento": "609.851.180-24",
  "documento_cnpj": "12.797.150/0001-57",
  "sexo": "M",
  "renda_familiar": "5000",
  "cep": "49043-525",
  "endereco": "Rua A6",
  "numero": "125",
  "complemento": "Casa 2",
  "bairro": "Santa Maria",
  "idestado": 26,
  "idcidade": 4733,
  "idsituacao": 3,
  "motivo_cancelamento": "Localização não atende",
  "descricao_motivo_cancelamento": "Não atende",
  "submotivo_cancelamento": "Cancelamento em lote",
  "origem": "SI",
  "data_vencimento": "2021-08-04 15:05:00",
  "facebook": "https://pt-br.facebook.com/exemplo-perfil-lead",
  "twitter": "https://twitter.com/exemplo-perfil-lead",
  "instagram": "https://www.instagram.com/exemplo-perfil-lead",
  "url_avatar": "url-foto-lead",
  "idempreendimento": 3,
  "idunidade": 82930,
  "idreserva": 5359,
  "idprecadastro": 2596,
  "permitir_trocar_atendente": true,
  "nao_associar_gestor_corretor_imobiliaria": true,
  "lead_utilizar_fila": true,
  "idfila_distribuicao_leads": 33,
  "ignorar_email": true,
  "conversao": "Campanha 2018.10.31",
  "data_cad_conversao": "04/06/2021 14:15:08",
  "converter": true,
  "integracao": "RD",
  "idintegracao": "dc4cd03f-92ef-453a-b070-14c1b50b2782",
  "idformulario": 74,
  "reativar_lead": true,
  "fila_reversa": true,
  "forcar_online": true,
  "atualizar_ordem": true,
  "pausar_hook": true,
  "possibilidade_venda": 1,
  "campos_adicionais": {
    "possui_imoveis": "Sim"
  },
  "interacoes": [
    {
      "tipo": "L",
      "descricao": "Ligar para Alfred Ramos",
      "situacao": "A",
      "audio_base64": "SUQzAwAAAAAAOVRQRTEAA...",
      "tarefa": {
        "nome": "Tarefa ligacao cadastrada por API",
        "data": "2021-02-06 11:00",
        "situacao": "A",
        "prioridade": "A",
        "tipo_responsavel": "G",
        "idresponsavel": 170,
        "lembrete_tarefa": "N"
      }
    }
  ],
  "visita": [
    {
      "nome": "Visita ao PDV",
      "data": "05/01/2022 14:30",
      "situacao": "P",
      "tipo_responsavel": "G",
      "idresponsavel": 170,
      "email_responsavel": "corretor@lead.com.br",
      "idpdv": 14,
      "visita_virtual": "S",
      "idtipovisita": 4
    }
  ],
  "tags": [
    "PRIVILEGIE",
    "Consulta"
  ],
  "idproduto": [
    23,
    51,
    62
  ],
  "produto": [
    "Produto 23",
    "Produto 51",
    "Produto 62"
  ],
  "remover_gestor": true,
  "remover_imobiliaria": true,
  "remover_corretor": true,
  "idmomento_lead": 5,
  "forcar_distribuicao_lead": true,
  "resumo_insight_api": "Resumindo os principais pontos do lead"
}

{
  "codigo": "200",
  "mensagem": "Operação realizada com sucesso."
}