1. Introdução

Este guia estabelece as diretrizes técnicas e especificações para que desenvolvedores, pesquisadores, analistas de BI, sistemas externos e agentes de Inteligência Artificial possam consumir de forma autônoma os dados abertos governamentais do município de Poços de Caldas / MG.

A API adota o padrão RESTful, respondendo a requisições HTTP GET com payloads estruturados em JSON (codificação UTF-8), além de disponibilizar exportações diretas em formatos abertos (CSV e XML).

2. Autenticação (Headers)

Todas as chamadas à API de Dados Abertos devem conter um token de autenticação válido transmitido nos cabeçalhos (Headers) da requisição HTTP. A API suporta dois formatos de envio:

Nota: O token pode ser gerado diretamente pelo portal na página principal de Dados Abertos ou na documentação interativa da API.

3. Tipos de Tokens e Limites de Requisição (Rate Limiting)

Os limites operacionais e os prazos de validade são determinados pela categoria da credencial gerada:

4. Especificação do Endpoint e Parâmetros de Consulta

O parâmetro modulo é obrigatório e deve conter o ID numérico do módulo desejado (ex: modulo=32 para Legislação, modulo=12 para Convênios/Parcerias, modulo=6 para Carta de Serviços).

Parâmetros Opcionais de Filtragem e Paginação:

• tab - Especifica o sub-módulo dinâmico ou aba a consultar. Exemplo em Legislação: &tab=leis-ordinarias, &tab=decretos. Exemplo em Convênios: &tab=recebidos, &tab=realizados.
• page - Número da página (de 1 até 1000). A API retorna até 100 registros por página. Padrão: 1. Exemplo: &page=2 (retorna registros de 101 a 200).
• campos - Projeção seletiva de colunas separadas por vírgula para otimização de tráfego. Exemplo: &campos=id,numero,ementa,link_lei. Se omitido, todas as propriedades são retornadas.
• q - Busca textual multi-termo abrangente (máx. 200 caracteres). Realiza pesquisa inteligente sobre todos os campos textuais (`"searchable": true`). Cada palavra digitada é tratada individualmente com lógica AND contextual, com suporte completo e simultâneo a acentos, sem acento, entidades HTML e números. Exemplo: &q=transporte%20escolar%202024.
• exercicio - Filtra registros por um ano ou lista de anos separados por vírgula (em módulos que possuem campo de ano/exercício). Exemplo: &exercicio=2023,2024.
• campo_periodo e periodo - Filtro por intervalo de datas. O parâmetro campo_periodo indica a coluna de data (ex: data_publicacao) e periodo recebe o intervalo no formato DD/MM/AAAA ate DD/MM/AAAA ou uma data única DD/MM/AAAA. Exemplo: &campo_periodo=data_publicacao&periodo=01/01/2024 ate 31/01/2024.

Exemplo Completo de Requisição:

5. Formato de Retorno e Estruturas de Dados

O corpo da resposta é estruturado em JSON nativo UTF-8. Cada registro retornado possui tipagem padronizada:

Tipos de Dados Primitivos:

• string - Textos, títulos, ementas e descrições. Entidades HTML são convertidas para texto limpo legível.
• int - Identificadores e números inteiros (ex: id, numero, ano).
• float - Valores monetários e decimais de dupla precisão (ex: valor_total, valor_repasse).
• date / datetime - Datas e carimbos de tempo no padrão internacional ISO-8601 (YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS).

Tipos de Dados Estruturados e Arquivos:

• file - URL absoluta pronta para visualização e download direto do arquivo (ex: PDFs de leis com resolução dinâmica de pastas anuais). Exemplo: "https://www.servicos.pocosdecaldas.mg.gov.br/uploads/leis/2024/decreto1234.pdf".
• file_array - Lista contendo as URLs públicas de todos os anexos ou fotos associadas ao registro. Exemplo: ["https://www.servicos.pocosdecaldas.mg.gov.br/uploads/servicos/capa.jpg"].
• array (Sub-listas Relacionais / Loaders) - Estruturas aninhadas com relacionamentos um-para-muitos (ex: atos incidentes e decorrentes em Legislação, execuções financeiras em Parcerias).

6. Exemplos de Implementação

Abaixo estão exemplos prontos para consumo da API nas principais linguagens e ferramentas analíticas:

curl -X GET "https://www.servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=32&page=1" \
  -H "X-API-Token: SEU_TOKEN_AQUI" \
  -H "Accept: application/json"

<?php
$url = 'https://www.servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=32&page=1';
$token = 'SEU_TOKEN_AQUI';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-API-Token: ' . $token,
    'Accept: application/json'
));

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code === 200) {
    $dados = json_decode($response, true);
    print_r($dados);
} else {
    echo "Erro HTTP: $http_code - Resposta: $response";
}
?>

async function consultarDadosAbertos() {
  const url = 'https://www.servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=32&page=1';
  const token = 'SEU_TOKEN_AQUI';

  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'X-API-Token': token,
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const erro = await response.json();
      console.error(`Erro ${response.status}:`, erro.mensagem);
      return;
    }

    const dados = await response.json();
    console.log('Dados recebidos:', dados);
  } catch (err) {
    console.error('Falha na requisicao:', err);
  }
}

consultarDadosAbertos();

import requests

url = 'https://www.servicos.pocosdecaldas.mg.gov.br/api/dados_abertos'
params = {'modulo': 32, 'page': 1}
headers = {'X-API-Token': 'SEU_TOKEN_AQUI', 'Accept': 'application/json'}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    dados = response.json()
    print(f"Recebidos {len(dados)} registros.")
    print(dados)
else:
    print(f"Erro {response.status_code}: {response.text}")

let
    Url = "https://www.servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=32&page=1",
    Fonte = Json.Document(Web.Contents(Url, [Headers=[#"X-API-Token"="SEU_TOKEN_AQUI", #"Accept"="application/json"]])),
    Tabela = Table.FromList(Fonte, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    Expandido = Table.ExpandRecordColumn(Tabela, "Column1", Record.FieldNames(Fonte{0}))
in
    Expandido

7. Revalidação de Tokens Ativos

Caso possua uma credencial de sessão ou de longa duração ativa próxima do vencimento, é possível renovar sua validade por período equivalente ao original de forma transparente, sem a necessidade de reautenticar com senha ou credenciais mestras. A operação emite um novo token e invalida o anterior com segurança.

A revalidação é realizada enviando uma requisição POST:

Exemplo de Resposta de Sucesso:

[
  {
    "Situacao": "event",
    "Resposta": "sucesso",
    "token": "NOVO_TOKEN_CRIPTOGRAFADO_GERADO",
    "id": 150,
    "id_antigo": 149,
    "tipo": "long",
    "expiracao": "2026-12-31 23:59:59"
  }
]

8. Códigos de Retorno HTTP e Tratamento de Erros

A API de Dados Abertos utiliza códigos de status HTTP padronizados para indicar o sucesso ou o motivo de falha em cada requisição. Todas as mensagens de erro retornam um objeto JSON explicativo com as propriedades status e mensagem.

Exemplos de Resposta de Erro (JSON):

{
  "status": "erro",
  "mensagem": "Este token expirou."
}

{
  "status": "erro",
  "mensagem": "Parametro \"modulo\" (ID valido) nao fornecido."
}

{
  "status": "erro",
  "mensagem": "Limite de requisicoes por hora atingido para este token de longa duracao (maximo de 500 requisicoes/hora)."
}

{
  "status": "erro",
  "mensagem": "Modulo nao encontrado ou sem dados abertos configurados."
}