O CXM de Atendimento possui uma API aberta, ou seja, é possível adicionar, alterar, consultar e remover informações do CXM utilizando o token de um usuário administrador.

A documentação completa da API do CXM de Atendimento está disponível clicando aqui.

TÓPICOS DO ARTIGO

  1. O que é uma API
  2. Como consumir uma API
  3. Estrutura de uma requisição
  4. Por que usar uma API?

O QUE É UMA API?

API é um acrônimo para Application Programming Interface , ou, em português, Interface de Programação de Aplicativos.

O intuito de uma API é trocar dados entre sistemas diferentes. Na maior parte das vezes, essas trocas de dados tem como objetivo automatizar processos manuais e/ou permitir a criação de novas funcionalidades. Resumidamente, uma API funciona como uma “ponte” que permite a conexão entre um dispositivo de um solicitante e um específico banco de dados.


Por meio de APIs, desenvolvedores podem criar novos softwares e aplicativos capazes de se comunicar com outras plataformas.

Por exemplo: através da API do CXM de atendimento é possível que através de uma ação executada em um CRM seja disparada uma campanha para envio de mensagens HSM para os leads.

Ou então: toda vez que um lead  for cadastrado no CRM, este cadastro pode ser enviado para o CXM de atendimento.

COMO CONSUMIR UMA API?

Para consumir uma API é necessário realizar uma requisição.

A requisição pode ser realizada tendo os seguintes itens na sua estrutura:

  • Uma URL apontando para o recurso a ser consumido (também conhecido como endpoint);
  • Parâmetros query string para realizar buscas;
  • Método de requisição (são os famosos "verbos");
  • Header e body, caso precise criar ou alterar alguma informação no banco de dados.

A API sempre retornará um status code informando a situação da requisição. Se ela foi bem sucedida, se não foi permitida, se o endpoint não existe, etc.

ESTRUTURA DE UMA REQUISIÇÃO

Uma requisição possui alguns elementos na sua estrutura. São eles:

Confira sobre cada um abaixo

URL

Na requisição, é necessário utilizar um URL. Ele é composto por:

  • Base URL

Esse é o início do URL da requisição. Aqui você basicamente especificará a informação de domínio que se repete em qualquer requisição. Digamos que você queira utilizar a API do CXM de atendimento, então:

https://{subdominio}.cxm.pipe.run/

O subdomínio é o nome da sua empresa, por exemplo: https://crmpiperun.cxm.pipe.run/

  • Resource (ou Path)

O recurso (resource) é a rota para o tipo de recurso que você quer que a API acesse.

Por exemplo: vamos simular que desejamos atualizar o cadastro de cliente , então acrescentamos o recurso customers à base URL:

https://{subdominio}.cxm.pipe.run/api/customers
  • Query String

Query string são os parâmetros de busca da requisição.

Por exemplo: para buscar um cliente com um determinado número de documento.

?search=document_number:12312312387

e nossa URL ficaria assim:

https://{{subdomain}}.cxm.pipe.run/api/v2/customers?search=document_number:12312312387

Como podem ver, por se tratar de parâmetros de busca da URL você usa o "?" antes de especificar o parâmetro e caso queira utilizar mais de um parâmetro você utiliza o "&" para separar os parâmetros. O campo searchJoin pode ser "AND" ou "OR".

Veja um exemplo de como buscar uma organização pelo número de documento e nome fantasia:

https://{{subdomain}}.cxm.pipe.run/api/v2/customer_organizations?search=document_number:01619946000101;trade_name:CONST&searchJoin=AND
Dica: é possível filtrar por  trade_name (nome fantasia) ou legal_name (razão social).
Embora o exemplo utilizado acima foi o de uso de filtro, a Query String não é utilizada somente para filtros. Ela pode ser utilizada como parâmetro de paginação, versionamento, ordenação, relações, etc.

MÉTODO

O método serve para informar o tipo de ação que você quer fazer na requisição.

Dentre os principais métodos, temos:

  • GET (Buscar dados);
  • POST (Enviar dados);
  • PUT e PATCH (Atualizar dados);
  • DELETE (Deletar dados).

Existem vários outros métodos que não serão citados no artigo. Nesse link você pode conferir a lista completa.

HEADERS

Headers, ou cabeçalhos da requisição permitem que você envie informações adicionais à requisição. Ele pode ser utilizado para inúmeras funções, como: autenticação de usuário, formatação de objeto, etc.

No caso da API do CXM, é necessário utilizar o token da conta para autenticação ao realizar as requisições. Caso o token não seja informado, o acesso ao recurso que está sendo requisitado não será permitido.

Para saber como gerar o token de integração acesse este artigo.

BODY

O body é o corpo da requisição que você quer enviar na requisição. Ele é utilizado somente nos métodos de POST, PUT e PATCH. Não é necessário em métodos de leitura de dados (como o GET).

Por exemplo: digamos que você queira adicionar um mailing via API no CXM de atendimento. Neste caso, utilizando o método POST, os dados que serão adicionados deverão ir no body da requisição, como o nome do mailing, ID da fila de atendimento e Arquivo CSV do mailing em formato Base64 com descritor. Algumas informações são obrigatórias. Você pode conferir essas informações na documentação da API do PipeRun.

HTTPS STATUS CODE

Para facilitar o entendimento das respostas das APIs existem padrões de códigos de status que podem ser utilizados.

Os códigos mais utilizados para as respostas de uma requisição são o 200 ("Ok"), o 201 ("Created"), o 204 ("No content"), o 404 ("Notfound"), o 400 ("Bad request"), e 500 ("Internal server error").

Existem vários outros códigos de resposta do protocolo HTTP que podem ser utilizados. Neste link temos a lista completa.

AUTENTICAÇÃO

Não podemos falar de APIs sem falar de segurança, afinal estamos falando de serviços WEB.

Como principais métodos de autenticação de APIs, temos:

  • Basic authentication: Baseado em usuário e senha codificados em Base64 e utilizado no header da requisição;
  • Secret token;
  • Token de acesso que pode ser limitado a escopo, e que é enviado na requisição pelo Header ou pela Query String. Nesse caso temos padrões famosos como o Auth e JWT.
Geralmente, as APIs possuem documentação para que o usuário possa entender seu funcionamento. Sempre leia a documentação antes de utilizar uma API. Clique aqui para conferir a documentação da API do PipeRun.

POR QUE USAR UMA API?

Como vimos, uma API pode mudar o dia a dia da empresa, agregando simplicidade, agilidade e automação aos sistemas. No CXM de Atendimento, diversas integrações estão configuradas, buscando trazer facilidade de comunicação entre plataformas diferentes das áreas de marketing e vendas.

Ao centralizar o acesso a funcionalidades específicas, a API viabiliza automação de rotinas (eliminando tarefas manuais e erros), garante escalabilidade ao permitir que novos módulos sejam conectados sem modificar o núcleo do sistema e reforça a segurança por meio de autenticação, controle de permissões e conformidade com legislações de proteção de dados.

Adotar APIs acelera o crescimento, reduz custos operacionais e amplia a competitividade do negócio.

Em caso de dúvidas, chame nossa equipe no chat. 😉