Pular para o conteúdo principal

Insomnia

Este documento apresenta um passo a passo para utilização correta e eficiente do Insomnia na visualização de dados do ERP do cliente via API Sankhya.

Preparação do Insomnia​

Passo 1: Acessar o Insomnia e baixar o arquivo de requisições​

  1. Abra o Insomnia no seu computador.
  2. Na tela inicial do aplicativo, clique em Use the local Scratch Pad.
  3. Baixe o arquivo de requisições do Insomnia no link abaixo:

Passo 2: Importar o arquivo no Insomnia​

  1. No canto superior esquerdo do Insomnia, localize o botão Scratch Pad.
  2. Clique sobre ele e selecione a opção Import.
  3. Arraste o arquivo baixado no passo anterior para a tela, ou selecione-o manualmente.

Entendendo a estrutura das requisições​

Na barra lateral esquerda ficam as requisições importadas. Elas normalmente estão organizadas em pastas, com destaque para:

Pasta TOKENS​

As requisições da pasta TOKENS permitem obter tokens temporários exigidos pela Sankhya para consumir a API do cliente.

Para consultar o token de um cliente:

  1. Selecione uma requisição da pasta TOKENS.
  2. Navegue até a aba Headers para visualizar:
    • token (token do cliente gerado no ERP)
    • username
    • senha
    • appKey

⚠️ Atenção

As informações de token, usuário, senha e appKey são internas e sensíveis.
Não compartilhe esses dados com terceiros.

Pasta Requisições​

A pasta Requisições contém requisições organizadas por entidades/tabelas do ERP, como:

  • TGFCAB
  • TGFEST
  • TGFPRO
  • entre outras

A API do Sankhya trabalha com entidades. Cada tabela do banco possui uma entidade correspondente.

Link com a lista de entidades:

⚠️ Atenção

Para tabelas adicionais/customizadas no ERP, a entidade costuma ser o nome da tabela em maiúsculo.

Componentes importantes de uma requisição​

Usando como exemplo a requisição “TGFEST - Estoque”:

Headers​

  • O header Authorization guarda o token temporário necessário para consultar a API.
  • O token temporário normalmente possui duração aproximada de 5 minutos.

Body​

No Body, você define:

  • Quais campos deseja retornar
  • Filtros da consulta (semelhante a um WHERE no SQL)
  • A entidade raiz consultada

Regras para escrever filtros no parâmetro expression:

  • Sempre que usar um campo na expression, utilize a palavra reservada this.
  • Os valores devem estar entre aspas simples.
  • Os campos do banco devem estar em caixa alta.

Exemplo de padrão (referência):

this.CODPROD = '<Código do Produto>' AND this.CODLOCAL = '<Código do Local de Estoque>'

Sobre rootEntity:

  • O parâmetro rootEntity define a entidade da tabela.
  • Sempre informe a entidade correspondente à tabela consultada.

Utilizando o Insomnia​

Passo 1: Gerar o token temporário do cliente​

  1. Selecione a requisição de token do cliente desejado (pasta TOKENS).
  2. Clique em Send.
  3. Copie o token retornado no painel de resposta (lado direito).

⚠️ Atenção

Copie o token do primeiro ao último caractere.
Não é necessário incluir aspas, chaves ou qualquer estrutura adicional.

Passo 2: Aplicar o token em uma requisição de tabela​

  1. Abra a requisição da tabela desejada (ex.: TGFEST - Estoque).
  2. Acesse a aba Headers.
  3. No header Authorization:
    • mantenha a palavra Bearer
    • substitua/cole o token temporário após um espaço

Formato esperado:

Bearer <token_temporario>

Passo 3: Montar a consulta no Body e executar​

  1. Acesse a aba Body.
  2. Ajuste os campos que deseja retornar.
  3. Configure os filtros (expression) conforme necessário.
  4. Clique em Send.
  5. Verifique o retorno no painel da direita.

Entendendo os retornos da Sankhya​

Os retornos da Sankhya nem sempre são diretos, mas é possível interpretá-los.

Exemplo de cenário:

  • Foi feito um request na entidade da TGFEST, mas nenhum dado foi retornado porque nenhum registro atendeu ao filtro aplicado.
  • Mesmo assim, alguns campos podem aparecer no retorno. Isso acontece porque a Sankhya pode retornar campos adicionais (geralmente PKs e FKs) obrigatoriamente.

Interpretação por índice (base 0)​

Como a API segue uma estrutura baseada em índice (base 0), os campos podem ser identificados assim:

  • CODPROD: f0
  • CODEMP: f1
  • CODLOCAL: f2
  • CONTROLE: f3

E assim sucessivamente.

Quando existe resultado, ele pode aparecer com os valores atribuídos em f0, f1, f2, etc. Em retornos com muitos campos, a ordem visual pode ficar confusa, mas a correspondência por índice permanece válida.

Exemplo de leitura:

  • f0: 49 corresponde ao campo CODPROD
  • f1: 0.0 corresponde ao campo ESTOQUE
  • e assim por diante, seguindo a sequência definida.

Análise de Logs (TGLATS)​

A análise de logs possui diferenças no Body e no retorno da requisição.

Como acessar a requisição de logs​

  1. Na pasta Requisições, localize a requisição “Logs - TGLATS”.
  2. Selecione a requisição e acesse a aba Body.

Parâmetros principais no Body:

  • size: quantidade máxima de logs retornados
  • page: página consultada (o log pode ter múltiplas páginas)
  • dhAlter: data utilizada como base para consulta
  • entidades: entidade/tabela a ser consultada nos logs

Como interpretar o retorno​

No retorno:

  • dtAlter: data/hora em que o log foi gravado no ERP
  • evento: tipo da movimentação que gerou o log (ex.: CHANGE e DELETE)
  • pk: conjunto de campos e valores que identifica o registro alterado

⚠️ Atenção

O log não informa quais campos foram alterados.
Ele informa a entidade, o evento e a chave (PK) do registro afetado.

Paginação de logs​

A quantidade total de páginas pode aparecer ao final do retorno da primeira página.

⚠️ Atenção

Por conta do índice base 0, se o retorno indicar totalPages: 14, a contagem efetiva de páginas vai de 0 a 13.
Consultar a página 14 normalmente resultará em resposta vazia/sem logs.

Se for realizada a consulta em uma página inexistente, o retorno indica que não há logs para aquela data ou página.

Vídeo Demonstrativo​

Material de apoio​