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, clique aqui.
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.
Ex: Caso não esteja no seu documento, adicione a tag <meta charset="UTF-8"> dentro da tag <head>.