1. Introdução

Este guia descreve as diretrizes para desenvolvedores consumirem os dados abertos do município de Poços de Caldas. As requisições são feitas via protocolo HTTP utilizando o método GET e os dados são retornados em formato estruturado JSON.

2. Autenticação (Headers)

Toda requisição para a API de dados abertos deve incluir o token de acesso gerado no cabeçalho HTTP. A API suporta dois formatos de cabeçalho de forma flexível:

3. Tipos de Tokens e Limites de Requisição

Os limites de requisições e tempos de expiração dependem da categoria da credencial gerada:

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

Substitua ID_DO_MODULO pelo identificador numérico do módulo obtido nos cards de dados da página principal.

Parâmetros Opcionais de Consulta:

• page - Determina a página de dados a ser retornada (valores numéricos de 1 até 1000). Cada página retorna no máximo 100 registros. Exemplo: &page=2 (retorna registros do índice 101 ao 200).
• campos - Permite filtrar as propriedades de retorno (separadas por vírgulas), economizando banda e processamento. Exemplo: &campos=id,titulo. Caso omitido ou em branco, todos os campos cadastrados são retornados por padrão.

Exemplo de Módulo Complexo (Convênios e Parcerias - ID: 12):
O módulo de convênios necessita do parâmetro extra tab para especificar qual aba deseja consultar:

• tab=recebidos - Recursos Recebidos
• tab=realizados - Parcerias Realizadas
• tab=acordos - Acordos sem Repasse

5. Formato de Retorno e Estruturas de Dados

A API de dados abertos retorna as respostas no formato JSON estruturado, utilizando codificação UTF-8 nativa. Dependendo das propriedades mapeadas em cada módulo, os campos podem pertencer aos seguintes tipos:

Tipos de Dados Simples:

• string - Cadeia de caracteres simples (ex: títulos, objetos, nomes). As entidades HTML são decodificadas automaticamente em UTF-8 no momento do envio.
• int - Valores numéricos inteiros (ex: id, ano_ref).
• float - Valores decimais de precisão dupla (ex: valor_total, valor_recebido).
• date / datetime - Datas formatadas no padrão ISO-8601 (YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS).

Tipos de Dados Estruturados (Listas e Objetos):

• file_array - Retorna um array contendo as URLs públicas completas dos arquivos salvos (ex: imagens de capa, arquivos anexados), prontas para serem acessadas diretamente. Exemplo: ["https://servicos.pocosdecaldas.mg.gov.br/uploads/servicos/capa.jpg"].
• array (Sub-listas dinâmicas) - Representa relações do tipo um-para-muitos (ex: dotações de uma parceria, execuções financeiras) resolvidas de forma aninhada. Retorna um array contendo sub-objetos com propriedades próprias.

6. Exemplos de Implementação

curl -H "X-API-Token: SEU_TOKEN_AQUI" \
  "https://servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=12&tab=recebidos&page=1"

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=12&tab=recebidos&page=1');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-API-Token: SEU_TOKEN_AQUI'
));
$response = curl_exec($ch);
curl_close($ch);

$dados = json_decode($response, true);
print_r($dados);
?>

fetch('https://servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=12&tab=recebidos&page=1', {
  headers: {
    'X-API-Token': 'SEU_TOKEN_AQUI'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Erro:', error));

let
    Url = "https://servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=12&tab=recebidos&page=1",
    Source = Json.Document(Web.Contents(Url, [Headers=[#"X-API-Token"="SEU_TOKEN_AQUI"]]))
in
    Source