Guia Menu Dinâmico - Padrão 55PBX

 

Integração - Padrão 55PBX

Guia de configuração para menus dinâmicos do tipo Padrão 55PBX. Ao decorrer da documentação será explicado todas as possibilidades que este menu dinâmico oferece e como usá-lo.

Podemos criar um menu do tipo Padrão 55PBX após a criação de um menu dinâmico,
acessando o menu de opções “Integração” e selecionando “Padrão 55PBX”
O Padrão 55PBX possui, inicialmente, 4 itens principais para preenchimento e configuração:

● Método de Url;
● Tipo;
● URL;
● Configurar variáveis de envio;

Métodos de URL

Estes métodos de requisição são responsáveis por indicar a ação a ser executada para um dado recurso através da URA:

 

                                               

GET

Essa é a requisição mais comum de todas. Através dessa requisição nós pedimos a
representação de um recurso: que pode ser um arquivo html, xml, json, etc.

POST

O método POST é utilizado quando queremos criar um recurso. Quando usamos POST, os dados vão no corpo da requisição e não na URL.

PUT

Requisita que um recurso seja "guardado" na URL fornecida. Se o recurso já existir, ele
deve ser atualizado. Se não existir, pode ser criado.

PATCH

Assim como o método PUT, serve para atualização de recursos, mas apenas para atualizar partes de um recurso, e não o recurso todo.

DELETE

Exclui o recurso especificado, normalmente através do ID do recurso

 

Tipo

Neste campo é possível definir qual o tipo de autenticação que será utilizada na requisição
a ser efetuada pela URA:

 

                                       

Token

Ao selecionar o tipo Token dois novos campos serão disponibilizados: Header e Token

 

                   

 

Em Header é possível definir o nome do header que receberá o valor do Token, exemplo:
Authorization, x-api-key, etc:

 

                                     

 

Obs: Esses valores normalmente são informados nas instruções da API.

Em Token deve ser informado o valor do token de autenticação. É possível digitar um token fixo ou utilizar um token dinâmico através de uma variável de resposta(normalmente obtida em outra consulta de menu dinâmico) ao selecionar o checkbox “Utilizar variável de resposta”:

 

                                             

Obs: Para utilizar uma variável de resposta como token, primeiro é necessário declará-la
em + Variável de resposta:

 

 

 

Bearer Token

O funcionamento do tipo de autenticação Bearer Token é muito parecido com o tipo Token,a única diferença é que no momento em que a requisição é efetuada, o texto “Bearer” é adicionado antes do Token:

 

Dessa forma, com base no exemplo acima, o envio do Header de autenticação ficaria da seguinte forma:

 

Obs: As instruções de quando um token deve ser enviado como Bearer normalmente são informadas nas instruções da API.

Token Dinâmico

Algumas requisições não requerem um Header de autenticação e acabam passando as
informações no corpo da requisição. O corpo da requisição pode ser configurado em
“Configurar variáveis de envio”

 

                                     

 

Ao clicar nesta opção, um Modal será aberto onde será possível configurar o corpo da
requisição, ou outros Headers, ao clicar em +Adicionar:

 

Obs: Este módulo será melhor detalhado em outro ponto desta documentação!

Exemplo:

No exemplo a seguir, temos uma requisição que gera um token de acesso para autenticar futuras requisições. O token é gerado através da seguinte requisição fictícia:

URL(Endpoint):
https://exemplo.com.br/v1/auth/token
Headers:
N/A
Corpo:
{
"clientId": "73218321787121",
"clientSecret": "2834738173283"
}

Com base nestas especificações, a configuração ficaria desta forma:
Configuração da URL:

 

Configuração do Corpo:

 

Usuário e Senha

Ao selecionar o tipo Usuário e Senha dois novos campos serão disponibilizados: Usuário e Senha:

Quando uma requisição necessita de autenticação através de usuário e senha, basta
informá-los em seus respectivos campos.

 

URL

Neste campo é informado qual é Endpoint ( URL onde um serviço pode ser acessado
através de requisições) em que a requisição será efetuada.

 

                             

 

É possível inserir variáveis da 55PBX na URL em questão ao preceder o nome da variável
com o caractere dois pontos :.

A variável a ser inserida na URL deve obrigatoriamente ser declarada em “Configurar
variáveis de envio”, colocando seu nome nos campo Variável 55PBX e Variável do
Sistema, conforme a seguir:

 

Exemplo:

No exemplo a seguir, o menu dinâmico foi configurado para fazer uma consulta de ticket no zendesk, através do Padrão 55PBX, com base em um número de protocolo digitado em URA e armazenado em uma máscara.

 

Endpoint

O endereço para realizar a busca de um ticket no Zendesk conta com o número do ticket a ser procurado no final da URL:

Obs: Para este exemplo foi utilizado o Zendesk da 55PBX.

https://instancia.zendesk.com/api/v2/tickets/{id_do_ticket}

 

 

1 - O número do ticket é armazenado em uma máscara de nome protocolo:

 

 

2 - O menu dinâmico Padrão 55PBX é configurado e a variável é protocolo é inserida no campo URL, com o caractere dois pontos precedendo seu nome:

 

                           

 

3 - No menu dinâmico, em “Configurar variáveis de envio” a variável é declarada nos dois campos:

 

Com essa configuração, após digitar um número de protocolo em URA, o texto: protocolo será substituído pelo número digitado e a requisição será efetuada:

Exemplo de como a URL ficará(caso seja digitado 5):

https://instancia.zendesk.com/api/v2/tickets/5

Dessa forma, com base no exemplo acima, a busca por ticket será dinâmica, apresentando um resultado diferente para cada protocolo distinto digitado em URA.

Configurar variáveis de envio

Ao clicar em “Configurar variáveis de envio”, um Modal será aberto onde será possível
configurar o corpo da requisição, ou outros Headers, ao clicar em +Adicionar:

 

 

Obs: O campo Variável 55PBX aceita tanto textos fixos quanto variáveis.

● Para utilizar uma variável, basta informar seu nome:

 

                     

 

● Para informar um texto, declare seu valor entre dois caracteres de porcentagem:

 

                           

 

Header

Para configurar um Header basta:

● inserir o seu nome em Variável do Sistema;
● inserir o valor do header em Variável 55PBX;
● Ativar a checkbox Utilizar como Header

 

Exemplo:

 

 

Corpo(Body)

Através do Padrão 55PBX, é possível realizar a configuração de dois tipos de body: JSON e form-urlencoded.

JSON

Para configurar o corpo que será enviado, basta informar em Variável do Sistema o nome da propriedade e em Variável 55PBX o seu valor:

 

                             

Por padrão, a configuração das variáveis permite o envio de um JSON simples, sem
objetos e arrays, ou seja, apenas o JSON em si com suas propriedades.

Os exemplos a seguir demonstram qual é um formato de JSON que é possível ser
configurado no menu:

JSON inválido:
{
"nome": "Fulano de Tal",
"email": [
"contato@55pbx.com",
"fulano@55pbx.com"
],
"telefone": {
"tipo": "celular",
"numero": "5511996523259"
}
}

 

JSON válido
{
"nome": "Fulano de Tal",
"email": "fulano@55pbx.com",
"telefone":"5511996523259"
}

O exemplo a seguir mostra como seria o preenchimento com base no JSON válido citado acima:

 

                                         

 

form-urlencoded

Para configurar um corpo como x-www-form-urlencoded, em configurar variáveis de envio, o checkbox x-www-form-urlencoded deve ser ativado:

 

 

A configuração do corpo segue o mesmo padrão anterior, informando em Variável do
Sistema o nome da chave e em Variável 55PBX o seu valor:

 

 

Retornos

Após realizar uma requisição de busca, atualização ou edição, é esperado que um objeto JSON seja retornado para a URA, com uma série de dados, de acordo com a requisição efetuada. Podemos usar os dados presentes nesse JSON em URA ao declará-los como Variáveis de Resposta.

 

Para utilizar as variáveis em URA, basta informar o nome da propriedade que deseja utilizar com o texto 55pbx inserido no início de toda variável, separando as palavras com_(underline).

Exemplo

Supondo que foi realizada a busca de um usuário, em um determinado sistema através do seu número de telefone, e os seguintes dados foram retornados:
{
"nome": "Fulano de Tal",
"email": [
"contato@55pbx.com",
"fulano@55pbx.com"
],
"telefone": {
"tipo": "celular",
"numero": "5511996523259"
}
}

Acessando propriedade simples:

Para acessar e utilizar uma variável simples, que não esteja dentro de um objeto ou array, basta declarar seu nome com o texto 55pbx precedendo seu valor. No exemplo a seguir, declaramos a variável nome com base no JSON acima:

 

                                         

Acessando array(arranjo)

Ao trabalhar com array, além de incluir o texto 55pbx e separar as palavras com underline, é necessário indicar a posição do dado que desejamos acessar dentro do array. No exemplo a seguir, acessamos o primeiro e-mail do array através do número 0 e o declaramos como uma variável de resposta:

 

Neste caso, o e-mail que estará disponível através da variável 55pbx_email_0 é o:
contato@55pbx.com

Acessando array de objetos

Também é possível acessar propriedades de objetos que estão dentro de arrays, basta
informar o nome da propriedade(separando com underline) após indicar a posição desejada do array. No exemplo a seguir, temos um JSON fictício de um retorno dos e-mails de um contato:
{
"email":[
{
"tipo": "casa",
"endereco": "contato@55pbx.com.br"
},
{
"tipo": "trabalho",
"endereco": "fulano@55pbx.com.br"
}
]
}

 

Com base no exemplo, para declarar uma variável que contenha o tipo do primeiro e-mail do array, a formatação ficaria desta forma:

 

                                             

 

Obs: A primeira posição dos arrays sempre começa no 0.

Acessando objetos

Para utilizar e declarar dados de um objeto, basta informar o nome do objeto e o nome de sua propriedade, separados por underline, conforme as especificações já apresentadas. No exemplo a seguir, declaramos a variável tipo, do objeto telefone, com base no JSON de exemplo: