acessibilidade

Prefeitura Municipal de Cidade Gaucha

conteúdo principal

Regras de Utilização da API

1. Autenticação

O acesso à API exige envio de um token válido no cabeçalho da requisição.
⚠️ Use o campo: Authorization: Bearer <seu-token> e Content-Type: application/json

2. URL Base

O endpoint principal é definido como: https://api.transparencia.sua-cidade.rs.gov.br/api/v1/

3. Recursos Disponíveis
  • Legislação: POST /legislacao - lista leis e atos normativos com filtros (busca, por_pagina)
  • Contratos: POST /contratos - filtra por termo de busca, ano (integer), situação (ativo ou inativo)
  • Obras: POST /obras - permite pesquisar com filtros como termo, status e período
4. Formato da Resposta

Todas as respostas estão no formato JSON com estrutura padronizada incluindo: success, message, data e pagination.

5. Códigos HTTP Utilizados
  • 200 – Sucesso
  • 201 – Criado com sucesso
  • 400 – Erro de validação
  • 401 – Não autorizado
  • 404 – Não encontrado
  • 500 – Erro interno do servidor
6. Diretrizes de Uso Geral
  • Utilize somente dados públicos em formatos abertos e estruturados, conforme previsto na Lei de Acesso à Informação (Lei nº 12.527/2011)
  • Respeite limites e filtros dos endpoints, evitando sobrecarga ou solicitações excessivas
  • Mantenha seu token seguro e evite compartilhá-lo em público
  • Trate erros HTTP corretamente no código do cliente, implementando lógica de re-tentativa conforme necessário
  • É obrigatório citar a fonte dos dados em qualquer uso ou redistribuição
  • O usuário é responsável integralmente pelo uso dos dados obtidos através da API
Resumo das Principais Regras
  • Token único: Sempre enviado em cabeçalho (Authorization)
  • Endpoints ativos: legislação, contratos, obras
  • Resposta JSON: Inclui success, message, data, pagination
  • Boa prática: Solicitar apenas dados públicos e tratar erros
Palavras-chave: API, autenticação, dados abertos, transparência

Documentação da API

Esta documentação descreve os endpoints disponíveis na API e como utilizá-los.

URL Base da API
http://seu-dominio.com.br:3000/api/v1

Autenticação

Todas as requisições devem incluir o token no header: 

Authorization Bearer SEU_TOKEN_AQUI

Legislação

POST /legislacao

Lista todas as legislações com filtros.

Parâmetros
Campo Tipo Descrição
busca string Termo para busca
por_pagina integer Itens por página (default: 10)
Exemplo
                    curl -X POST http://seu-dominio.com.br:3000/api/v1/legislacao \
                            -H "Authorization: Bearer seu-token" \
                            -H "Content-Type: application/json" \
                            -d '{
                                    "busca": "lei",
                                    "por_pagina": 10
                            }'
POST /legislacao/detalhe

Retorna detalhes de uma legislação específica.

Parâmetros
Campo Tipo Descrição
id integer ID da legislação
Exemplo
                    curl -X POST http://seu-dominio.com.br:3000/api/v1/legislacao/detalhe \
                            -H "Authorization: Bearer seu-token" \
                            -H "Content-Type: application/json" \
                            -d '{
                                    "id": 1
                            }'

Contratos

POST /contratos

Lista todos os contratos com filtros.

Parâmetros
Campo Tipo Descrição
busca string Termo para busca
ano integer Ano do contrato
situacao string Status do contrato (ativo/inativo)
Exemplo
curl -X POST http://seu-dominio.com.br:3000/api/v1/contratos \
     -H "Authorization: Bearer seu-token" \
     -H "Content-Type: application/json" \
     -d '{
         "busca": "construção",
         "ano": 2025,
         "situacao": "ativo"
     }'
POST /contratos/detalhe

Retorna detalhes de um contrato específico.

Parâmetros
Campo Tipo Descrição
id integer ID do contrato
Exemplo
curl -X POST http://seu-dominio.com.br:3000/api/v1/contratos/detalhe \
     -H "Authorization: Bearer seu-token" \
     -H "Content-Type: application/json" \
     -d '{
         "id": 1
     }'

Obras

POST /obras

Lista todas as obras com filtros.

Parâmetros
Campo Tipo Descrição
busca string Termo para busca no título
situacao string Status da obra (em_andamento/concluida/paralisada)
data_inicial date Data inicial (Y-m-d)
data_final date Data final (Y-m-d)
Exemplo
curl -X POST http://seu-dominio.com.br:3000/api/v1/obras \
     -H "Authorization: Bearer seu-token" \
     -H "Content-Type: application/json" \
     -d '{
         "busca": "pavimentação",
         "situacao": "em_andamento",
         "data_inicial": "2025-01-01"
     }'
POST /obras/detalhe

Retorna detalhes de uma obra específica.

Parâmetros
Campo Tipo Descrição
id integer ID da obra
Exemplo
curl -X POST http://seu-dominio.com.br:3000/api/v1/obras/detalhe \
     -H "Authorization: Bearer seu-token" \
     -H "Content-Type: application/json" \
     -d '{
         "id": 1
     }'

Formato das Respostas

{
                                "success": true/false,
                                "message": "Mensagem descritiva",
                                "data": {
                                    // Dados da resposta
                                },
                                "pagination": {
                                    "total": 100,
                                    "per_page": 10,
                                    "current_page": 1,
                                    "last_page": 10
                                }
                            }

Códigos de Status HTTP

Código Descrição
200 Sucesso
201 Criado com sucesso
400 Erro de validação
401 Não autorizado
404 Não encontrado
500 Erro interno do servidor
Índice

O site da Prefeitura não utiliza cookies e tecnologias semelhantes.

Ver Termo