¶ ¶ Endpoint: Contratos (GET /api/v1/contratos)
Este endpoint da API Públicas - CGE permite consultar contratos cadastrados no Portal da Transparência. A operação é do tipo GET, ou seja, é utilizada apenas para leitura/consulta de dados. O retorno é em JSON e pode ser consumido por sistemas, dashboards e integrações.
¶ ¶ Como funciona
- Método: GET (consulta de dados)
- Rota:
/api/v1/contratos - Parâmetros: enviados via query string (ex.:
?page=1&pageSize=10) - Paginação: obrigatória (precisa informar
pageepageSize) - Retorno: JSON com lista de contratos e dados de paginação
¶ ¶ URL base e exemplo de consulta
Exemplo de chamada simples (primeira página com 10 itens):
https://transparencia.api.ro.gov.br/api/v1/contratos?page=1&pageSize=10
Exemplo filtrando por período (data de assinatura):
https://transparencia.api.ro.gov.br/api/v1/contratos?DataInicioAssinatura=2024-01-01&DataFimAssinatura=2024-12-31&page=1&pageSize=10
¶ ¶ Parâmetros de consulta (query)
Abaixo estão os principais parâmetros disponíveis para filtrar os resultados.
Quando não informados, a API retorna os contratos de forma paginada conforme page e pageSize.
| Parâmetro | Tipo | Para que serve | Exemplo |
|---|---|---|---|
| DataInicioAssinatura | string (date-time) | Filtra contratos a partir de uma data de assinatura. | 2024-01-01 |
| DataFimAssinatura | string (date-time) | Filtra contratos até uma data de assinatura. | 2024-12-31 |
| CodigoUnidade | integer (int32) | Filtra pelo código da unidade/órgão. | 1234 |
| Cpf_Cnpj | string | Filtra pelo CPF ou CNPJ do fornecedor/contratado. | 12345678000199 |
| RazaoSocial | string | Filtra pela razão social do fornecedor/contratado. | EMPRESA X |
| Objeto | string | Filtra por texto do objeto do contrato (palavras-chave). | serviços |
| NumeroContrato | string | Filtra pelo número do contrato. | 28/2024 |
| page (obrigatório) | integer (int32) | Número da página a ser retornada. | 1 |
| pageSize (obrigatório) | integer (int32) | Quantidade de registros por página. | 10 / 50 / 100 |
¶ ¶ Retorno (resposta) da API
O retorno geralmente contém informações de paginação e uma lista de contratos. A estrutura exata pode variar conforme a versão, mas normalmente inclui:
- page: página atual
- pageSize: quantidade de itens por página
- total: total de registros encontrados (quando disponibilizado)
- data: lista de contratos retornados
Exemplo ilustrativo de resposta (JSON):
{
"page": 1,
"pageSize": 10,
"total": 345,
"data": [
{
"numeroContrato": "28/2024",
"razaoSocial": "EMPRESA X",
"objeto": "Prestação de serviços...",
"valor": 100000,
"dataAssinatura": "2024-02-01"
}
]
}
¶ ¶ Dicas de uso
- Use page e pageSize para navegar pelos resultados.
- Quando possível, filtre por datas para reduzir volume de dados.
- Para localizar um contrato específico, use NumeroContrato e/ou Cpf_Cnpj.
- Para pesquisa por texto, utilize Objeto e/ou RazaoSocial como palavras-chave.
¶ ¶ Onde visualizar as respostas da API
Após preencher os parâmetros de consulta no Swagger e executar a requisição, os resultados da API são exibidos diretamente na própria interface da documentação.
Ao clicar no botão "Execute", a plataforma retorna a resposta logo abaixo do endpoint, exibindo:
- Os parâmetros utilizados na consulta
- A URL gerada da requisição
- O retorno da API em formato JSON
- As informações de paginação e registros encontrados
A resposta exibida contém a lista de contratos de acordo com os filtros informados, permitindo a visualização dos dados retornados em tempo real.
Essas informações podem ser utilizadas para análise, integração com sistemas ou desenvolvimento de dashboards e aplicações institucionais.
As imagens ilustrativas abaixo demonstram onde o retorno da API é apresentado na interface do Swagger após a execução da consulta.