Interpretação dos relatórios e extração de dados

Atualizado há 28 dias

1. Página de resumo

Depois de guardar a configuração do fluxo, abre-se uma página de resumo que apresenta todas as informações necessárias à extração de dados.

Modificar a configuração

Pode modificar as informações previamente introduzidas clicando no separador «Editar a configuração do fluxo».

Pode também aceder a esta página através do separador «Configurações de fluxo», clicando no símbolo do olho na coluna «Ações» da tabela.

2. Elementos de extração

As condições de extração da origem escolhida são apresentadas sob a forma de três elementos obrigatórios a combinar:

Método

GET: protocolo de pedido utilizado para recuperar os dados.

Autorização

Bearer Token: chave de segurança necessária para aceder ao conteúdo.

URL do ponto final

URL em formato JSON ou CSV:

https://gate.teeptrak.net/api/....json
https://gate.teeptrak.net/api/....csv

3. Notas importantes

Paginação e limites de pedidos

Os dados são devolvidos por blocos para garantir um desempenho ótimo.

Limites de pedidos

  • Máximo: 1 pedido a cada 2 segundos por token
  • Quota horária: 500 pedidos por hora por token

Se este limite for ultrapassado, a API devolve um erro 429 Too Many Requests.

Recomendação: espace os seus pedidos em, pelo menos, 8 segundos para se manter confortavelmente dentro dos dois limites.

Resultados por página

Cada pedido devolve um máximo de 2000 resultados por página (2000 linhas). Para uma exportação de 5000 resultados, é necessário efetuar vários pedidos, sendo os resultados repartidos em blocos de 2000 linhas.

Exceção: a contagem de produtos está limitada a 1000 resultados por página.

4. Exemplo de recuperação de dados

Através da utilização do método GET, da autorização Bearer Token e do URL fornecido, pode exportar os seus dados em formato JSON e/ou CSV.

Procedimento com o Postman

  1. Insira as informações da API nos campos correspondentes do Postman
  2. Os dados exportados em formato JSON são apresentados na secção inferior

5. Parâmetros opcionais e paginação

É possível aplicar filtros às exportações para afinar e otimizar as suas necessidades de extração.

Utilização no Postman

  1. Clique em «Params»
  2. Insira as chaves e os valores correspondentes
  3. Clique em «Send» para validar o filtro

Lista dos parâmetros disponíveis

N.º Parâmetro Descrição
1 page Definir o número de página devolvido pela API
2 created_at_gte Definir o limiar «maior ou igual a» (criado em…)
3 created_at_lte Definir o limiar «menor ou igual a» (criado em…)
4 updated_at_lte Definir o limiar «menor ou igual a» (atualizado em…)
5 with_custom_fields Autorizar a apresentação dos campos personalizados
6 machine_ids Filtrar o pedido por uma ou várias máquinas

6. Dados brutos - Alternativa V2 com paginação por cursor

Apresentação

Para a API de dados brutos, está disponível uma alternativa opcional: a API Performance Logs V2. Esta API oferece uma paginação por cursor mais robusta do que a paginação clássica por número de página, garantindo que cada registo é devolvido exatamente uma vez, mesmo que os dados mudem entre os seus pedidos.

Endpoints V2:

GET /api/v1/external/performance_logs.json
GET /api/v1/external/performance_logs.csv
GET /api/v1/external/performance_logs/simplified_losses.json
GET /api/v1/external/performance_logs/simplified_losses.csv

Endpoints V1 clássicos (continuam disponíveis):

GET /api/v1/external/raw_data
GET /api/v1/external/simplified_losses

Pode continuar a utilizar a paginação clássica por page ou adotar a paginação por cursor, consoante as suas necessidades.

Quando utilizar a V2 (cursor)?

  • Tem uma sincronização regular de dados (diária, horária, etc.)
  • Pretende garantir zero perdas ou duplicações de dados
  • Gere grandes volumes e pretende uma exportação CSV num único pedido

Quando permanecer na V1 (página)?

  • Efetua exportações pontuais simples
  • Prefere a paginação clássica por número de página
  • A sua integração existente funciona bem com a V1

Paginação por cursor: modo de utilização

Parâmetros específicos da V2

Parâmetro Descrição
since Data ISO 8601 para o primeiro pedido (ex.: 2025-01-01T00:00:00Z).
cursor Chave de paginação para os pedidos seguintes. Ver abaixo.
limit Número de resultados por página (predefinição: 2000, máx.: 2000)

Conceito

O cursor é uma chave de paginação que garante que cada registo é devolvido exatamente uma vez, mesmo que os dados mudem entre os seus pedidos. Isto oferece uma melhor integridade dos dados em comparação com a paginação simples por número de página.

Primeiro pedido (sincronização inicial)

Lance o seu primeiro pedido sem cursor, utilizando o parâmetro since ou sem qualquer parâmetro:

GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z

A resposta JSON inclui um objeto meta que contém um next_cursor:

{
  "data": [ ... ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate.teeptrak.net/api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0Ij..."
  }
}

Pedidos seguintes (sincronização incremental)

Guarde o último next_cursor recebido. Para o pedido seguinte, utilize este cursor como parâmetro:

GET /api/v1/external/performance_logs?cursor=eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9

A resposta devolve um novo next_cursor para o pedido seguinte. Repita este ciclo até que next_cursor seja null, o que indica que obteve todos os dados disponíveis.

Fim da paginação

Quando meta.next_cursor é null ou o número de resultados é inferior ao limite, recuperou todos os registos disponíveis.
Para prosseguir o pedido mais tarde e obter os novos dados, recomenda-se conservar o último cursor que não seja null.

Caso de erro: cursor perdido

Se perder o seu último cursor guardado, relance um pedido com o parâmetro since e uma data aproximada da sua última sincronização bem-sucedida. Recuperará então os dados a partir dessa data.

Exemplo completo de uma sincronização em três pedidos

  1. Sincronização inicial
Pedido 1: GET /api/v1/external/performance_logs?since=2025-01-01T00:00:00Z
Resposta: 2000 registos + next_cursor = "cursor_ABC"
Guarde "cursor_ABC"
  1. Sincronização incremental
Pedido 2: GET /api/v1/external/performance_logs?cursor=cursor_ABC
Resposta: 2000 registos + next_cursor = "cursor_XYZ"
Guarde "cursor_XYZ"
  1. Última sincronização incremental
Pedido 3: GET /api/v1/external/performance_logs?cursor=cursor_XYZ
Resposta: 1500 registos + next_cursor = "cursor_qsd"
Guarde "cursor_qsd"
Sincronização terminada

7. Gestão do cursor com o Postman (variáveis de ambiente)

Para automatizar a gestão do cursor no Postman, utilize as variáveis de ambiente.

Configuração inicial

  1. Abra o Postman e aceda a «Manage Environments» (ícone de engrenagem)
  2. Crie ou modifique o seu ambiente Gate
  3. Adicione duas variáveis:
    • Chave: cursor | Valor: (deixar vazio)
    • Chave: token | Valor: o seu Bearer Token

Primeiro pedido

No separador Params, adicione:

Chave Valor
since 2025-01-01T00:00:00Z

No separador Authorization, selecione Bearer Token e introduza o seu token.

Clique em Send.

Atualização do cursor após cada resposta

  1. Aceda ao separador Tests
  2. Adicione este script para guardar automaticamente o next_cursor:
if (pm.response.code === 200) {
  const responseData = pm.response.json();
  if (responseData.meta && responseData.meta.next_cursor) {
    pm.environment.set("cursor", responseData.meta.next_cursor);
    console.log("Cursor guardado:", responseData.meta.next_cursor);
  } else {
    console.log("Fim da paginação: next_cursor é null");
  }
}

Pedidos seguintes

  1. No separador Params, elimine o parâmetro since
  2. Adicione o parâmetro cursor com o valor {{cursor}}
  3. Clique em Send

O Postman substituirá automaticamente {{cursor}} pelo último valor guardado. Após cada resposta, o script atualiza a variável com o novo cursor.

Repetir até ao fim

Continue a enviar o pedido. O cursor é atualizado automaticamente após cada chamada. Quando next_cursor é null, a sincronização está terminada.

8. Estrutura da resposta V2

Resposta JSON

{
  "data": [
    {
      "id": 1,
      "duration": 300,
      "machine_id": 10,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:00:00Z",
      "custom_fields": {
        "Team": "Morning",
        "Line": "L3"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0wNi0wMVQxMDoxNTowMC4wMDAwMDBaIiwiaWQiOjJ9"
  },
  "links": {
    "next": "https://gate.teeptrak.net/api/v1/external/performance_logs?cursor=eyJ..."
  }
}

Elementos-chave

Elemento Descrição
data Tabela que contém os registos de desempenho
meta.next_cursor Cursor para o pedido seguinte. null se for o fim da paginação
links.next URL pré-construído para o pedido seguinte (opcional)
data.custom_fields Objeto que contém os campos personalizados (se ativados)

Formato das datas

Todas as datas são devolvidas em formato ISO 8601 em UTC (ex.: 2025-01-15T10:30:00Z).

10. Exemplos de integrações com a V2

Exportação CSV completa

Para exportar todos os dados em CSV de uma só vez:

GET /api/v1/external/performance_logs.csv?since=2025-01-01T00:00:00Z

Este pedido único devolve todos os resultados num único ficheiro CSV, sem necessidade de paginação. Ideal para as exportações pontuais.

Filtragem por máquinas

Para extrair os dados de máquinas específicas:

GET /api/v1/external/performance_logs?cursor=...&machine_ids=10,20,30

Campos personalizados

Para incluir os campos personalizados na resposta:

GET /api/v1/external/performance_logs?cursor=...&with_custom_fields=true

Aparecerão no objeto with_custom_fields de cada registo.