Como Usar a API do SCADAFlex

Guia completo: autenticação, tags, dados operacionais e histórico

Guia técnico · Equipe SCADAFlex

Este guia foi feito para quem vai integrar um sistema com a API do SCADAFlex — seja para consultar dados de estações, ler histórico de variáveis ou automatizar relatórios. Você vai aprender, do zero, o que é uma API, como conseguir acesso, e como usar os quatro endpoints mais importantes do dia a dia, com exemplos práticos no Postman.

Não é preciso nenhum conhecimento prévio de programação avançada — só entender o passo a passo com calma. Vamos lá.

1. O que é uma API?

API é a sigla de “Application Programming Interface” — Interface de Programação de Aplicações. Na prática, é um jeito padronizado de um sistema pedir informação (ou mandar informação) para outro sistema, sem que um precise entender como o outro funciona por dentro.

Pense num balcão de atendimento: você não entra na cozinha do restaurante para pegar seu prato — você faz o pedido no balcão, numa linguagem que os dois lados entendem, e recebe o prato pronto de volta. A API do SCADAFlex é esse balcão: seu sistema “pede” dados (uma leitura de pressão, uma lista de estações, um histórico) numa linguagem padronizada, e recebe a resposta pronta, sem precisar saber como o SCADAFlex guarda ou calcula esses dados por dentro.

Toda chamada de API é um par pergunta/resposta: sua requisição vai, a resposta volta.

As peças de uma chamada de API

• URL base — o endereço de internet da API. Todas as chamadas deste guia usam, como exemplo, https://demo.scadaflex.online (na sua integração real, você usará o endereço informado pela nossa equipe).
• Endpoint — o “caminho” específico dentro da API que você quer acessar — por exemplo, /api/v2/variables/history é o endpoint de histórico.
• Método HTTP — indica a intenção do seu pedido. Os dois que você mais vai usar estão na tabela abaixo.

• Headers (cabeçalhos) — informações extras enviadas junto da chamada, fora do conteúdo principal — como o token de acesso (Authorization) ou o formato dos dados (Content-Type).
• JSON — o formato de texto usado para organizar os dados enviados e recebidos — pares de “chave”: valor, entre chaves { }. Todas as respostas da API do SCADAFlex vêm em JSON.
• Código de status — um número que resume o que aconteceu com sua chamada: 200 significa sucesso, 401 significa “não autenticado”, 404 significa “não encontrado”, e assim por diante.

2. Autenticação: como provar quem você é

Antes de pedir qualquer dado, a API precisa saber quem está perguntando — e se essa pessoa (ou sistema) tem permissão para ver aquilo. Isso é feito com um token: uma espécie de “crachá digital” temporário, que você recebe uma vez e depois anexa em toda chamada seguinte, para não precisar mandar sua senha de novo a cada pedido.

2.1 — Obtendo o token: POST /api/Auth/Token

Este é o primeiro passo de qualquer integração: enviar seu usuário e senha para receber um token de acesso.

Requisição de token: usuário e senha vão no corpo (Body) da chamada, em JSON.

A resposta traz o token propriamente dito (access_token) e por quanto tempo ele é válido (expires_in, em segundos — 3600 segundos = 1 hora, neste exemplo). Guarde os dois: você vai precisar renovar o token antes dele expirar.

2.2 — Usando o token nas chamadas seguintes

A partir daqui, toda chamada às demais APIs do SCADAFlex precisa levar o token no cabeçalho Authorization, no formato Bearer <token>:

2.3 — Conferindo sua sessão e permissões: GET /api/Auth

Depois de obter o token, você pode usar este endpoint para confirmar que ele está válido e ver informações da sua sessão — como seu identificador de usuário e quais permissões (funções) o seu perfil tem no sistema. Repare: este endpoint não gera um token novo — ele confirma o que o token que você já tem permite fazer.

Consultando a própria sessão: o token vai no cabeçalho Authorization, não no corpo.

3. Identificando variáveis: GET /api/v2/tags

No SCADAFlex, cada grandeza monitorada (pressão de saída, vazão, temperatura…) pode estar presente em várias estações e equipamentos diferentes. Para não precisar decorar um código numérico por equipamento, o sistema usa Tags Globais: um nome padronizado que identifica a mesma grandeza em qualquer lugar do sistema — por exemplo, PRESSAO_SAIDA sempre significa “pressão de saída”, não importa em qual estação.

Este endpoint retorna a lista completa de tags cadastradas — é o primeiro lugar para descobrir quais nomes usar nos filtros das próximas seções.

Lista de tags disponíveis: use o campo “tag” como filtro nos endpoints de dados.

Guarde os valores do campo tag (não o codTgg, que é um identificador interno) — são eles que você vai usar para filtrar dados operacionais e históricos nas próximas duas seções.

4. Dados operacionais instantâneos: POST /api/v2/variables/operations

Use este endpoint quando quiser o valor mais recente de uma ou mais variáveis agora — uma “foto” do estado atual do sistema, não um histórico. É o endpoint certo para montar um painel de monitoramento ou verificar rapidamente se algo está fora do esperado.

Os filtros vão no corpo (Body) da requisição, em JSON — você pode combinar vários ao mesmo tempo, e deixar como lista vazia [] os que não for usar:

Pedindo o valor atual de duas tags em duas estações diferentes, de uma só vez.

A resposta traz uma lista (items) com o valor convertido (valorConv, já na unidade de engenharia correta), a unidade e o horário exato da última leitura (dataLeitura) de cada variável encontrada.

5. Dados históricos: GET /api/v2/variables/history

Use este endpoint quando precisar de uma série de leituras ao longo do tempo — para montar um gráfico de tendência, um relatório de consumo, ou auditar o comportamento de uma variável num período específico.

Diferente do endpoint de operações, este é um GET — os filtros vão na própria URL, como parâmetros de consulta (query string), depois do sinal de interrogação (?), separados por &:

Histórico paginado: os filtros aparecem direto na URL, não no corpo da chamada.

Entendendo a paginação

Como um histórico pode ter milhares de registros, a resposta nunca vem inteira de uma vez só — ela vem em páginas. Repare nos três campos ao final da resposta do exemplo acima:

• pageSize — quantos registros já foram retornados nesta chamada (pagesize=3, neste exemplo).
• pageIndex — qual página você está vendo (a primeira é 1, não 0).
• totalRows — quantos registros existem no total, para esse filtro — use este número para calcular quantas páginas você precisa pedir (totalRows ÷ pageSize).

Para pegar a próxima página, basta repetir a mesma chamada trocando pageindex=1 por pageindex=2, e assim por diante, até cobrir todo o totalRows.

6. Boas práticas e erros comuns

Limite de requisições (rate limit)

A API do SCADAFlex protege endpoints sensíveis contra excesso de chamadas. Hoje, a maioria dos endpoints de consulta aceita até 30 requisições por minuto por cliente; endpoints mais sensíveis (como comandos de escrita) têm limites mais restritos. Se você ultrapassar o limite, a API responde com o código 429 (Too Many Requests) — nesse caso, espere um pouco antes de tentar de novo, em vez de repetir a chamada imediatamente.

Erro comum: token expirado

Este é, de longe, o erro mais frequente em integrações novas. A resposta vem com o código 401:

Token expirado ou ausente: sempre um 401. A solução é obter um token novo (seção 2.1).

Datas e fusos horários

Todas as datas trocadas com a API seguem o padrão ISO 8601 (ano-mês-dia, horas:minutos:segundos), geralmente em UTC (horário de Greenwich, indicado pelo Z no final, como em 2026-08-29T18:40:12Z). Ao montar filtros de período (from/to), fique atento à diferença entre o horário local e o UTC para não pedir o intervalo errado.

Segurança do token

• Não exponha o token — nunca grave o token em arquivo de log, print de depuração ou repositório de código.
• Use sempre HTTPS — sempre https://, nunca http://.
• Renove com antecedência — peça um token novo com folga antes do expires_in acabar, em vez de esperar a chamada falhar com 401 para só então renovar.

7. Glossário rápido

8. Resumo dos endpoints deste guia

Com esses cinco endpoints, você já cobre a maior parte das integrações mais comuns com o SCADAFlex. Em caso de dúvida, fale com a nossa equipe técnica.

SCADAFlex — Guia da API para Integradores