API PNCP: Swagger, endpoints e parâmetros de consulta

API REST pública em pncp.gov.br/api/consulta/v1/ com dados abertos de atas, contratações, contratos e PCAs. Nesta página: os 12 endpoints com parâmetros obrigatórios, erros comuns (400, 204, limites de página), o Swagger UI e o status da API ao vivo, logo abaixo.

Por que monitorar a API separada do Portal?

O Portal PNCP (consultado por humanos no navegador) e esta API REST (consumida por sistemas) são produtos com infraestruturas e padrões de tráfego diferentes. Costumam falhar de forma independente: o site pode cair sem afetar a API, e vice-versa.

O que fazer durante uma instabilidade da API

• Implemente backoff exponencial em consumidores — gov.br tem rate-limit por IP.
• Cache local da última resposta válida evita perder dados durante quedas curtas.
• Endpoints de janela longa (publicação) são mais lentos — prefira /v1/atas ou /v1/contratacoes/proposta para health-check.

Swagger do PNCP: onde encontrar a documentação da API

O Swagger UI oficial da API de consulta fica em pncp.gov.br/api/consulta/swagger-ui/index.html. Nele você explora todos os endpoints, parâmetros e schemas de resposta, e pode testar chamadas direto no navegador — sem autenticação, pois a API de consulta é pública. Quando a API cai, o Swagger geralmente cai junto; confira o status acima antes de assumir erro no seu código.

Endpoints da API de consulta do PNCP

Base: https://pncp.gov.br/api/consulta — todos os endpoints são GET, públicos e sem autenticação. A API expõe 12 operações, agrupadas em contratações, atas, contratos/empenhos, instrumentos de cobrança e planos de contratação.

/v1/contratacoes/publicacao

O endpoint mais usado: lista contratações publicadas num intervalo de datas. Exige o código da modalidade — não existe consulta "de todas as modalidades" numa chamada só; para varrer tudo, itere sobre os códigos.

• Obrigatórios: dataInicial, dataFinal, codigoModalidadeContratacao, pagina
• Opcionais: codigoModoDisputa, uf, codigoMunicipioIbge, cnpj, codigoUnidadeAdministrativa, idUsuario, tamanhoPagina
• Limite de página: tamanhoPagina vai de 10 a 50

/v1/contratacoes/proposta

Retorna contratações com o período de recebimento de propostas em aberto — é o endpoint certo para quem procura oportunidades ainda disputáveis. Atenção: ele aceita apenas dataFinal. Mandar dataInicial aqui é um erro comum, porque os outros endpoints pedem os dois.

• Obrigatórios: dataFinal, pagina
• Opcionais: codigoModalidadeContratacao, uf, codigoMunicipioIbge, cnpj, codigoUnidadeAdministrativa, idUsuario, tamanhoPagina
• Limite de página: 10 a 50

/v1/atas e /v1/contratos

Atas de registro de preço por período de vigência e contratos/empenhos por data de publicação. Ambos aceitam janelas maiores por página que as contratações.

• /v1/atas: obrigatórios dataInicial, dataFinal, pagina; opcionais idUsuario, cnpj, codigoUnidadeAdministrativa
• /v1/contratos: obrigatórios dataInicial, dataFinal, pagina; opcionais cnpjOrgao, codigoUnidadeAdministrativa, usuarioId
• Limite de página: 10 a 500 nos dois

Erros comuns ao consumir a API

Boa parte dos 400 Bad Request vem de cinco detalhes que a documentação não destaca:

1. Datas no formato yyyyMMdd, sem hífens. 20260101, não 2026-01-01.
2. pagina é obrigatório em todos os endpoints de listagem e começa em 1. Omitir é a causa mais frequente de 400. (A única exceção é a consulta de uma contratação específica por CNPJ/ano/sequencial, que não pagina.)
3. O teto de tamanhoPagina muda por endpoint: 50 nas contratações, 100 nos instrumentos de cobrança, 500 em atas, contratos e PCA. O mínimo é 10 em todos.
4. /v1/pca/atualizacao usa dataInicio e dataFim — e não dataInicial/dataFinal como o resto da API. É uma inconsistência real da spec.
5. Sem resultados devolve 204 No Content, não um 200 com lista vazia. Cliente que assume corpo JSON sempre presente quebra nesse caso.

Além do 400, todas as operações declaram 422 Unprocessable Entity para erro de validação de parâmetro — trate os dois como erro do cliente (sem retry), ou seu consumidor entra em loop de tentativas num request que nunca vai passar.

As respostas paginadas vêm num envelope com data, totalRegistros, totalPaginas, numeroPagina, paginasRestantes e empty — use paginasRestantes para decidir se continua iterando.

Documentação oficial

• Swagger UI
• Manuais oficiais PNCP