Este tutorial apresenta, de forma detalhada e orientada, o passo a passo completo para realizar a integração com o Pcontrol por meio da API. Seguindo cuidadosamente cada etapa descrita, você aprenderá como configurar corretamente a conexão e enviar contatos de forma automatizada para o sistema, garantindo que a comunicação entre as plataformas ocorra de maneira eficiente, segura e sem falhas.

Cadastrando uma nova API no Pcontrol

1 – No menu superior acesse o menu configurações (ícone de engrenagem) e então clique no link Integração.

2 – No módulo Integrações, clique no botão verde Cadastrar para cadastrar uma nova integração com o Pcontrol.

3 – No tela de seleção de do tipo de integração,  escolha a opção “API”.

4 – Na tela seguinte, digite um nome para a interação preenchendo o campo ““. O campo “Status” deve estar como “Ativo” para que a integração aconteça e o restante dos campos devem ser preenchidos de acordo com a sua estratégia de vendas.

Após preencher todos os campos, revise-os e então clique no botão verde Salvar localizado no final do formulário.

5 – Após o cadastro ser realizado você será redirecionado à tela inicial das integrações. Confira a lista de integrações se a integração foi cadastrada corretamente.

Perceba que há um botão branco, com ícone de olho, Ver Código da Integração. Por favor, clique no botão.

6 – Clicando no botão Ver Código da Integração, será exibido o código JSON que deverá ser utilizado no sistema de interação, o token de sua API e também o endereço de Endpoint que deverá ser utilizado.


Realizando o Teste da API

7 – Vamos utilizar o Postman, plataforma de testes de API para desenvolvedores, para continuar como nosso tutorial. (Você pode escolher outra plataforma de testes de API como o Insomnia, por exemplo).

Independente de qual plataforma de testes de API você escolher, faça as configurações básicas da plataforma antes de continuar este tutorial.

  • Método da requisição deve ser: POST
  • URL (endpoint) de envio da requisição é: https://api.pctrlx.com.br/lead/cadastrar
  • Definir o Auth Type como Bearer Token
  • Colocar o token da API no campo Token do Postman

8- No Postman, cole o código JSON gerado pelo Pcontrol para ser usado como Corpo da requisição.

No código JSON podem ser incluídas as informações de observação, produtos e campos personalizados.


Observação

A observação deve ser inserida como array, com o conteúdo a ser cadastrado colocado entre aspas e cada observação a ser inserida separada por vírgulas:

"observacao": [

    "Contato preferencial: e-mail",

    "Horário de atendimento: 09:00-18:00",

    "Responsável financeiro: Maria Oliveira",

    "Cliente desde 2023"
]

Produtos

Os produtos devem ser inseridas como array, com o SKU relativo ao produto a ser cadastrado na ficha do cliente colocado entre aspas e cada SKU de produto deve ficar separado por vírgulas.

Atenção: Caso o SKU não esteja cadastrado em sua conta do Pcontrol, ou seja enviado código SKU incorreto, o produto não será associado ao lead. 

"produtos": [

    "SKU-001",

    "SKU-015",

    "SKU-RETAIL-02"

  ]

Campos Personalizados

Os campos personalizados devem ser acrescentados ao código JSON da seguinte forma:

"campos_personalizados": {
"total_funcionarios": 25,
"setor": "Comércio varejista"
}

Atenção: Caso o campo personalizado não esteja cadastrado em sua conta do Pcontrol, ou seja enviado nome de campo incorreto, as informações enviadas como campo personalizado não serão associadas ao lead. 

9 – Após seguir fielmente as instruções do passo anterior, envie a requisição através sua plataforma de testes de API:

A mensagem “Dados enviados para fila de cadastro com sucesso” e o “Status Code 200” devem ser exibidos. O lead irá entrar em uma fila, e será cadastrado em alguns minutos. O cadastro não é instantâneo, por isso não irá aparecer no Pcontrol imediatamente após o envio pela API.


Confirmando o Cadastro dos Dados

10 – Voltando ao Pcontrol, os dados enviados via API podem ser verificados na ficha do cliente. Pesquise pelo CNPJ enviado pela API:

11- No resultado, clique em Ficha do Cliente:

12- Observe na ficha do cliente os dados cadastrados, conforme código JSON:

Ao descer a página, pode visualizar as demais informações, como os campos personalizados:

Atenção: Todos os leads enviados via API constarão como origem sempre o nome de sua API. 

13- Clicando na aba Observações da Ficha do Cliente, você poderá visualizar a observação conforme enviada via API:

 

POSSÍVEIS MENSAGENS DE ERRO

11 – Se no corpo da requisição não foi enviado o parâmetro pagina a mensagem “Código da página não encontrado.” e Status Code 400 serão exibidos

12 -Se no corpo da requisição o parâmetro pagina foi enviado em branco a mensagem “Código da página não encontrado.” e Status Code 400 serão exibidos.

13 – Se no corpo da requisição o parâmetro pagina for enviado com um código diferente do que gerado pelo Pcontrol a mensagem “Integração não encontrada.” e Status Code 404 serão exibidos.

14 – Se todos os critérios de envio de uma requisição estiver corretos porém a integração está inativa no Pcontrol a mensagem “Integração inativa.” e o Status Code 404 serão exibidos.

15 – Para verificar o status da Integração acesse o Pcontrol e na tela de integrações e veja na coluna Status o status atual da integração desejada.

16 – Caso a mensagem “Conta Pcontrol inativa ou não encontrada.” com o Status Code 404 sejam exibidos, isto significa que o acesso à sua conta do Pcontrol está inativo.

Neste caso, entre em contato com a equipe de atendimento do Pcontrol para entender o motivo.

17 – Caso necessário, há alguns campos extras que podem ser enviados, os campos são:
● cnpj
● razao_social
● celular

IMPORTANTE:

Todas as mensagens de retorno da API (de sucesso e de erro) devem ser tratadas pelo cliente, o Pcontrol só irá realizar o cadastro de contato se todas as regras apresentadas neste tutorial estiverem validadas, caso contrário uma mensagem de erro com o status code correspondente será retorno ao cliente.

Observações:

  • Caso sejam realizadas várias tentativas de  cadastro de um mesmo CNPJ, será retornado erro conforme abaixo:

  • Caso sejam realizadas mais de 30 requisições dentro de 1 minuto, será exibida mensagem de erro, conforme a imagem:

Caso a mensagem de erro seja exibida, será necessário aguardar 1 minuto para realizar novas requisições.

  • A API possui o limite do payload de envio de 10KB por requisição. Caso seja ultrapassado este limite, será retornadas as informações: 
    • Status Code: 413
    • Mensagem: Content Too Large

 

Como enviar o lead para:

Comments are closed, but trackbacks and pingbacks are open.