Documentação da API do Portal
O Portal de Telemetria oferece uma API REST para permitir a integração e o acesso programático a diversos de seus recursos. Esta API facilita a comunicação entre o Portal e outras plataformas, sistemas ou serviços, possibilitando a automação e o intercâmbio de informações.
Atenção
A utilização da API REST esta 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 dos equipamentos remotos.
Monitorar o status de equipamentos: verificar o status de conexão (online/offline) dos equipamentos remotos.
Obter dados de histórico: consultar e utilizar os registros de histórico de Dados e Alarmes.
Envio de comandos: realizar escritas nos Dados asscociados as variáveis dos equipamentos remotos.
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.
- Playlist de Vídeos Explicativos:
Para uma compreensão visual e prática do recurso, assista à nossa playlist com vídeos detalhados sobre como utilizar a API.
Restrições e Limitações da API
Para manter a integridade da API do Portal de Telemetria, algumas restrições e limitações são impostas na sua utilização:
Atenção
A API do Portal de Telemetria possui restrições de uso para manter a integridade do serviço. É obrigatório consultar e seguir as diretrizes detalhadas na Documentação.
Número de Requisições
Todos os endpoints da API possuem um limite de requisições (throttling) em sua utilização. Estes limites se diferenciam para requisições em endpoints que lidam com registros históricos e os demais endpoints da API.
Além disso, as requisições são contabilizadas em duas janelas de tempo, sendo uma por minuto e outra no por dia (período de 24 horas).
Dependendo do Tipo de Requisição:
Endpoints de Histórico
Máximo de 1 requisição por minuto;
Até 288 por dia;
Em média por dia: 1 requisição a cada 5 minutos.
Endpoints de Comandos (Escrita e Reconhecimento de Alarme)
Máximo de 6 requisição por minuto;
Até 1.440 por dia;
Em média por dia: 1 requisição a cada minuto.
Demais Endpoints
Máximo de 2 requisições por minuto;
Até 1.440 por dia;
Em média por dia: 1 requisição a cada minuto.
Atenção
Caso ultrapasse o limite do número de requisições, será retornado um erro HTTP de código 429. É importante que ao receber o primeiro retorno HTTP 429, a sua integração aguarde uma nova janela de requisições para não ocorrer o mesmo erro.
Número de Registros
Para os endpoints de histórico, existe um limite do número de registros que podem ser retornados em uma única requisição de acordo com o tipo de histórico:
Tipo de Histórico |
Limitação |
|---|---|
Dados |
Até 90 mil registros |
Alarmes |
Até 30 mil registros |
Eventos |
Até 10 mil registros |
Atenção
Neste caso, pode-se utilizar a Paginação da API para se trabalhar com um conjunto máximo de registros definidos ou caso seja retornado exatamente um número de registros igual ao limite, deve-se considerar utilizar filtros mais restritos ou realizar outras requisições.
Período de Consulta
Para os endpoints de histórico, existe um limite do período de registros (em dias) que podem ser consultados.
Neste caso, os endpoints de histórico utilizam os seguintes períodos máximos:
Tipo de Histórico |
Limitação |
|---|---|
Dados |
Até 30 dias |
Alarmes |
Até 30 dias |
Eventos |
Até 7 dias |
Atenção
Se não for especificado um período de consulta para os endpoints de histórico, automaticamente a API irá considerar a consulta pelas últimas 24 horas de registros.