Instruções para implantação da API de Cliente Potencial (Negociações) do CRM


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.

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:

  1. 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.
  2. 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.

  1. empresas
  2. usuário responsável
  3. parceiros
  4. status
  5. forma de contato
  6. serviço de interesse
  7. 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.
Endereço ClientePotencial[endereco] Informação preenchida pelo seu cliente.
Observações ClientePotencial[observacoes] Informação preenchida pelo seu cliente.

Observação: Os campos E-mails e Telefones deverão estar em formato de array, pois poderá haver mais de um e-mail 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 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.
Caso tenha dúvida o seguinte artigo irá te ajudar: Preciso de uma Api/Token do Conexa para minha integração

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>.