Instruções para implantação da API de Cliente Potencial (Negociações) do CRM | Central de Ajuda Conexa
Ir para Conexa
Todas as coleções
CRM
Instruções para implantação da API de Cliente Potencial (Negociações) do CRM
Instruções para implantação da API de Cliente Potencial (Negociações) do CRM
API CRM
Escrito(a) por Hanna Carvalho
Atualizado(a) há mais de uma semana
Este manual tem por objetivo instruir desenvolvedores WEB a integrar o módulo de Cadastro de Cliente Potencial do Conexa em sua página. Para que isso seja possível, o desenvolvedor deverá seguir as regras para a comunicação com a API responsável por realizar a comunicação com o Conexa e cadastro das informações.
Com este módulo, clientes potenciais poderão se cadastrar no Conexa sem precisar que um usuário os cadastre. Pelo site de sua própria empresa, um potencial cliente (prospect) que esteja interessado em se tornar de fato um cliente, poderá realizar o seu cadastro preenchendo o formulário e automaticamente ele já fará parte de sua base de clientes em potencial do Conexa.
🟡 OBS: O funcionamento desta API consiste em receber os dados que o seu cliente potencial/prospect preenche no formulário. Qualquer observação referente à formatação do próprio formulário (como inserção de recursos como Recaptcha) é de responsabilidade de quem realizou tal integração no seu site);
Para fazer o download da API, acesse: https://conexa.app/download/apis/exemplo-form-api-crm.zip
1️⃣ Comunicação com a API
Para se comunicar com a API, basta enviar os dados necessários por meio dos métodos GET e POST. Essa comunicação ocorrerá em dois momentos:
Utilização do método GET para obter os dados do Conexa que serão apresentados aos usuários, onde ele deverá optar por uma das opções disponíveis.
Submeter o formulário utilizando o método POST.
Para realizar a comunicação, seja para obtenção das informações ou submeter o relatório, um Token deverá ser enviado junto com a requisição como forma de segurança e validação. No primeiro momento, o método GET deverá conter em sua URL o Token, sendo que esse Token deverá ser validado. Se o Token estiver correto, as informações serão retornadas em formato JSON, onde deverá ser tratada pelo programador front-end para que seja exibida de forma correta para os clientes. As informações retornadas em formato JSON estão na seguinte ordem.
empresas
usuário responsável
parceiro/origem
status
forma de contato
serviço de interesse
ramo de atividade
O modelo da requisição, supondo que o Token seja c61312e5032b2fe72b05ce8617aedc1d, deverá seguir esse modelo de URL: https://MEUDOMINIO.conexa.app/index.php?r=configuracoes/crmApi/getInformacoes&token=c61312e5032b2fe72b05ce8617bedc1d. Onde MEUDOMINIO é o domínio do sistema e varia a depender do nome da empresa. O Token deverá ser anexado após “&token=”.
Ao submeter o formulário, o Token deverá vir junto com o formulário submetido via método POST, em um input do tipo hidden pois ele não precisa ser exibido para o cliente. A URL para a submissão do formulário deverá ser http://MEUDOMINIO.conexa.app/index.php?r=configuracoes/crmApi/cadastrar.
2️⃣ Configurações do Formulário
Quanto às informações que deverão compor o formulário, algumas devem ser obrigatoriamente preenchidas pelo usuário, caso contrário o cadastro não será realizado com sucesso. São elas:
Empresa
Parceiro/Origem
Nome para Contato
Telefone
Quanto às outras opções, elas são opcionais e o sistema não acusará nenhum problema caso não sejam preenchidas. Se deseja tornar essas informações obrigatórias, o desenvolvedor deverá determinar isso no Front-end.
Ao submeter o relatório, os names dos inputs preenchidos pelo usuário deverão seguir o modelo abaixo:
Informações
Names
Observações
Empresa
ClientePotencial[idEmpresa]
No sistema, você poderá identificar o id das unidades/empresa em Config > Unidades > Ações > Exibir.
Usuário Responsável
ClientePotencial[idUsuarioResponsavel]
No sistema, você poderá identificar o id do usuário em Config > Usuários > Listar > Ações > Exibir.
Parceiro
ClientePotencial[idParceiro]
No sistema, você poderá identificar o id do parceiro em CRM > Listar Negociações > Outros Cadastros > Parceiro/Origem.
Status
ClientePotencial[idStatus]
No sistema, você poderá identificar o id do status em CRM > Listar Negociações > Outros Cadastros > Status.
Forma de Contato
ClientePotencial[idFormaContato]
No sistema, você poderá identificar o id da forma de contato em CRM > Listar Negociações > Outros Cadastros > Forma de Contato.
Serviço de Interesse
ClientePotencial[servicosInteresse][]
No sistema, você poderá identificar o id do serviço de interesse em CRM > Listar Negociações > Outros Cadastros > Serviço de Interesse.
Ramo de Atividade
ClientePotencial[idRamoAtividade]
No sistema, você poderá identificar o id do ramo de atividade em CRM > Listar Negociações > Outros Cadastros > Ramo de Atividade.
Nome
ClientePotencial[nomeEmpresa]
Informação preenchida pelo seu cliente.
Nomes para Contato
ClientePotencial[nomesContato]
Informação preenchida pelo seu cliente.
Telefones
TelefoneClientePotencial[telefone][]
Informação preenchida pelo seu cliente.
E-mails
ClientePotencial[emailsArray][]
Informação preenchida pelo seu cliente.
Site
ClientePotencial[site]
Informação preenchida pelo seu cliente.
Observações
ClientePotencial[observacoes]
Informação preenchida pelo seu cliente.
Observação: Os campos E-mails, Serviço de Interesse e Telefones deverão estar em formato de array, pois poderá haver mais de um e-mail, mais de um serviço de interesse ou mais de um telefone.
Dica: Não é necessário que todos os campos que serão enviados para o Conexa estejam visíveis em seu formulário. Os campos empresa, usuário responsável, parceiro, status, etc, por exemplo, podem ser um input oculto (hidden) cujo valor é especificado por você no próprio HTML. Além disso, você pode personalizar os nomes dos campos (labels) do seu formulário com os nomes que desejar.
3️⃣ Retorno na submissão do formulário
Ao submeter o formulário, uma resposta será enviada de volta, seja informando que o cadastro foi realizado com sucesso ou que algum erro ocorreu. As mensagens que podem ser retornadas estão na tabela abaixo.
Mensagem
Código
Cadastro realizado com sucesso
0
Token Inválido ou nulo
1
Campo Empresa não preenchido ou não existente
2
Campo Parceiro não preenchido
3
Campo Nomes para contato não preenchido
4
Erro no campo Telefone
5
Uma observação importante a ser feita é que o campo Telefone deverá ser submetido apenas com números e ter exatamente 10 dígitos (DDD+número). Exemplo: 7599999999.
4️⃣ Gerando o Token
Para gerar o Token, algum usuário com permissão de administrador deverá acessar o Conexa, acessar a página API/Token através do menu Config. > Integrações > API / Token. Se já existir um token para a API de Cliente Potencial, basta copia-lo. Para criar um novo token, clique em Novo Token, selecione a API e clique em Gerar Token.
5️⃣ Modelo de formulário Html e Javascript Nativo
O formulário criado em exemplo-form-api-crm.html já possui uma estrutura pronta para que o cadastro seja realizado e foi criado utilizando HTML e Javascript sem qualquer tipo de framework, isso significa que ele poderá ser copiado para o código do seu site e pode ser estilizado como você preferir.
Basta apenas substituir o domínio e o token na linha em que possui:xhttp.open("GET",http://MEUDOMINIO.conexa.app/index.php?r=configuracoes/crmapi/getInformacoes&token=c61312e5032b2fe72b05ce8617aedc1d", true);
Substituir o domínio na linha em que possui:<form class="form-basic" id="cliente-potencial-form" action="http://MEUDOMINIO.conexa.app/index.php?r=configuracoes/crmapi/cadastrar" method="post" >
Substituir o token na linha:<input name="c61312e5032b2fe72b05ce8617aedc1d" id="token" type="text" value="token" hidden>
E substituir a URL (www.conexa.app) de redirecionamento na linha que possui:<input name="urlDestino" id="urlDestino" type="text" value="www.conexa.app" hidden>
6️⃣ Considerações Finais
É necessário que o charset do seu documento HTML esteja com a codificação UTF-8 para que não haja erros de caracteres ao submeter o formulário.