Integração com API Web Service de terceiros

O ERP SIGER® agora possui recursos para facilitar a criação de integrações com esses sistemas Web Service! A nova modalidade substitui a troca de informações entre sistemas por arquivos txt, csv, etc. Como as API Web Service as integrações são mais instantâneas e constantes entre os sistemas.

Contextualização

Temos recebido várias demandas para criação de integração com sistemas Web Service. Essas integrações possuem vários pontos em comum, como leitura de cadastros específicos da base de dados do SIGER®, geração de um corpo de envio da requisição e chamada da comunicação. Para simplificar a construção de novas integrações foi elaborado um framework de integração Web Service para os EDIs. Nesta publicação serão apresentadas as possibilidades que o SIGER® possui para elaboração dessas integrações.

Quais APIs já estão sendo atendidas dessa forma?

Várias integrações já foram implementadas utilizando esse framework, tornando os processos dos clientes automatizados. É válido observar a variedade de sistemas integrados, cada qual possuindo uma finalidade. As integrações atuais são as seguintes:

  • E-commerce Dooca: integração com a loja virtual do cliente, cadastrando produtos e recebendo pedidos;
  • Green Mobile: integração com aplicativo utilizado pelos representantes da empresa para registrar as vendas, importando pedidos;
  • myWMS: sistema destinado para o controle de estoque, recebe comandos do SIGER® para recebimento de mercadorias na entrada da nota e coleta de produtos para expedição;
  • API Beira-Rio: Calçados Beira-Rio passou a receber por API WS as notas para beneficiamento dos seus clientes, os quais agora têm configurado essa integração por EDI Web Service;
  • Atacado Martins: outra plataforma e-commerce, SIGER® fornece cadastros de produtos e recebe pedidos realizados no site.

Disponibilização da integração

O primeiro passo é criar um EDI. Isso serve para diferenciar a finalidade da integração, para permitir que as configurações sejam salvas para ela e para habilitar o acesso aos menus de configuração e monitoramento. Os EDI Web Service estão disponíveis no menu FTR 6.C.

Com o EDI disponível é possível configurar como será a integração dele através do menu FTR 6.C-G.Essas configurações são individuais por base de dados do SIGER®, portanto podem ser customizadas conforme a necessidade de cada cliente. Nesta etapa a configuração deve ser feita conforme as especificações da API de terceiros, que define por exemplo qual link deve ser utilizado e quais campos devem ser enviados. Abaixo estão listados os recursos disponíveis na tela de configuração do FTR 6.C-G.


Configurações gerais da integração

Configurações gerais da integração

Aqui fica definido o link principal da integração, que é a via base de comunicação entre o SIGER® e a API de terceiros. Além disso, é possível configurar o padrão de comunicação, tendo as opções REST ou SOAP. Cada API opta por usar algum desses padrões, a emissão de nota da Sefaz por exemplo é implementada com o padrão SOAP.

Nesta tela também fica configurado o tipo de autenticação que a API solicita. Existem opções para informar o token da integração ou usuário e senha. Essas chaves de acesso são disponibilizadas pelo fornecedor da API.

Configuração de operações

Configuração de operações

As API Web Services oferecem várias operações distintas que podem ser realizadas nela. Podem existir operações para cadastrar marcas, produtos, buscar pedidos, buscar lotes, etc. Nesta tela é configurada a integração com as operações de interesse da API. Importante observar que cada operação está vinculada a um relatório XML do gerador de relatórios. Isso permite utilizar os filtros da seleção padrão desse relatório para definir quais cadastros e campos serão enviados para a API, semelhante ao conceito das VIEWs. Porém, uma vantagem aqui é que, diferente das VIEWs, é possível utilizar campos complementares das tabelas do SIGER®.

A configuração das operações ainda permite definir se a operação trata-se de uma importação ou exportação de dados. Enquanto que a exportação entrega dados para a API, a importação irá consultar a API e acionar rotinas de importação específicas do programa EDI da integração.

Esta tela também permite habilitar/desabilitar o envio da operação através da check-box presente no grid de operações. Além disso, é possível configurar a ordem em que as operações serão acionadas na API, definindo quais operações devem ser executadas antes das demais.

Configuração De X Para

Configuração De X Para

A definição de quais campos da API o SIGER® irá enviar é feita no botão <De X Para> de cada operação. Nesta tela fica configurado cada campo da API de terceiros que o SIGER® irá utilizar na integração. Para cada campo, é definida uma expressão JavaScript de carga do campo, sendo que os campos disponíveis nestas expressões são justamente as mesmas “colunas” selecionadas no relatório XML da operação. Se o relatório lista por exemplo o “comprimento do produto”, será possível utilizar esse comprimento nas expressões de envio do produto.

Isso permite fazer relações diretas entre o SIGER® e a API, como por exemplo configurar que o campo “ncm” da API recebe a NCM do produto. Porém, é possível trabalhar com a expressão JavaScript para atender cenários mais complexos. Na imagem por exemplo o campo “comprimento” do SIGER® possui 3 casas decimais, enquanto que a API em questão permite apenas 2 casas decimais. A expressão JavaScript se encarrega de converter o valor do SIGER® sempre para 2 casas decimais nesta integração.

O uso de expressões JavaScript abre diversas possibilidades. Mais informações podem ser encontradas no help do SIGER®


Recursos Disponíveis

Esta tela de configurações conta ainda com diversos outros recursos mais específicos que serão listados abaixo.

Exportação incremental

Exportação incremental

Pode ser configurada a exportação incremental de registros do SIGER®. Isso permite que após uma exportação completa (de todos os cadastros filtrados na seleção padrão) o SIGER® faça apenas a integração dos registros que foram alterados após este envio completo. Isso torna a integração muito mais rápida quando o volume de cadastros integrados é grande.

Teste e envio da operação

Teste e envio da operação

No botão <Teste> o SIGER® fará uma tentativa de acesso à operação configurada. Isso permite verificar se o link principal está correto e se o SIGER® consegue acessar a API sem ser impedido por questões do ambiente, como falta de internet, bloqueio de firewall ou antivírus, por exemplo.

Além disso, no botão <Enviar Agora> é possível acionar a exportação direta de uma operação. São solicitados os filtros específicos desse envio direto. Isso permite efetuar testes e reintegrações sem que seja necessário acionar a integração completa com a API.

Visualização de inconsistências

Visualização de inconsistências

Nas integrações com a API podem ser vistas as inconsistências geradas e as mensagens retornadas pela API. Algumas APIs retornam informações detalhadas da validação do campo, o que ajuda a definir como deve ser feita a expressão.

Tempo limite de espera

Tempo limite de espera

Na operação pode ser definido o tempo em segundos que o SIGER® deve aguardar por uma resposta. Algumas operações podem retornar muitas informações, o que leva a tempos maiores de comunicação. Essa configuração permite adequar esse tempo para o cenário de cada operação.

Consulta e alteração de relatórios pelo browse

Consulta e alteração de relatórios pelo browse

Foi disponibilizado no browse de relatórios do gerador as opções de consulta e alteração do relatório selecionado. Esse recurso pode ser utilizado no menu FTR 6.C-G para verificar o relatório da integração ou adicionar novos campos nele.

Log de alteração por campos

Log de alteração por campos

No menu FTR 6.C-G podem ser consultadas as alterações realizadas na configuração da integração. Isso é útil para verificar as modificações mais recentes ou até detectar alterações indevidas.

Notificação para encerramento inesperado

Notificação para encerramento inesperado

Tendo em vista que as integrações com Web Service normalmente são constantes, foi criada uma notificação para os casos de encerramento inesperado. Se o SIGER® identificar, por exemplo, um arquivo corrompido durante a integração, será disparada uma notificação para os usuários. No menu FTR 6.C-M são configurados quais os usuários que recebem esse alerta.

Alteração manual da requisição

Alteração manual da requisição

No botão <Opções Restritas> do FTR 6.C-G é possível habilitar a edição das requisições montadas pelo SIGER®. Com isso, durante a integração serão exibidas perguntas como a exibida acima, possibilitando a alteração manual das informações. Esse recurso pode ser utilizado para fazer testes rápidos sobre o formato dos dados exigidos pela API, bastando utilizar o botão <Editar conteúdo> e em seguida o botão <Enviar com alterações>. Existe ainda a opção “Não exibir esta mensagem novamente” para pular a exibição desta tela nas requisições posteriores.

Log de requisições do SIGER®

Junto com a opção de edição das requisições é habilitado o relatório de requisições executadas. Neste relatório é possível consultar de forma consolidada todas as requisições feitas pelo SIGER® para a API e o status da comunicação. Com isso é possível verificar se o SIGER® enviou todos os dados que deveria e se obteve sucesso na comunicação.

Proteção contra execução em duplicidade

Proteção contra execução em duplicidade

A troca de informações entre o SIGER® e as API Web Service normalmente deverá ser feita com exclusividade por uma única sessão do SIGER®. Isso evita, por exemplo, que o SIGER® importe duas vezes as mesmas informações ou que envie cadastros duplicados para a API. Os EDI de integração Web Service já contam com essa proteção, impedindo acesso simultâneo ao menu de integração FTR 6.C-M. Isso permite inclusive configurar tarefas agendadas para abrir o menu de integração automaticamente em caso de parada inesperada, pois caso já esteja sendo executado o SIGER® irá apenas descartar a abertura duplicada do menu.

Descrição do EDI de origem no pedido

Descrição do EDI de origem no pedido

No pedido do SIGER® foi disponibilizado um campo de número do EDI de origem. Este campo permitiu a criação de um campo complementar de descrição do EDI de origem, que pode ser utilizado para verificar qual a API que deu entrada no pedido.

Envio de imagens ou XML da nota

Envio de imagens ou XML da nota

Em algumas API pode ser solicitado o envio de imagens, é o caso das API de e-commerce. Foi criado um recurso nas expressões JavaScript destas integrações de EDI para gerar o código base64 das imagens do SIGER®, permitindo que a imagem fique embutida na requisição feita pelo SIGER®.

Porém nem todas as API reconhecem a imagem ou outros arquivos dessa forma. No caso da API Atacado Martins é solicitado um link público da imagem e do XML da nota. Isso significa que esses arquivos devem estar disponíveis “na internet”. Para atender esse cenário foi implementado um recurso nos EDI Web Service para criar esse link público em conjunto com a API Rech WS.