API V5

Introdução

O V5 Traceability Gateway permite a troca bidirecional de dados entre a linha de produtos V5 Traceability e outras soluções. O gateway é altamente flexível, proporcionando implantação rápida com muitos ERP diferentes e sistemas externos, permitindo que os clientes integrem toda a fábrica com eficiência. A linha de produtos V5 possui uma extensa API para uso na integração.

Este guia fornecerá uma visão geral detalhada de como usar os vários métodos para importar e exportar dados. Também detalhará cada entidade que pode ser importada e os campos possíveis para essas entidades.

O gateway pode ser utilizado de 2 maneiras principais:

• Por meio de uma API REST de interface da Web utilizando arquivos JSON ou XML.
• Por meio de compartilhamento direto de arquivos com documentos CSV ou XML.

Ambos os métodos serão analisados ​​neste guia, além de fornecer exemplos para as principais áreas de integração de dados.

1. O que o Gateway V5 faz?
2. Exemplo de Diagrama de Fluxo de Dados
3. Guias de Integração
4. Documentos de Referência de Integração V5
5. Metodologia - API V5
   1. Solicitações de exportação/GET
   2. Solicitações de Importação/POST
   3. Inserir ou Atualizar?
   4. Marcadores de exportação
   5. Parâmetros URI
   6. Logs, transações e descritores de sistema
6. Metodologia - Compartilhamento de Arquivos CSV
   1. Ordenação de arquivos de dados e cabeçalho
   2. Importações
   3. Exportações
7. Frequência e Sequência
8. Entre em contato

O serviço de integração V5 Traceability pode ser implantado para cobrir uma variedade de pontos de dados, que podem ser totalmente personalizados por cada cliente individual, dependendo de seus requisitos. Esses requisitos serão discutidos durante as fases iniciais da implementação do V5 Traceability.

Dependendo dos requisitos do cliente, o V5 Traceability pode ser configurado para integrar qualquer número de áreas, como formulação/BoMs, agendamento de trabalhos, pedidos de compra e venda e níveis e locais de estoque.

Nesta seção você pode encontrar guias específicos para a integração de módulos específicos do V5 Traceability:

Para os principais módulos que geralmente apresentam integração bidirecional:

• Mercadorias
• Fórmulas
• Estoque/localização de estoque
• Trabalhos/Ordens de Produção
• Ordens de compra
• Ordens de venda
• Transferências
• Unidades de medida

Para módulos menores que apresentam apenas opções de importação:

• Endereço
• AllergenLink
  
• Cliente (Fornecedores e Clientes)
• Link de campo personalizado
• Link de perigo
• Atribuição de ações

Para obter assistência na instalação e atualização da API V5, consulte a seguinte documentação:

• Guia de instalação e atualização da API V5

Para exemplos de implantação de integração, consulte nossos guias para soluções ERP específicas abaixo:

• Oracle NetSuite
• Sábio X3
• Central de Negócios da Microsoft

Ao longo deste guia dos métodos de integração do V5 Traceability, faremos uso regular de duas documentações para nos auxiliar. Ambos são úteis, independentemente do método de integração que estamos usando. Estes são:

• A Planilha de Integração V5 que contém informações úteis e modelos para os módulos integrados mais comuns.
• A Manual API V5, que pode ser usado para identificar URIs de importação/exportação específicos, além de fornecer um guia abrangente para todas as classes de dados usadas pela API V5.
• Ao longo dos guias de API nesta seção, serão feitas referências a endpoints transacionais e de log. Uma lista completa deles pode ser encontrada seguindo o link.

Se estiver usando esse método, a API V5 será instalada como um serviço da Web para facilitar a transferência de dados. A partir daqui, as transações são tratadas pelas diferentes classes de módulos disponíveis.

Para saber mais sobre essas classes, os diferentes endpoints/URIs, bem como informações sobre as várias classes de banco de dados com as quais lidaremos ao usar a API V5, podemos usar tanto o 'Planilha de Mapeamento de Integração V5' e as Site da API V5 para nos ajudar. A partir daqui, podemos utilizar o explorador de pacotes no canto superior esquerdo desta janela para navegar pelas diferentes seções do manual da API.

Faremos uso dessas seções para criar exemplos enquanto discutimos os vários aspectos da integração de dados abaixo.

Depois de instalados, os endpoints da API podem ser acessados ​​por meio de um navegador ou cliente REST em:

http://{hostname:port}/V5-API/api

O módulo IntegrationImport tem um caminho de /integrate/import/

O módulo IntegrationExport tem um caminho de /integrate/export/

O caminho do módulo 'Transações' é /integrate/export/transactions/

Cada método tem seu próprio caminho listado no diretório da API V5 como um ‘Target URI’. Isso pode ser anexado ao final dos caminhos acima para executar o método.

Cada descrição de método também contém um ‘request type’, que denota se é uma solicitação GET ou POST mais o URI para esse método fornecido.

Quaisquer solicitações GET ou POST serão processadas no formato JSON. Todos os campos e objetos são definidos no pacote de banco de dados que você pode encontrar através do pacote de serviços.

Conforme mencionado acima, o módulo de exportação da API V5 tem um caminho de:

http://{hostname:port}/V5-API/api/integrate/export/

Então, na realidade, isso seria algo como (se interagir por meio de uma instância instalada localmente da API V5):

http://127.0.0.1:8080/V5-API/api/integrate/export/

O que viria depois disso depende de quais dados queremos extrair do V5. Em seguida, nos referiríamos ao pacote de serviços, usando as janelas à esquerda da janela principal da API para selecionar o pacote de serviços, seguido por 'IntegrationExport' abaixo.

Também podemos usar o link de serviços na página de índice, que carregará o resumo da classe para esse pacote, onde podemos escolher a classe 'IntegrationExport'.

Em seguida, veremos o URI de destino da exportação (1) junto com uma lista de pontos de extremidade disponíveis para a classe do módulo de exportação. Podemos visualizar tudo isso em detalhes clicando no construtor 'IntegrationExport' (2) ou podemos usar o ‘Method Summary’ tabela abaixo (3) para encontrar rapidamente o endpoint desejado. Também podemos ver o URI de destino para este módulo na parte superior da página, portanto, tudo o que precisamos fazer agora é identificar os objetos, campos e valores necessários.

Então, vamos pegar a primeira entrada na tabela de resumo do método aqui, ‘Batch’. Clicar no link na coluna da direita (4) nos levará direto ao endpoint que queremos saber.

Isso nos fornece as informações que precisamos saber, incluindo quais dados serão recuperados, o tipo de solicitação e, mais importante, o URI de destino da solicitação.

Portanto, agora sabemos que, se quisermos extrair um lote da API V5, o endpoint que precisaríamos atingir seria:

http://127.0.0.1:8080/V5-API/api/integrate/export/batch/{batchNumber}

Vamos rapidamente dar uma olhada em como isso funcionaria na prática. Podemos começar encontrando um lote que queremos extrair por meio da API, vamos para o lote '50009622' que podemos ver aqui em Control Center.

Usando o que aprendemos acima, podemos concluir o URI no cliente REST da seguinte forma:

A execução desse processo agora gerará um arquivo JSON detalhado para esse lote, que pode ser consumido e analisado pelo aplicativo cliente. Um retorno típico para essa solicitação pode ser assim.

Em muitos casos em que o pluralismo é aplicável aos terminais que estamos abordando, por exemplo, aqui lote pode se tornar lotes, podemos usar isso para chamar uma lista de lotes com o ‘export/batches’ URI.

Conforme mencionado acima, o módulo de importação da API V5 tem um caminho de:

http://{hostname:port}/V5-API/api/integrate/import/

O que viria a seguir dependeria de quais dados estamos procurando importar por meio da API. Voltaríamos à seção de pacotes de serviços do manual da API e clique em 'IntegrationImport' (1) desta vez.

Isso é apresentado da mesma forma para a página de exportações, com o URI de importação (2), link para o topo das páginas de resumo abaixo (3) e a tabela de resumo do método (4) onde podemos ver todos os endpoints disponíveis .

Como antes, precisaríamos apenas encontrar o endpoint relevante para os dados que desejamos enviar ao sistema por meio da API.

Observe que a maioria dos terminais POST de importação espera uma matriz para que vários registros possam ser enviados em uma solicitação. Isso pode ser visto observando os tipos de parâmetro para os endpoints de importação sob o ‘Method Summary’.

Vamos pegar commodities como exemplo aqui:

O que isso está nos dizendo aqui é que podemos usar esse ponto final para importar listas de produtos/ingredientes que podem ser usados ​​para formulação. A URI que usaríamos para isso seria:

http://127.0.0.1:8080/V5-API/api/integrate/import/commodity

Podemos ver esse endpoint em uso abaixo, juntamente com um arquivo de importação de amostra muito básico no formato JSON:

Para nos ajudar a estruturar um arquivo de importação JSON, podemos usar o link para a seção de pacotes de banco de dados relevantes do manual da API presente no resumo do serviço:

Ou podemos navegar manualmente para a seção relevante selecionando a seção de resumo da classe do banco de dados no Página inicial da API.

Se navegarmos para a página de classe do banco de dados abaixo para ‘Commodity’, podemos como devemos estruturar ou arquivo JSON. Por exemplo, se quisermos definir um código de mercadoria ao usar este URI, isso seria ‘code’, e da mesma forma para a descrição da mercadoria, isso seria ‘description’.

Observe então como esses campos estão bem à esquerda do arquivo JSON de exemplo acima, junto com outros campos que podemos ver na captura de tela, como ‘defExpiryDays’. Também poderíamos adicionar o custo padrão da mercadoria ao nosso arquivo e, verificando abaixo, podemos ver que seria simplesmente ‘cost’ (1). Observe também que qualquer coisa listada aqui como um ‘primary key’ (2) é um campo obrigatório para esse terminal, ou seja, o arquivo não será importado se não estiver presente.

Também podemos percorrer diferentes níveis da API a partir desta classe de banco de dados, então vamos ver como podemos fazer isso para incluir mais informações sobre nossa mercadoria ‘units’.

No final desta página, encontraremos ‘WeightUnit’, que podemos usar como uma classe aninhada dentro do URI da mercadoria.

Isso nos dá nossa classe de banco de dados para ‘units’, que pode ficar no mesmo nível das outras classes que já definimos. Para descobrir quais dados podemos aninhar aqui, podemos clicar em ‘WeightUnit’ aqui para navegar pelas definições dessa classe.

Como podemos ver, existem apenas 3 pontos de dados nessa classe e, em nosso exemplo JSON, estamos usando todos eles, ‘code’, ‘description’, e ‘conversionRate’. Esses 3 pontos de dados seriam aninhados dentro do ‘units’ campo, como mostrado.

Se executarmos esse arquivo JSON como acima, veremos (dependendo do cliente que estamos usando) uma resposta da API e também poderemos ver essa mercadoria importada para o nosso 'Mercadorias' tabela no Centro de Controle.

Ao usar a função POST para atingir os terminais da API V5, isso pode atualizar ou inserir um registro. O que acontece aqui é definido pela chave primária que estamos tentando postar.

Se pegarmos nosso exemplo de mercadoria acima, vimos nas definições de classe do banco de dados que o código da mercadoria é sua chave primária. Quando estivermos postando, se esse código já existir, atualizaremos o registro dessa mercadoria com os novos valores incluídos nesse nível de classe.

Por outro lado, se o código atualmente não existir no banco de dados V5, um novo registro será criado.

No entanto, se olharmos para o nosso ‘units’ classe aninhada, observe que, embora possamos inserir novos dados de unidade se a chave primária desta classe ainda não estiver presente, não podemos atualizar as unidades existentes usando o ‘commodity’ ponto final. Em vez disso, teríamos que abordar o ‘import/unit’ URI em vez disso.

A API V5 usa marcadores de exportação para diferenciar os dados que já foram ou não exportados para o sistema ERP de um cliente. Por padrão, isso é ativado para ajudar na exportação de dados que o ERP externo ainda não viu e, uma vez marcados como exportados no banco de dados V5, esses dados não serão incluídos em futuras exportações.

No entanto, isso pode ser desativado, dependendo da preferência do cliente. Isso também pode ser desativado se o sistema ERP em uso puder retornar marcadores de exportação para a API V5 para reconhecer que já recebeu os dados em questão.

Nesta situação, um aviso de recebimento é usado para informar à API V5 que os dados foram recebidos, o endpoint que pode ser usado para controlar isso é documentado aqui.

Se nem a API V5 nem o ERP estiverem configurados para fornecer marcadores de exportação, dependendo do endpoint usado, isso poderá retornar uma grande quantidade de dados. Nesses casos, podemos usar parâmetros de URI para filtrar a quantidade de dados exportados.

A API V5 também utiliza vários parâmetros de URI que podem ser usados ​​para restringir ainda mais nossas solicitações do sistema.

Podemos ver se esses parâmetros estão disponíveis para nossos endpoints verificando os resumos de métodos em nosso serviço desejado. Se pudermos ver ‘int’ seguido de um parâmetro, podemos usar esse parâmetro para filtrar os resultados que receberemos de volta da API.

Por exemplo, vimos acima que isso funciona para ‘batch’ permitindo-nos filtrar pelo número do lote.

Outros exemplos podem incluir a obtenção de logs de lote por data, onde podemos usar ‘batch_system_logs/filterFrom/{filterDate}’ (usando convenções de datação de época).

Para muitos dos módulos que podem ser integrados por meio da API V5, geralmente é mais conveniente recuperar informações de terminais de transações e logs. Alguns deles podem ser usados ​​para diversos fins (como ‘registros do sistema’), enquanto outros são mais personalizados para módulos específicos (como ‘transações de vendas’).

Esses terminais usam descritores de sistema para denotar determinados eventos acontecendo (recebimento de uma mercadoria, consumo de um ingrediente para produção, etc.) e são particularmente úteis para manter a precisão do inventário em todo o sistema V5.

Para revisar esses endpoints e quais informações eles retornam/para quais módulos são úteis, clique em aqui.

O método de compartilhamento de arquivos V5 utiliza arquivos de 'cabeçalho' csv e csvh para realizar trocas de dados com Rastreabilidade V5. Para essas trocas, utilizaríamos arquivos de 'cabeçalho' para determinar a ordem dos dados para importações e exportações e, em seguida, importaríamos ou receberíamos um csv exportado que segue essa ordem. Podemos dar uma olhada em como isso funcionaria na prática abaixo.

Quer estejamos importando ou exportando dados usando o método de compartilhamento de arquivo csv, usaremos arquivos de cabeçalho para determinar a ordem dos dados. Em termos de como podemos estruturá-los, aqui podemos usar tanto o 'Planilha de Mapeamento de Integração V5' e o on-line manual da API para nos ajudar com isso. Vejamos um exemplo aqui para um ‘Commodities’ importar da planilha.

Como podemos ver aqui, o SG já estruturou um layout de cabeçalho básico aqui, e se olharmos no manual da API para esta classe de banco de dados em particular, podemos ver que a maioria dos campos aqui existe nesta classe, permitindo-nos simplesmente usar ‘code’, ‘cost’, ‘bulkUnit’ etc. como eles são definidos aqui.

Observe que, de forma semelhante a quando estávamos estruturando nossos arquivos JSON acima, a chave primária (code) deve ser incluído.

Também podemos percorrer classes de banco de dados de maneira semelhante à que vimos ao estruturar a importação JSON acima. Podemos ver isso em nosso exemplo acima com ‘units.code’. Dentro do ‘Commodity’ classe temos o ‘WeightUnits’ classe (definida como ‘units’).

Seguindo este link para o ‘WeightUnit’ classe nos mostrará que para definir o código para a unidade de peso, isso é ‘code’ nesta classe, então, para passar para isso de nossa ‘Commodity’ ponto de partida seria ‘units.code’.

Podemos percorrer quantos níveis quisermos aqui, eles só precisam estar vinculados no manual da API.

Faríamos o mesmo para estruturar cabeçalhos que usaríamos para exportações, usando as definições de classe de banco de dados apropriadas para identificar quais dados queremos receber de volta do sistema e em que ordem.

Os arquivos de cabeçalho devem ser construídos como arquivos csv, com 1 valor em cada célula na linha superior até que tenhamos definido todos os dados que desejamos importar ou exportar. Este arquivo csv deve então ser salvo e ter sua extensão editada para ser um ‘csvh’ (a visualização da extensão do arquivo no Windows deve estar habilitada para fazer isso).

Quaisquer edições no arquivo csvh devem ser feitas após alterá-lo novamente para um arquivo csv e editá-lo neste formato.

Os cabeçalhos usados ​​para importações devem ser colocados em:

<installdir>\SG Control Center\gateway\import\column_defs

Os cabeçalhos usados ​​para exportações devem ser colocados em:

<installdir>\SG Control Center\gateway\export\order

Agora podemos ver como faríamos para realizar nossas importações e exportações.

Depois que nossos arquivos de cabeçalho relevantes estiverem no lugar, precisamos concluir nosso arquivo csv para importação.

Conforme já mencionado, os dados em nosso arquivo csv devem aderir à mesma estrutura de seu arquivo de cabeçalho correspondente, ou seja, os dados corretos devem estar na coluna correta para que a importação seja bem-sucedida. Para manter nosso exemplo de mercadoria, podemos ver que neste exemplo abaixo, incluímos os dados do cabeçalho para nos auxiliar na entrada de dados. No entanto, isso não precisa ser incluído (consulte 'Ignorar cabeçalhos' abaixo).

Depois de configurar isso, podemos continuar a preencher o csv para incluir todas as mercadorias que queremos importar.

Com o csv completo, as importações podem ser executadas soltando os arquivos csv formatados e nomeados apropriadamente em ‘\SG Control Center\gateway\import’. As convenções de nomenclatura para esses arquivos são definidas na Planilha de Mapeamento de Integração V5, portanto, para commodities, podemos ver que é:

Assim, por exemplo, nosso nome de arquivo pode ser denominado 'commodity-0530231803.csv para nos informar que isso foi importado no dia 30^th Maio de 2023 às 18h03. Não há preferência de ordem de data/hora definida, então a SG recomendaria usar qualquer formato que funcione melhor para cada cliente aqui (isso pode acabar sendo determinado pelo ERP externo em uso).

Depois de colocar nossos arquivos na pasta correta, o Control Center os processará automaticamente, desde que as importações estejam habilitadas no Gateway. O sistema fornecerá um diálogo para nos informar se o processo foi bem-sucedido ou não. Mais informações sobre isso, com logs, podem ser encontradas na seção 'Gateway' do Centro de Controle.

Os arquivos também podem ser importados manualmente de outros locais clicando com o botão direito do mouse no ícone do Centro de Controle no sistema e escolhendo Gateway > Importar Arquivo.

Isso abrirá uma caixa de diálogo no Centro de Controle para selecionar o arquivo csv apropriado.

Dentro do próprio Gateway, podemos definir opções no processo de importação:

As configurações aqui podem ser definidas da seguinte forma:

• Importação habilitada – habilita a importação, permitindo que o Gateway verifique a pasta de importação em busca de csvs à medida que são colocados lá.
• Inserir Entidades Filhos – permite que o Gateway crie dinamicamente entidades internas se elas estiverem vinculadas ao arquivo csv. Um bom exemplo disso poderia ser uma importação de fórmula que lista commodities ainda não presentes no banco de dados. O Gateway criará essas entidades 'filhos' para nós neste caso, desde que a chave primária para mercadoria (código) seja fornecida.
• Ignorar Cabeçalhos – força o Gateway a pular a primeira linha (linha) de um csv importado. Isso é útil se o arquivo de cabeçalho estiver incluído no arquivo de importação csv.
• Nível de validação – define como os dados são validados à medida que são importados pelo Gateway. Existem 2 opções aqui:
  • Avisar – Se houver um erro em um arquivo e uma linha não puder ser importada, o sistema o avisará, mas continuará tentando processar o restante do arquivo.
  • Abortar – Se houver um erro em um arquivo e a linha não puder ser importada, o sistema interromperá o processo e informará o erro.

As alterações nas configurações podem ser aplicadas no canto superior direito deste painel. O Centro de Controle deve ser reiniciado para que as alterações entrem em vigor.

A exportação por meio do método de compartilhamento de arquivo csv é amplamente gerenciada pelo arquivo de cabeçalho e pelas informações solicitadas pelo sistema. Se os estruturarmos corretamente usando o manual da API, devemos receber todos os dados que queremos na ordem correta.

Dentro do próprio Gateway, também podemos definir opções no processo de exportação:

Aqui podemos usar as caixas de seleção fornecidas para selecionar quais dados desejamos exportar, dependendo dos pontos de dados que desejamos ver.

Observe que as classes de banco de dados iniciais aqui, como ‘BatchConsumption’ e ‘SystemLogs’ são diferentes daqueles com os quais começaríamos para importações, mas desde que sejamos capazes de navegar com sucesso no manual da API para essas classes, podemos produzir um arquivo de cabeçalho adequado.

Depois de selecionar o que queremos exportar, basta inserir um intervalo de exportação (em milissegundos) no canto superior esquerdo e aplicar esse valor (0 nunca exportará) no canto superior direito. O Centro de Controle deve ser reiniciado para que as alterações entrem em vigor.

Os arquivos csv exportados serão colocados em ‘<installdir>\SG Control Center\gateway\export’ by default.

Independentemente da metodologia utilizada para integração com o V5 Traceability, a frequência e o nível de automação das importações e exportações de dados é um elemento do processo que pode ser construído para atender às necessidades de cada cliente.

Isso pode ser feito manualmente pelo cliente ou automatizado para capturar a saída de um ERP externo de um local específico no servidor do cliente.

Uma ordem específica de importação também pode ser imposta neste estágio, então, por exemplo, podemos importar uma Lista de Materiais antes de uma ordem de serviço referente a essa BOM. Poderíamos fazer isso carregando os arquivos em sequência no diretório de importação ou nos pontos de extremidade do URI da API.

Conforme mostrado acima, também podemos configurar o Gateway para exportar em intervalos específicos para enviar os dados de volta ao sistema ERP.

Importações e exportações podem ser gerenciadas quase em tempo real ou executadas em intervalos definidos. Usando a rota da API, as importações e exportações podem ser gerenciadas com mais facilidade quase em tempo real. A frequência de importação para o método de compartilhamento de arquivo csv depende da solução de ERP/middleware individual que está sendo implementada, com a frequência de exportação gerenciada por meio do Centro de Controle, conforme descrito acima.

Interessado na Rastreabilidade V5 e na integração de dados que ela oferece? Entre em contato com nossa equipe de vendas aqui!