{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"70f1eeef-7a37-41db-b0ef-cc1fec843fd8","name":"Documentação da API do Portal de Telemetria (11/2025)","description":"Esta documentação descreve a utilização e exemplifica o uso dos _endpoints_ básicos da API REST do Portal de Telemetria.\n\nEstes são responsáveis por interagir com as diversas entidades do Portal, como prover acesso aos registros de Histórico de Dados e Alarmes, valores dos Dados coletados pelo Portal, informações de Conectores, Dispositivos, Dados e Alarmes, além de outras interações diversas.\n\nPara maiores informações sobre os recursos do Portal de Telemetria, acesse o [Manual do Usuário](https://doc.hitecnologia.com.br/portal_telemetria/br/).\n\nRecomendamos que antes de utilizar essa documentação, seja feita a leitura e compressão dos [conceitos básicos](https://doc.hitecnologia.com.br/portal_telemetria/br/_files/glb_introducao.html#conceitos-basicos) do Portal de Telemetria\n\nEm caso de dúvidas, entre em contato conosco através dos [nossos canais de suporte](https://www.hitecnologia.com.br/suporte/).\n\n## **Configuração da URL Base da API**\n\nO Portal de Telemetria é acessado através de uma URL que inicia com o subdomínio \"app\". Por exemplo, o Portal de Telemetria da HI está disponível em:\n\n`https://app.telemetria.hitecnologia.com.br/`\n\nPara acessar a API e realizar requisições aos endpoints documentados, substitua o subdomínio \"app\" por \"api\":\n\n`https://api.telemetria.hitecnologia.com.br/`\n\n### **Clientes White Label**\n\nPara implementações White Label, utilize a mesma lógica de substituição do subdomínio. Se seu Portal de Telemetria está hospedado em:\n\n`https://app.nomedaempresa.com.br/`\n\nA URL base da API correspondente será:\n\n`https://api.nomedaempresa.com.br/`\n\n> **Importante:** Certifique-se de utilizar a URL específica da sua instalação para todas as chamadas à API. \n  \n\n## Métodos de Autenticação\n\nNa API do Portal de Telemetria existem dois métodos de autenticação para utilização dos endpoints:\n\n### Autenticação Básica\n\nO primeiro método é conhecido como **Basic Authentication,** ou Autenticação Básica, sendo este o método de autenticação mais comum do protocolo HTTP.\n\nNeste método, deve ser incluído no cabeçalho(header) de cada requisição para a API, a constante **Authorization: Basic** seguida pelas informações do e-mail e senha do usuário de autenticação(do Portal) no formato **e-mail:senha** e codificados em **Base 64**(a senha do usuário já deve estar codificada em Base 64 também).\n\nExemplo:\n\n[<b>teste@teste.com.br</b>](https://mailto:teste@teste.com.br)**:teste123** codificado em Base 64 = **dGVzdGVAdGVzdGUuY29tLmJyOnRlc3RlMTIz**\n\nPortanto, o conteúdo final a ser utilizado no cabeçalho da requisição seria:\n\n> Authorization: Basic dGVzdGVAdGVzdGUuY29tLmJyOnRlc3RlMTIz \n  \n\n### JSON Web Token (JWT)\n\nO segundo método é gerando um **JSON Web Token (JWT)**, que é reutilizável. Neste formato é passado no corpo da requisição do endpoint de **login** em formato JSON os campos \"email\" e \"password\" (sendo a senha já em codificada em _Base 64_) para se obter um token autenticado e válido. A URL para realizar esta requisição de POST e obter as informações desejadas é a seguinte:\n\n`https://api.telemetria.hitecnologia.com.br/rest/v1/auth/login/`\n\nNa resposta dessa requisição, serão retornados os campos **token, expiration_at, refresh_expiration_at**, além de outros anexos. O token deve ser passado em cada requisição através de um cabeçalho(header) específico conforme exemplo abaixo:\n\n> Authorization: Bearer (conteúdo do token) \n  \n\nÉ necessário se atentar à validade do token para sempre mantê-lo válido através do endpoint de atualização de token:\n\n`https://api.telemetria.hitecnologia.com.br/rest/v1/auth/login_refresh/`\n\nPara mais informações de como usar o login com token, acesse a **Gerência de Usuários e Controle de Acesso**.\n\n## Restrições e Limitações da API\n\nPara manter a integridade da API do Portal de Telemetria, algumas restrições e limitações são impostas na sua utilização:\n\n#### **Número de Requisições**\n\nTodos 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.\n\nAlém disso, as requisições são contabilizadas em duas janelas de tempo, sendo uma por minuto e outra no período de 24 horas.\n\n| **Tipo de Requisição** | **Limitação** |\n| --- | --- |\n| Endpoints de Histórico | Máximo de **1 requisição por minuto ou 288 por dia** (em média, 1 requisição a cada 5 minutos) |\n| Endpoints de Comandos (Escrita e Reconhecimento de Alarme) | Máximo de **6 requisição por minuto ou 1.440 por dia** (em média, 1 requisição por minuto) |\n| Demais endpoints | Máximo de **2 requisições por minuto ou 1.440 por dia** (em média, 1 requisição por minuto) |\n\nCaso ultrapasse o limite do número de requisições, será retornado um erro **HTTP de código 429**.\n\nÉ importante que ao receber o primeiro retorno **HTTP 429**, a sua integração aguarde uma nova janela de requisições para não ocorrer no mesmo erro.\n\n#### **Número de Registros**\n\nPara 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:\n\n| **Tipo de Histórico** | **Limitação** |\n| --- | --- |\n| Histórico de Dados | Até **90 mil** registros |\n| Histórico de Alarmes | Até **30 mil** registros |\n| Histórico de Eventos | Até **10 mil** registros |\n\nNeste 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.\n\n#### **Período de Consulta**\n\nPara os endpoints de histórico, existe um limite do período de registros que podem ser consultados. Neste caso, os endpoints de histórico utilizam os seguintes períodos máximos:\n\n| **Tipo de Histórico** | **Limitação** |\n| --- | --- |\n| Histórico de Dados | Até **30 dias** |\n| Histórico de Alarmes | Até **30 dias** |\n| Histórico de Eventos | Até **7 dias** |\n\nSe 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.\n\n## Paginação\n\nEm nossos endpoints de listagem, podem ser utilizados alguns parâmetros na requisição que aplicam uma paginação nos resultados retornados pela API e permitem utilizá-la de maneira mais eficiente:\n\n- **Número de páginas:**\n    \n\n| **Parâmetro** | **Descrição** |\n| --- | --- |\n| page_size | Valor inteiro com o número máximo de registros que devem ser retornados na coleção(tamanho da página). |\n| page | Valor inteiro com o número da página a serem retornados na coleção. Deve ser utilizado em conjunto com **page**. |\n\nExemplo de requisição para o endpoint de Histórico de Dados(documentado a seguir):\n\n`https://api.telemetria.hitecnologia.com.br/rest/v1/data_history/?data_id=999&page=2&page_size=50`\n\nExemplo de resposta(simplificado):\n\n``` json\n{\n    \"count\": 100,\n    \"previous_page\": null,\n    \"previous_page_number\": null,\n    \"next_page\": \"https://api.telemetria.hitecnologia.com.br/rest/v1/data_history/?data_id=999&page=2&page_size=50\",\n    \"next_page_number\": 2,\n    \"results\": [\n        {\n            ...\n        }\n    ]\n}\n\n ```\n\n- **Blocos de registros:**\n    \n\n| **Parâmetro** | **Descrição** |\n| --- | --- |\n| limit | Valor inteiro com o número máximo de registros que devem ser retornados na coleção. |\n| offset | Valor inteiro com o deslocamento de registros a serem retornados na coleção. Deve ser utilizado em conjunto com **limit**. |\n\nExemplo de requisição para o endpoint do Histórico de Dados(documentado a seguir):\n\n`https://api.telemetria.hitecnologia.com.br/rest/v1/data_history/?data_id=999&offset=0&limit=50`\n\nExemplo de resposta(simplificado):\n\n``` json\n{\n    \"count\": 100,\n    \"previous_page\": null,\n    \"previous_page_offset\": null,\n    \"next_page\": \"https://api.telemetria.hitecnologia.com.br/rest/v1/data_history/?data_id=999&offset=0&limit=50\",\n    \"next_page_offset\": 50,\n    \"results\": [\n        {\n            ...\n        }\n    ]\n}\n\n ```\n\n## Obtendo o ID(identificador) e referência dos Recursos na API\n\nNormalmente, nos endpoints da API, deve-se utilizar o ID(identificador) ou referencia do(s) recurso(s) como **Conectores**, **Dispositivos**, **Dados** e **Alarmes**. que se deseja acessar, filtrar, etc.\n\nO identificador de um recurso é um número inteiro e pode ser obtido diretamente na URL apresentada na página de cadastro do recurso desejado.\n\nVamos há alguns exemplos:\n\n##### Conector de ID = 1\n\n`https://app.telemetria.com.br/dashboard/edit/connector/1#edit`\n\n##### Dispositivo de ID = 15\n\n`https://app.telemetria.com.br/dashboard/edit/connector/1/device/15#edit`\n\n##### Dado de ID = 250\n\n`https://app.telemetria.com.br/dashboard/edit/connector/1/device/15/data/250#edit`\n\n##### Alarme de ID = 1500\n\n`https://app.telemetria.com.br/dashboard/edit/connector/1/device/15/data/250/alarm/1500#edit`\n\nJá a referência de um recurso é um hash de 8 caracteres que o identifica unicamente no contexto de um Conector(no caso de Dispositivos, Dados e Alarmes) e no contexto de um Contrato(no caso de Conectores).\n\n`Exemplo: 8a92fd7f`\n\nNa API, esta referência é encontrada em um atributo chamado **reference_id** presente no objeto JSON de representação de cada recurso.\n\nA opção por utilizar o **reference_id** ao invés do ID dos recursos é extremamente útil principalmente no cenário em que são utilizados [Conectores de Instância de Modelo](https://doc.hitecnologia.com.br/portal_telemetria/br/_files/glb_model_concept.html).\n\nNeste cenário, o **reference_id é igual** entre os Dispositivos, Dados e Alarmes do Conector de Modelo e seus Conectores de Instância, o que viabiliza a reutilização do mesmo código para tratar Conectores de Instância diferentes.\n\nPorém, é importante observar que, caso se opte por utilizar o **reference_id** para obter os recursos de um Conector de Instância de Modelo, deve-se utilizar nos filtros ou payloads dos endpoints o ID desse Conector ou o seu próprio **reference_id** para que a API atue exatamente nos recursos desejados.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"20304836","team":3287907,"collectionId":"70f1eeef-7a37-41db-b0ef-cc1fec843fd8","publishedId":"2s93sc4CAy","public":true,"publicUrl":"https://documenter-api.postman.tech/view/20304836/2s93sc4CAy","privateUrl":"https://go.postman.co/documentation/20304836-70f1eeef-7a37-41db-b0ef-cc1fec843fd8","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0072C7"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/0aadb4b0-ec7b-418d-beb5-751f81435cfe/YUdsb1pXRmtaWEl1YW5Cbi5qcGc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"0072C7"}},{"name":"light","logo":"https://content.pstmn.io/0aadb4b0-ec7b-418d-beb5-751f81435cfe/YUdsb1pXRmtaWEl1YW5Cbi5qcGc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0072C7"}}]}},"version":"8.11.4","publishDate":"2023-06-13T14:06:30.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/0aadb4b0-ec7b-418d-beb5-751f81435cfe/YUdsb1pXRmtaWEl1YW5Cbi5qcGc=","logoDark":"https://content.pstmn.io/0aadb4b0-ec7b-418d-beb5-751f81435cfe/YUdsb1pXRmtaWEl1YW5Cbi5qcGc="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/4d8ffa3d5ed89bbfb3e51c8c5ad9fdb136fd2b7dffa285071ebf86de0d2934bf","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2s93sc4CAy"}