Documentação da API do Portal
O Portal de Telemetria disponibiliza uma API REST para permitir a integração com outras plataformas, sistemas e serviços. Por meio da API, é possível consultar informações do Portal, obter dados de telemetria, acompanhar o estado dos equipamentos, consultar históricos e executar determinadas operações, como o envio de comandos e o reconhecimento de alarmes.
A API deve ser utilizada de forma controlada e eficiente. Os limites apresentados nesta documentação existem para preservar a estabilidade, disponibilidade e desempenho do serviço para todos os usuários e integrações.
Atenção
A utilização da API REST está disponível apenas para Contratos do plano ENTERPRISE.
Recursos Disponíveis via API
Através da API REST do Portal, é possível, por exemplo:
Acessar Dados de telemetria: obter medições de temperatura, umidade, pressão e outros parâmetros disponibilizados pelos equipamentos remotos.
Monitorar o estado dos equipamentos: consultar informações relacionadas ao estado de conexão dos equipamentos, como online e offline.
Consultar históricos: obter registros históricos de Dados, Alarmes e Eventos.
Enviar comandos: realizar escritas nos Dados associados às variáveis dos equipamentos remotos.
Reconhecer Alarmes: realizar operações de reconhecimento de Alarmes, quando disponíveis para o recurso utilizado.
Utilização da API
Para auxiliar na utilização e no melhor aproveitamento da API REST do Portal, disponibilizamos os seguintes recursos:
Documentação Interativa API REST: inclui detalhes sobre endpoints, métodos, parâmetros, modelos de dados e exemplos de requisições e respostas.
Esta é a principal referência técnica da API e deve ser consultada durante o desenvolvimento da integração.
Playlist de Vídeos Explicativos: apresenta exemplos e orientações práticas para utilização da API.
Boas Práticas de Consumo da API
A API REST deve ser utilizada de maneira eficiente, evitando consultas desnecessárias, repetitivas ou com quantidade excessiva de informações.
Uma integração bem implementada deve buscar apenas os recursos necessários, utilizar filtros adequados e manter o controle das informações que já foram processadas.
As recomendações desta seção são especialmente importantes para integrações que executam consultas de forma automática ou periódica.
Controle das Requisições
Evite realizar requisições de forma contínua ou em intervalos muito pequenos para verificar se existem novas informações.
Sempre que possível:
defina um intervalo adequado entre as consultas;
evite realizar várias consultas simultâneas para o mesmo recurso;
reutilize informações já obtidas anteriormente;
mantenha localmente o controle dos recursos que já foram processados;
consulte somente os recursos necessários para a operação da integração.
Uma integração não deve utilizar requisições repetitivas como mecanismo de polling intensivo.
Atenção
Os limites de requisições são aplicados à utilização da API. Portanto, aumentar a quantidade de processos, threads ou tarefas executando requisições simultaneamente não aumenta a capacidade disponível e pode fazer com que a integração atinja os limites mais rapidamente.
Utilize Filtros Sempre que Disponíveis
Ao consultar informações, utilize os parâmetros de filtragem disponíveis para restringir a consulta aos recursos realmente necessários.
Evite consultas genéricas que retornem todos os recursos de um Contrato quando a integração necessita apenas de uma parte deles.
Para endpoints de histórico, recomenda-se informar explicitamente os IDs dos recursos que devem ser consultados, sempre que essa opção estiver disponível.
Por exemplo, se uma integração precisa acompanhar somente determinados Dados, é preferível consultar explicitamente esses Dados em vez de solicitar o histórico de todos os Dados do Contrato.
Atenção
Consultas abrangentes podem retornar uma quantidade significativamente maior de informações e consumir mais recursos do serviço. Além de aumentar o tempo de processamento da requisição, isso pode fazer com que os limites de registros ou recursos sejam atingidos.
Boas Práticas para Consultas de Histórico
As consultas de histórico merecem atenção especial, pois podem retornar uma quantidade elevada de registros.
Evite utilizar o histórico como mecanismo de consulta contínua de todas as informações disponíveis no Portal.
Para integrações que precisam processar históricos periodicamente, recomenda-se utilizar consultas incrementais.
Nesse modelo, a integração deve:
registrar localmente até qual data e hora os registros já foram processados;
realizar a próxima consulta somente para o período ainda não processado;
utilizar filtros para restringir os recursos consultados;
utilizar paginação quando necessário;
atualizar o controle local após o processamento bem-sucedido dos registros.
Esse modelo reduz significativamente a quantidade de informações transferidas e evita que a mesma informação seja consultada e processada repetidamente.
Nota
A consulta incremental é especialmente recomendada para integrações que precisam acompanhar continuamente novos registros de Alarmes, Dados ou Eventos.
Boas Práticas para Alarmes
Integrações que trabalham com Alarmes devem evitar consultas frequentes de grandes períodos do histórico para identificar novos registros.
Por exemplo, não é recomendado que uma integração consulte repetidamente as últimas 24 horas de Alarmes para verificar se houve um novo registro. Essa abordagem faz com que os mesmos registros sejam transferidos e processados diversas vezes.
Prefira uma estratégia incremental, mantendo o controle do último período processado e consultando somente os registros posteriores a esse ponto.
Além disso:
utilize filtros para consultar somente os Alarmes de interesse;
evite consultar todos os Alarmes do Contrato quando apenas alguns são necessários;
evite aumentar a frequência das consultas como tentativa de obter informações mais rapidamente;
mantenha localmente os registros já processados, quando aplicável;
não utilize múltiplos processos independentes para consultar repetidamente os mesmos Alarmes.
Atenção
O histórico de Alarmes deve ser utilizado para consulta e processamento de registros históricos, e não como mecanismo de polling intensivo. Uma integração que consulta grandes períodos repetidamente pode gerar processamento e transferência de dados desnecessários.
Boas Práticas para Dados
Ao consultar históricos de Dados, procure restringir a consulta aos Dados que efetivamente serão utilizados pela integração.
Evite solicitar simultaneamente grandes quantidades de Dados quando eles não são necessários para a operação.
Para processos periódicos, prefira dividir o processamento em consultas menores e incrementais, mantendo o controle do último período processado.
Essa abordagem também facilita o tratamento de falhas, pois uma eventual reexecução pode ocorrer somente sobre o intervalo que não foi processado com sucesso.
Paginação
Quando a quantidade de registros retornados puder ser elevada, utilize os recursos de paginação disponibilizados pelo endpoint.
A paginação permite trabalhar com conjuntos menores de registros, reduzindo o consumo de memória e facilitando o processamento pela integração.
Caso uma consulta retorne exatamente a quantidade máxima de registros permitida para o endpoint, considere esse resultado como um indicativo de que a consulta pode estar ampla demais.
Nesse caso, recomenda-se:
utilizar filtros mais restritivos;
reduzir o período consultado;
reduzir a quantidade de recursos consultados;
utilizar paginação, quando disponível;
dividir a consulta em múltiplas requisições menores.
Evite Consultas Repetitivas
Informações que não precisam ser atualizadas continuamente devem ser armazenadas ou reutilizadas pela integração sempre que possível.
Evite solicitar novamente informações que já foram obtidas e que não sofreram alteração.
Por exemplo, uma integração não deve consultar repetidamente a mesma lista de recursos apenas para obter informações que permanecem estáticas.
Sempre que possível, mantenha um estado local da integração contendo as informações necessárias para evitar consultas redundantes.
Controle de Concorrência
Evite executar um grande número de requisições simultaneamente.
A utilização de múltiplos processos, threads ou tarefas assíncronas para realizar requisições deve ser controlada para que a integração não gere uma quantidade excessiva de chamadas em um curto intervalo de tempo.
A concorrência deve ser utilizada para melhorar o processamento da aplicação, e não para aumentar artificialmente a quantidade de requisições realizadas contra a API.
Atenção
A execução concorrente de requisições não elimina os limites da API. Todas as requisições continuam sujeitas às restrições de utilização descritas nesta documentação.
Tratamento do HTTP 429
Quando a API retorna o código HTTP 429 (Too Many Requests), significa que a integração atingiu um dos limites de requisições estabelecidos para a API.
Ao receber esse retorno, a integração deve interromper temporariamente as novas requisições e aguardar a abertura de uma nova janela de requisições.
Não é recomendado realizar imediatamente novas tentativas em sequência, pois isso pode prolongar a ocorrência de novos bloqueios.
Uma implementação adequada deve:
identificar o código HTTP 429;
interromper temporariamente novas requisições;
aguardar antes de realizar uma nova tentativa;
evitar múltiplas tentativas simultâneas;
retomar o processamento de forma controlada após o período de espera.
Atenção
Não implemente tentativas imediatas e contínuas após um HTTP 429. O comportamento de repetir rapidamente a mesma requisição pode gerar novas ocorrências do limite e prejudicar o funcionamento da integração.
Tratamento de Erros
A integração deve tratar adequadamente os códigos HTTP retornados pela API.
Não considere toda resposta diferente de 200 como uma falha definitiva. Dependendo do endpoint e da operação realizada, diferentes códigos podem representar situações distintas, como requisição inválida, recurso inexistente, falta de autorização ou excesso de requisições.
Recomenda-se que a integração:
valide o código HTTP retornado;
analise a resposta retornada pela API;
registre erros relevantes para diagnóstico;
evite repetir automaticamente requisições que possuem erros de validação;
diferencie erros temporários de erros que exigem correção da requisição.
Restrições e Limitações da API
Para manter a integridade, estabilidade e desempenho da API do Portal de Telemetria, existem restrições de utilização.
Essas restrições devem ser consideradas durante o desenvolvimento da integração e não devem ser tratadas apenas como limites a serem contornados.
Os principais limites estão relacionados a:
Atenção
Os limites apresentados nesta documentação são parte das regras de utilização da API. Não é recomendado desenvolver a integração tentando contornar esses limites, por exemplo, utilizando múltiplos processos, credenciais ou requisições simultâneas para aumentar artificialmente a quantidade de consultas.
Número de Requisições
Todos os endpoints da API possuem limites de requisições (throttling).
Os limites variam de acordo com o tipo de operação realizada. As requisições também são controladas em duas janelas de tempo:
uma janela de 1 minuto;
uma janela de 24 horas.
Os limites atualmente definidos são:
Endpoints de Histórico
Máximo de 1 requisição por minuto;
Até 288 requisições por dia;
Frequência média recomendada: 1 requisição a cada 5 minutos.
Endpoints de Comandos (Escrita e Reconhecimento de Alarme)
Máximo de 6 requisições por minuto;
Até 1.440 requisições por dia;
Frequência média recomendada: 1 requisição por minuto.
Demais Endpoints
Máximo de 2 requisições por minuto;
Até 1.440 requisições por dia;
Frequência média recomendada: 1 requisição por minuto.
Atenção
Os limites por minuto e por dia são acumulativos. Portanto, respeitar apenas o limite por minuto não garante que a integração poderá realizar requisições continuamente durante todo o período de 24 horas.
Atenção
Caso o limite de requisições seja ultrapassado, a API retornará o código HTTP 429 (Too Many Requests).
Nota
Ao receber esse código, a integração deve aguardar a abertura de uma nova janela de requisições antes de realizar novas consultas. Não devem ser realizadas novas tentativas imediatamente e de forma repetitiva.
Número de Registros
Os endpoints de histórico possuem um limite para a quantidade de registros que pode ser retornada em uma única requisição.
Os limites são:
Tipo de Histórico |
Limitação |
|---|---|
Dados |
Até 90 mil registros |
Alarmes |
Até 30 mil registros |
Eventos |
Até 10 mil registros |
Atenção
Uma resposta contendo exatamente a quantidade máxima de registros permitida deve ser analisada com atenção.
Nota
Esse resultado pode indicar que existem registros adicionais que não foram retornados pela consulta. Nessa situação, utilize paginação, quando disponível, ou torne os filtros mais restritivos, reduzindo o período ou a quantidade de recursos consultados.
Quantidade de Recursos
Os endpoints de histórico também possuem limites relacionados à quantidade de recursos que podem ser consultados em cada requisição.
Os limites são aplicados após a aplicação dos filtros da consulta. Portanto, eles não representam simplesmente a quantidade de IDs ou nomes informados nos parâmetros, mas a quantidade de recursos efetivamente considerada pela consulta após a combinação dos filtros.
Os limites são:
Tipo de Histórico |
Recurso |
Limitação |
|---|---|---|
Dados |
Dado |
Até 50 Dados |
Dados |
Conector |
Até 200 Conectores |
Alarmes |
Alarme |
Até 25 Alarmes |
Alarmes |
Conector |
Até 200 Conectores |
Eventos |
Conector |
Até 200 Conectores |
Atenção
Para garantir maior controle sobre os resultados, utilize os IDs dos recursos desejados nos parâmetros de filtragem sempre que possível.
Nota
Evite consultas que dependam da obtenção de todos os recursos disponíveis no Contrato quando apenas uma parte deles é necessária.
Período de Consulta
Os endpoints de histórico possuem um limite para o período máximo que pode ser consultado em uma única requisição.
Os períodos máximos são:
Tipo de Histórico |
Limitação |
|---|---|
Dados |
Até 30 dias |
Alarmes |
Até 30 dias |
Eventos |
Até 7 dias |
Atenção
Consultar períodos extensos pode resultar em uma quantidade elevada de registros.
Nota
Sempre que possível, utilize períodos menores e realize consultas incrementais. Isso reduz o volume de dados transferidos e facilita o processamento e o tratamento de falhas pela integração.
Atenção
Quando nenhum período de consulta for especificado nos endpoints de histórico, a API considerará automaticamente os registros das últimas 24 horas.
Nota
Para integrações automáticas, recomenda-se informar explicitamente o período desejado em vez de depender desse comportamento padrão.
Recomendações para Integrações Automáticas
Integrações que executam consultas automaticamente devem ser projetadas para funcionar de maneira previsível mesmo diante de grandes volumes de dados, falhas temporárias ou atingimento dos limites da API.
Como regra geral, recomenda-se o seguinte fluxo:
Defina quais recursos realmente precisam ser acompanhados.
Armazene localmente os IDs desses recursos.
Consulte somente os recursos necessários.
Utilize filtros de período e demais filtros disponíveis.
Processe os resultados em lotes menores sempre que possível.
Mantenha o controle local do último registro ou período processado.
Evite consultar novamente informações que já foram processadas.
Trate adequadamente respostas HTTP 429 e outros erros.
Evite múltiplas requisições simultâneas para o mesmo recurso.
Registre erros e informações suficientes para permitir o diagnóstico da integração.
Nota
Uma integração eficiente não é aquela que realiza o maior número possível de requisições, mas aquela que consegue obter as informações necessárias realizando a menor quantidade possível de consultas.
Exemplo de Estratégia para Consulta Periódica
Para uma integração que precisa acompanhar novos registros de histórico, uma estratégia recomendada é utilizar consultas incrementais.
Suponha que a integração tenha processado registros até 10:00. Na próxima execução, em vez de consultar novamente todo o histórico das últimas 24 horas, a integração deve consultar somente o período posterior ao último ponto processado.
Dessa forma, o fluxo será semelhante a:
primeira execução: consulta do período inicial definido;
processamento e armazenamento dos registros;
armazenamento local do último período processado;
próxima execução: consulta somente dos registros posteriores ao último período processado;
atualização do controle local após o processamento bem-sucedido.
Essa estratégia reduz consultas duplicadas, diminui o volume de dados transferidos e torna a integração mais eficiente e previsível.
Atenção
O desenvolvimento de uma integração deve considerar os limites da API desde o início do projeto.
Nota
Não é recomendado desenvolver uma solução que dependa de consultas excessivamente frequentes, consultas sem filtros ou repetição contínua de grandes períodos de histórico.
Resumo das Principais Recomendações
Para obter o melhor desempenho e evitar bloqueios ou respostas HTTP 429, considere as seguintes recomendações:
Consulte somente o que for necessário.
Utilize IDs para filtrar os recursos desejados.
Evite consultas sem filtros.
Prefira consultas incrementais para históricos.
Evite consultar repetidamente o mesmo período.
Utilize paginação quando disponível.
Reduza o período consultado quando houver muitos registros.
Controle a quantidade de requisições realizadas pela integração.
Evite requisições simultâneas desnecessárias.
Trate corretamente o HTTP 429.
Não realize novas tentativas imediatamente após um HTTP 429.
Mantenha localmente o controle dos registros já processados.
Utilize o histórico de Alarmes para processamento histórico, evitando `polling` intensivo.
Projete a integração considerando os limites da API desde o início.