Rascunho em revisão — esta página ainda não é indexada pelos buscadores.
API do PNCP: como funciona a integração
A API do PNCP é a interface REST oficial pela qual plataformas credenciadas publicam dados no Portal Nacional de Contratações Públicas. A plataforma faz login em /v1/usuarios/login, recebe um token JWT válido por 1 hora e chama os serviços de contratação, ata, contrato, termo e PCA, nos ambientes de treinamento ou de produção. A consulta pública tem API própria.
Atualizado em · Escrito por Mário Dias · Revisado por [PREENCHER: nome do revisor técnico], [PREENCHER: cargo — ex.: responsável técnico pela integração com o PNCP]
Onde está a documentação oficial da API do PNCP?
A documentação tem duas partes: o Manual de Integração, publicado pelo governo em PDF (versão 2.4, de abril de 2026), e a especificação OpenAPI navegável no Swagger de produção e no Swagger de treinamento. O documento JSON da especificação fica em https://pncp.gov.br/api/pncp/v3/api-docs. Há ainda uma API de consultas, pública, com manual próprio.
O manual define o protocolo: REST sobre HTTP 1.1, com dados em JSON. Informações enviadas no cabeçalho devem usar o charset ISO-8859-1, e arquivos enviados, como os JSON usados como parte de um envio multipart, devem ser codificados em UTF-8 (seção 2).
Quais são os ambientes da API do PNCP?
| Ambiente | Portal | URL base (BASE_URL) | Documentação |
|---|---|---|---|
| Homologação externa | https://treina.pncp.gov.br | https://treina.pncp.gov.br/api/pncp | Swagger treina |
| Produção | https://pncp.gov.br | https://pncp.gov.br/api/pncp | Swagger produção |
Como funciona a autenticação na API do PNCP?
As APIs de manutenção (inserção, retificação e exclusão) exigem autenticação; as consultas são públicas. A plataforma credenciada junto ao MGI recebe login e senha e se autentica para obter um JSON Web Token (JWT), que vale por 1 hora a partir da geração. O token vem no cabeçalho Authorization da resposta, depois da palavra Bearer, e deve ser repetido nesse mesmo cabeçalho em cada chamada (seção 3.2). A especificação oficial declara o esquema bearerAuth (HTTP bearer, formato JWT).
curl -i -X POST 'https://treina.pncp.gov.br/api/pncp/v1/usuarios/login' \
-H 'Content-Type: application/json' \
-d '{"login": "<login-da-plataforma>", "senha": "<senha>"}'
# Resposta (cabeçalhos relevantes):
# authorization: Bearer <token>
# expires: 3600000A senha da plataforma segue regras do manual: entre 16 e 64 caracteres, sem conter o login, o nome do usuário ou partes do e-mail, sem sequências de 3 caracteres iguais nem de 4 caracteres crescentes ou decrescentes. A troca de senha ou de login é solicitada pela opção "Gestão de Plataforma" da Área de Trabalho do PNCP (seções 3.2 e 6.1.7).
Quais são os principais endpoints da API do PNCP?
Os caminhos abaixo são relativos à URL base e foram conferidos no Swagger de produção em 03/11/2026. Todos os serviços de manutenção usam o CNPJ do órgão no caminho.
| Serviço | Método e caminho | Corpo |
|---|---|---|
| Login | POST /v1/usuarios/login | JSON |
| Unidades do órgão | POST /v1/orgaos/{cnpj}/unidades | JSON |
| Inserir contratação (edital, aviso ou ato) | POST /v1/orgaos/{cnpj}/compras | multipart: compra + documento |
| Retificar ou excluir contratação | PUT, PATCH, DELETE /v1/orgaos/{cnpj}/compras/{ano}/{sequencial} | JSON |
| Itens e resultados | POST …/compras/{ano}/{sequencial}/itens e …/itens/{numeroItem}/resultados | JSON |
| Inserir ata | POST …/compras/{anoCompra}/{sequencialCompra}/atas | multipart: ata + documento |
| Inserir contrato ou empenho | POST /v1/orgaos/{cnpj}/contratos | multipart: contrato + documento |
| Termos de contrato | POST /v1/orgaos/{cnpj}/contratos/{ano}/{sequencial}/termos | JSON |
| Empenhos do contrato | POST /v1/orgaos/{cnpj}/contratos/{ano}/{sequencial}/empenhos | JSON |
| Plano de contratações anual | POST /v1/orgaos/{cnpj}/pca | JSON |
| Documentos | POST …/arquivos (contratação, ata, contrato, termo) | multipart |
| Domínios (modalidades, amparos, etc.) | GET /v1/modalidades, /v1/amparos-legais, /v1/modos-disputas … | — |
Em 03/11/2026, a especificação tinha 214 operações distribuídas em 34 grupos (tags), entre eles Contratação (26 operações), Plano de Contratação (20), Intenção de Registro de Preço (17), Ata (15), Contrato/Empenho (14) e Termo de Contrato (12). O MeuPNCP lê essa especificação todos os dias e publica as mudanças em novidades da API do PNCP; a situação de cada operação no MeuPNCP está em cobertura da API do PNCP, e os códigos aceitos em cada campo em tabelas de domínio do PNCP.
Exemplo: como enviar uma contratação
A inserção de contratação é multipart/form-data. A parte compra leva o JSON e a parte documento leva o arquivo; os cabeçalhos Titulo-Documento e Tipo-Documento-Id descrevem o arquivo. O serviço exige ao menos um item e aceita até 2.000 itens por requisição (seção 6.3.1).
curl -X POST 'https://treina.pncp.gov.br/api/pncp/v1/orgaos/10000000000003/compras' \
-H 'Authorization: Bearer <token>' \
-H 'Titulo-Documento: Edital' \
-H 'Tipo-Documento-Id: 1' \
-F 'compra=@compra.json;type=application/json' \
-F 'documento=@edital.pdf'{
"codigoUnidadeCompradora": "1010",
"tipoInstrumentoConvocatorioId": "1",
"modalidadeId": "6",
"modoDisputaId": "1",
"numeroCompra": "0001",
"anoCompra": 2023,
"numeroProcesso": "1/2023",
"objetoCompra": "Descrição do objeto da contratação",
"srp": false,
"dataAberturaProposta": "2022-07-21T08:00:00",
"dataEncerramentoProposta": "2022-07-21T17:00:00",
"amparoLegalId": "1",
"itensCompra": [
{
"numeroItem": 1,
"materialOuServico": "S",
"criterioJulgamentoId": "1",
"tipoBeneficioId": "4",
"incentivoProdutivoBasico": false,
"quantidade": 1000,
"descricao": "Item do tipo serviço",
"unidadeMedida": "Unidade",
"orcamentoSigiloso": false,
"valorUnitarioEstimado": 1.5001,
"valorTotal": 1500.00
}
]
}Em caso de sucesso, o PNCP responde 201 com o cabeçalho location e um corpo com compraUri e documentoUri, que contêm o ano e o sequencial gerados para a contratação, como em https://treina.pncp.gov.br/api/pncp/v1/orgaos/10000000000003/compras/2022/1. Guarde esses valores: eles são usados para enviar itens, resultados, atas e contratos.
Quais são os limites da API do PNCP?
| Limite | Valor | Seção do manual |
|---|---|---|
| Itens por inserção de contratação | de 1 a 2.000 | 6.3.1 |
| Itens por inserção de PCA | de 1 a 1.000 | 6.7.1 |
| Tamanho por arquivo de documento | 30 MB | 5.16 |
| Imagens por item da contratação | até 5, com até 3 MB cada | 5.21 |
| Validade do token JWT | 1 hora | 3.2 |
| Senha da plataforma | 16 a 64 caracteres | 3.2 |
O manual não publica limite de requisições por minuto. Mesmo assim, uma boa integração renova o token antes da expiração, em vez de fazer login a cada chamada, e reenvia com cautela em caso de erro 500.
Que regras de negócio a API valida?
Além do formato dos campos, o PNCP valida regras de conformidade entre domínios: instrumento convocatório, modalidade e amparo legal (seção 5.18); instrumento convocatório e modo de disputa (5.19); modalidade e critério de julgamento (5.22); e modalidade e fonte orçamentária (5.26). Também impede contrato de contratação SRP sem ata publicada (5.20) e exclusão de contratação com ata ou contrato ativo (6.3.4). As mensagens reais desses casos estão em erros comuns ao enviar ao PNCP.
Integrar sozinho ou usar um sistema integrador?
Integrar diretamente exige credenciar a plataforma, implementar o multipart de cada serviço, tratar as regras de conformidade e acompanhar as mudanças da especificação, que o PNCP publica sem aviso prévio fixo. O MeuPNCP gera os formulários a partir dos metadados dos endpoints oficiais, compara diariamente o Swagger com esses formulários e guarda URL, corpo, código HTTP e resposta de cada envio. Os módulos estão descritos em módulos, e a importação a partir do ERP em conectores ERP. O passo a passo administrativo está em como publicar no PNCP.
Perguntas frequentes
Qual é a URL da API do PNCP?
A URL base de produção é https://pncp.gov.br/api/pncp, e a do ambiente de homologação externa é https://treina.pncp.gov.br/api/pncp (Manual de Integração, seção 3.1).
Como obter o token da API do PNCP?
Com POST em /v1/usuarios/login, enviando login e senha da plataforma credenciada. O token JWT vem no cabeçalho Authorization da resposta e vale 1 hora.
Qualquer empresa pode usar a API do PNCP para publicar?
Só plataformas credenciadas junto ao MGI e autorizadas pelo gestor do órgão a publicar em nome dele. A consulta aos dados, porém, é pública.
A API do PNCP tem ambiente de teste?
Sim, o ambiente de homologação externa em treina.pncp.gov.br, com Swagger próprio. Em treinamento, a plataforma pode cadastrar órgãos e unidades de teste pela API.
Quantos itens posso enviar numa contratação?
Pelo menos 1 e no máximo 2.000 itens por requisição de inserção de contratação (Manual de Integração, seção 6.3.1).
Onde vejo as mudanças recentes da API do PNCP?
O histórico de versões fica no início do Manual de Integração. O MeuPNCP também publica as diferenças detectadas na leitura diária do Swagger oficial na página de novidades da API do PNCP.
Fontes
- Manual de Integração PNCP, versão 2.4 (abril/2026) — seções 2, 3.1, 3.2, 4.3, 5.16, 5.18 a 5.26, 6.1.4, 6.1.7, 6.3.1 e 6.7.1 (conferido em 03/11/2026)
- Documentação técnica (Swagger/OpenAPI) da API do PNCP — produção (conferido em 03/11/2026)
- Documentação técnica (Swagger/OpenAPI) da API do PNCP — ambiente de treinamento (conferido em 03/11/2026)
- Manual das APIs de Consultas do PNCP, versão 1.0 (conferido em 03/11/2026)
Conteúdo informativo; não substitui orientação jurídica.