Avançar para o conteúdo principal

How to Integrate API and Publish API Data via OptiSync

Integrar sua API com o OptiSigns tem muitos usos e permite a exibição fácil de dados atualizados automaticamente em suas telas. Neste guia, vamos orientá-lo sobre como conectar sua API - nenhuma experiência em engenharia de software é necessária.

NOTA: A Integração de API está disponível apenas com um plano Pro Plus ou superior.

O que a Integração de API Pode Fazer

O OptiSigns permite fácil integração com APIs de usuários. Isso permite que dados da API de um usuário sejam exibidos em qualquer uma de suas telas digitais. Isso permite atualizações dinâmicas para:

  • Menus Digitais - Integre com seus sistemas de PDV e obtenha o menu digital atualizado automaticamente, e edite o formato do seu menu digital usando o aplicativo designer sempre que necessário.
  • Atualizações Automáticas de RH - Use a API dos seus sistemas de RH para exibir aniversários ou aniversários de trabalho nas telas automaticamente.
  • Rastreamento de Inventário de Armazém - Use a API do seu armazém para exibir níveis de inventário com atualizações automáticas em toda a sua organização
  • Quaisquer outros casos de uso de exibição de informações que você precise consumir dados de API e exibir os dados nas telas.

Essa integração de API pode ser alcançada no OptiSigns com pouca ou nenhuma codificação, tornando-a acessível para aqueles sem experiência em engenharia de software. Neste guia, vamos orientá-lo sobre como configurá-la com o exemplo abaixo usando uma API do sistema PDV Clover.

O que Você Precisa para Começar

Você precisará de:

  • URL do Endpoint da API
  • Token de Autorização da API

Estes são necessários para que o OptiSigns se conecte com sua API desejada. Certifique-se de tê-los em um local facilmente acessível antes de tentar configurar sua Solicitação de API no Portal Web do OptiSigns. Você deve poder obtê-los de um profissional de TI em sua organização ou através do administrador do seu sistema de PDV.

Como Configurar uma Solicitação de API

O gateway de API é uma ferramenta poderosa que permite aos usuários gerenciar centralmente as APIs, bem como configurar e testar as APIs.

Agora que você tem tudo o que precisa, vamos começar a configurar uma Solicitação de API. Com uma solicitação de API, você pode:

  1. Usar o Keystore de API do OptiSigns para armazenar e usar com segurança chaves de API de outros sistemas.
  2. Testar os endpoints da API, com a capacidade de modificar cabeçalhos e parâmetros.
  3. Usar parâmetros de substituição e regras de pré-processamento e pós-processamento para lidar com integração complexa. Regras de pré-processamento podem ajudá-lo a lidar com situações de integração de API que requerem uma chamada adicional para obter um token de autenticação antes de fazer a chamada de API. O pós-processamento permitirá que você processe os dados retornados e os adapte para melhor atender ao seu uso.

Para começar, abra seu Portal Web do OptiSigns.

Uma vez lá, navegue até o canto superior direito da tela e passe o mouse sobre o nome da sua conta.

Passe o mouse sobre Mais → Fontes de Dados

Você verá a tela abaixo.

Agora você está pronto para começar.

Passo 1: Armazene Seu Token de Autorização de API no Keystore de API do OptiSigns

O primeiro passo é pegar seu Token de Autorização de API e armazená-lo no Keystore de API do OptiSigns.

Este passo é tecnicamente opcional: você pode inserir seu token de Autorização de API em uma solicitação de API individual. No entanto, o Keystore tem algumas grandes vantagens:

  • Permite que seu token de Autorização de API seja enviado para várias solicitações de API, sem a necessidade de inseri-lo manualmente a cada vez
  • Fornece segurança superior para seu token de Autorização de API, tornando muito mais difícil para atores externos descobri-lo

Portanto, recomendamos fortemente este passo.

Para entrar no Keystore, encontre o Ícone de Cadeado e clique nele.

firefox_YNrLQDITUl.png

Isso abrirá o Keystore de API.

Clique em Adicionar Chave.

firefox_Af1bBuAYxy.png

Há dois campos aqui.

  • Primeiro Campo - Digite o nome da chave aqui. Recomendamos algo que o ajude a lembrá-la. Você usará isso para configurar uma solicitação de API.
  • Segundo Campo - A senha única real para suas comunicações de API.

Depois de inserir seu token de Autorização de API, clique em Salvar. Quando você quiser executar uma solicitação usando esta Chave de API, você usará o termo: {{apiKeystore.<<key>>}} onde "<<key>>" é substituído pelo nome que você inseriu anteriormente. Neste exemplo, nomearemos nossa solicitação "clover".

Agora, estamos prontos para configurar sua solicitação de API.

Passo 2: Configure e Teste a Solicitação de API

Antes de avançar no OptiSigns, recomendamos testar sua API usando uma ferramenta gratuita, como o Postman. Isso oferece várias vantagens, incluindo:

  • Verificar a formatação dos seus dados
  • Garantir que os dados corretos estão sendo fornecidos
  • Verificar sua autenticação
  • Identificar problemas de integração ou erros de conexão

Os parâmetros de teste, endpoints e autenticadores podem então ser usados no OptiSigns para configurar sua solicitação de API. Veja como fazer isso.

firefox_orSTybxxGU.png

Clique no botão Adicionar Solicitação, ele abrirá a janela para você configurar e testar a solicitação de API.

firefox_owER9ex9xQ.png

  • Nome de Exibição - Isso será mostrado na lista do gateway de API, principalmente para ajudar os usuários a identificar a solicitação de API.
  • Nome - Isso é usado como referência para a solicitação de API, é um nome técnico que será usado posteriormente no caminho para se referir aos dados da solicitação de API.
  • URL - Este é o endpoint da API, você pode usar o método GET ou POST dependendo da solicitação de API, por exemplo, se você estiver usando GraphQL, todas as solicitações usarão POST.
  • Parâmetros - Permite definir os parâmetros em sua solicitação de API. Você pode ver parâmetros em sua URL do endpoint da API, estes serão precedidos por uma marca "?". Estes podem ser usados em código de solicitação de pré e pós-processamento para automatizar ainda mais sua solicitação de API.
  • Cabeçalhos - O(s) cabeçalho(s) da solicitação de API. Você deve inserir seu token de Autenticação de API aqui.
  • Pré-solicitação - Um pedaço opcional de código que prepara o contexto antes da solicitação de API. Por exemplo, você pode precisar chamar outra API para obter um token de autenticação de curta duração antes de chamar a API, ou você precisa calcular algumas variáveis a serem usadas na solicitação de API.
  • Pós-solicitação - Um pedaço opcional de código que modifica os dados recebidos da solicitação. Por exemplo, se os dados que você recebe não estão exatamente como você deseja que sejam exibidos, você pode escrever um pouco de código para modificá-los de acordo com suas necessidades de exibição digital.
  • Ativar Webhook - Gera um link de webhook e um token associado. Este webhook pode ser usado para nos notificar sobre uma mudança nos dados, o que atualizará a solicitação de API e atualizará suas telas automaticamente.
  • Ativar esta Solicitação - Define o status da solicitação de API.

Para testar a solicitação, precisaremos configurar o cabeçalho. É aqui que o Keystore entra. Na segunda caixa, digite Bearer {{apiKeystore.<<key>>}}, onde Bearer é o tipo de token e {{apiKeystore.<<key>>}} puxa o token armazenado no Keystore. Neste exemplo, usaremos o nome "clover" como referenciado acima.

Depois disso, clique em "Executar Teste". Se o código de resposta for 200, a API retornou dados com sucesso. Se houver qualquer outro código, há um problema na Solicitação de API.

Como Usar Parâmetros

Parâmetros estão presentes em URLs de todos os tipos. Há dois elementos em um parâmetro:

  • Eles devem seguir uma marca '?' na URL;
  • Eles têm um valor associado a eles

A aba Parâmetros permite especificar os Parâmetros cujo valor você gostaria de alterar.

Geralmente, a aba Parâmetros é usada em conjunto com as abas Pré-solicitação e Pós-solicitação para criar valores atualizados automaticamente.

Como Usar Processamento de Pré e Pós-Solicitação

Para usar o processamento de pré e pós-solicitação, é necessário algum conhecimento de Javascript.

Qual é a Diferença Entre os Dois?
Pré-solicitação: Este é um trecho de código normalmente definido para o contexto antes da solicitação de API. Isso pode ser recuperar um token de autenticação de outra API ou alterar parâmetros para permitir mais automação.
Pós-solicitação: Um pedaço de código para aplicar aos dados recebidos da solicitação de API. Este código pode ser usado para modificar os dados recebidos para mudar como eles são exibidos em suas telas.

A aba Pré-solicitação é onde você inserirá o código para processamento de pré-solicitação.

Exemplo: Para sistemas que requerem um token de autenticação gerado dinamicamente como o Toast, isso pode ser usado para chamar outra API para recuperar o token de autenticação e defini-lo no contexto da API.

Para mais informações sobre este exemplo, veja este artigo sobre como conectar sua API do Toast.

A aba Pós-solicitação é onde você inserirá o código para processamento de pós-solicitação.

Exemplo: Você está recebendo dados da API do seu software de ponto de venda (PDV), mas certas peças de dados não estão sendo exibidas da maneira que você gostaria.

Os preços podem ser exibidos como números inteiros (ou seja, 1299) em vez de como um preço adequado (ou seja, R$ 12,99). Para isso, precisaríamos de um pedaço de código para converter o número inteiro em um preço, e ter esse código extensível a quaisquer erros de exibição semelhantes (por exemplo, 1899 em vez de R$ 18,99).

Para este exemplo comum, este pedaço de código JavaScript deve resolver seu problema. Também podemos configurar a capacidade de mapear a disponibilidade do produto ao mesmo tempo.

Isso corrigirá os dados retornados, permitindo que sejam exibidos corretamente:

Isso também pode ser usado para fazer os dados aparecerem como "ESGOTADO", para riscar um item se ele estiver indisponível ou para exibir avisos em um sistema de gerenciamento de inventário. Para mais informações sobre este exemplo, veja nosso artigo sobre Menus Digitais.

Passo 3 (Opcional): Use Parâmetros de Substituição dos Atributos do Dispositivo.

Muitos sistemas de ponto de venda (PDV) são licenciados por loja/local. É possível configurar uma única Solicitação de API com o OptiSync e fazê-la funcionar com diferentes locais usando parâmetros de substituição. Inserir estes permite que sua tela comunique suas informações de identificação de loja ou local. Isso significa que uma única solicitação de API pode comunicar dados diferentes para diferentes lojas ou locais, em vez de precisar fazer solicitações de API individuais por tela.

Para começar, encontre a tela que deseja editar.

Clique em Avançado → Mais → Atributos Adicionais do Dispositivo.

Dois campos aparecerão, Chave e Valor.
firefox_KkCBvxsPKU.png

  • Chave - Um parâmetro que será usado durante a chamada de API para substituir pelo valor da sua loja. Isso substituirá parte do endpoint da URL da sua API.
  • Valor - Representa o código único associado à loja ou local que você deseja passar para sua API.

Neste exemplo, estamos mantendo o merchantID do Clover aqui. O valor inserido precisará ser obtido por você, pois será único.

Agora, volte para a página de configuração da solicitação de API. Substitua o merchantID no endpoint da API pelo nome da Chave que você definiu anteriormente.

Quando a chamada de API é acionada no dispositivo, ela pegará o valor do dispositivo e o substituirá em tempo de execução. Para cada tela, você deve executar essas mesmas etapas, mantendo o nome da Chave igual enquanto altera o Valor. Isso permitirá que você envie dados diferentes para telas diferentes.

Como Mapear Dados de API no Designer

Para enviar dados da sua API para uma tela, ela precisará ser registrada como uma Fonte de Dados. Isso permite que elementos de dados sejam adicionados ao aplicativo Designer do OptiSigns, onde podem ser formatados e incorporados em qualquer design visual que você deseja exibir.

O aplicativo Designer e os modelos podem ser usados para fazer a formatação, e a fonte de dados da API lidará com o mapeamento de dados. Qualquer caixa de texto ou elemento de imagem pode ser mapeado no Designer. Quando você mapeia um elemento de imagem, a URL da imagem será substituída em tempo de execução.

Passo 1: Criando uma Fonte de Dados de API

Para começar, encontre seu design ou crie um novo na aba Arquivos/Ativos.

Com o design aberto, clique em "Fonte de Dados" na coluna da esquerda. Em seguida, clique em "Adicionar Fonte de Dados" para adicionar uma fonte de dados de API ao design.

Role para baixo até onde diz "Gateway de API" e clique nele.

Você deve ver esta tela:

Selecione a Solicitação de API criada acima. Você verá uma tela como a abaixo:

Aqui, você pode escolher quais dados especificamente você deseja adicionar ao Design. Se você quiser todas as opções, clique em "Continuar". Esta tela aparecerá.

Nome da Fonte de Dados é como esta Fonte de Dados aparecerá no Designer. Nomeie-a com algo que o ajude a identificá-la.

Sincronização permite escolher com que frequência sincronizar de volta com sua API. Importar apenas uma vez faz sentido para promoções únicas e similares. Se for para um ativo de longo prazo, escolha Acesso direto periódico ou Sincronização de fundo periódica dependendo se você precisa usar os dados de dispositivo específico para definir o contexto.

Clique em Concluído, e a Fonte de Dados é criada.

Ela deve aparecer na coluna esquerda em "Usado neste design". Ela definitivamente aparecerá na seção "Outras Fontes de Dados". Você pode precisar atualizar a página para que ela apareça.

Agora, passamos para o passo 2.

Passo 2: Manter o Mapeamento de Elementos

Depois que a Fonte de Dados de API foi criada, você está pronto para mapear os dados.

No Designer, abra sua Fonte de Dados.

Clique nela e uma tela semelhante a esta aparecerá:

Abrir qualquer uma dessas exibirá os dados extraídos da sua API:

Ao clicar em qualquer pedaço desses dados e arrastá-lo para a tela, os dados aparecerão. Você terá a opção de usar os dados como um Repetidor ou sozinho.

Neste caso, queremos usá-lo sozinho. Para menus, um Repetidor faz mais sentido.

Para verificar a vinculação de dados, você pode clicar em qualquer elemento mapeado, depois clicar em Configurações. Você verá o Nome do Elemento do Ativo lá.

Temos o nome do item e o preço da API mapeados para o design. Quando publicado na tela, o valor será substituído automaticamente pelo valor da API. Se atualizações forem feitas no sistema PDV Clover, a mudança será refletida na tela automaticamente.

Repita este passo para todos os elementos que você deseja mapear para a fonte de dados da API e salve o design. Seu design está pronto para uso.

Mais Casos de Uso do OptiSync

Se você quiser mais detalhes sobre casos de uso de integração de API, temos vários artigos adicionais. Por favor, veja:

É isso!

Assim você integra dados de API e os publica em sua tela. Mais importante ainda, sem codificação!

Se você tiver perguntas adicionais, preocupações ou qualquer feedback sobre o OptiSigns, sinta-se à vontade para entrar em contato com nossa equipe de suporte em support@optisigns.com

Este artigo foi útil?
Deutsch English (United States) Español Français Italiano 日本語 Nederlands Svenska