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.
• q - Busca textual aberta flexível (limitada a no máximo 200 caracteres). Pesquisa em todos os campos textuais configurados no módulo. Espaços são interpretados como curingas (%), permitindo encontrar termos não contíguos. Se o termo for numérico, a busca englobará também campos do tipo int ou float. Exemplo: &q=educacao%20infantil.
• periodo e campo_periodo - Filtro baseado em data. O campo_periodo especifica em qual coluna do banco de dados o filtro atuará (ex: data_publicacao), e o periodo deve seguir o formato DD/MM/AAAA ate DD/MM/AAAA ou apenas DD/MM/AAAA para uma data única. Exemplo: &campo_periodo=data_publicacao&periodo=10/05/2023 ate 15/05/2023.

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://www.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://www.servicos.pocosdecaldas.mg.gov.br/api/dados_abertos?modulo=12&tab=recebidos&page=1"

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.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://www.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://www.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

7. Revalidação de Tokens Ativos

Caso possua uma credencial de sessão ou de longa duração que ainda esteja ativa, é possível estender a sua validade por um período equivalente ao do token original, sem a necessidade de fornecer novamente as chaves de segurança. Essa operação invalida permanentemente o token anterior, substituindo-o pelo novo.

A revalidação pode ser executada por meio de uma requisição HTTP com o método POST para o endpoint da API:

Cabeçalhos (Headers) necessários:

Parâmetros no corpo da requisição (POST):

• acao - Deve possuir o valor fixo revalidar_token.
• token_atual - (Opcional se enviado no cabeçalho) O token ativo que será revalidado.

Exemplo de Resposta de Sucesso:

[
  {
    "Situacao": "event",
    "Resposta": "sucesso",
    "token": "NOVO_TOKEN_CRIPTOGRAFADO",
    "id": 123,
    "id_antigo": 122,
    "tipo": "long",
    "expiracao": "YYYY-MM-DD HH:MM:SS"
  }
]