API PNCP: como integrar o sistema de compras da prefeitura

A API PNCP é o caminho técnico pelo qual o sistema de compras da prefeitura envia ao Portal Nacional de Contratações Públicas o plano de contratações, os editais, as atas, os contratos e os empenhos, sem que um servidor precise baixar arquivos e subi-los um a um na interface do portal. Para o gestor, a pergunta raramente é como funciona cada serviço. A pergunta é outra: quem responde quando uma ata não aparece no portal ou quando um contrato é divulgado depois do prazo do art. 94 da Lei 14.133/2021?

A resposta passa por três decisões que ficam na mesa do secretário de Administração e do gestor de TI. A primeira é publicar manualmente ou integrar. A segunda é integrar por conta própria ou contratar uma plataforma credenciada. A terceira é definir quem acompanha a versão vigente do manual de integração do PNCP, que muda várias vezes por ano. A versão 2.6, de 31 de agosto de 2026, é a mais recente e já corrigiu a obrigatoriedade de campos que antes estavam em outro estado.

O risco de errar essa conta não é abstrato. Contrato assinado e não divulgado no prazo não produz plenos efeitos, e a divergência entre o que o processo aprovou e o que o portal mostra é justamente o tipo de apontamento que os tribunais de contas encontram. O ponto de partida geral está no guia completo sobre o PNCP; aqui o foco é a operação: autenticação, serviços cobertos, prazos, falhas comuns e a divisão de responsabilidade com o fornecedor do sistema.

O que a API do PNCP faz e o que ela não faz

O PNCP tem duas camadas de acesso. O portal de consultas é público: qualquer pessoa pesquisa contratações, atas e contratos sem login. Já as APIs de manutenção, que inserem, retificam ou excluem dados, exigem autenticação e autorização. É nessa segunda camada que a integração acontece, e é dela que o manual oficial trata.

A API do PNCP não decide o que deve ser publicado, não valida o mérito da contratação e não corrige um processo mal instruído. Ela recebe os dados que o sistema de origem envia, devolve um número de controle e aplica regras de conformidade entre campos, como a combinação entre modalidade, instrumento convocatório e amparo legal. Se o processo interno chega incompleto, a API apenas transporta a falha para o portal.

Há dois ambientes. O de treinamento, também chamado de homologação externa, serve para testar a integração sem efeito jurídico. O de produção é onde o dado vira publicidade oficial. O manual traz o endereço de cada um e a documentação técnica dos serviços no formato Swagger, que é o material de trabalho da equipe de desenvolvimento.

Quem pode enviar dados pela API: a plataforma, não a prefeitura isolada

O manual é claro quanto ao desenho: quem se integra é uma plataforma digital que fornece os dados em nome dos órgãos e entidades. Essa plataforma precisa ser credenciada junto ao Ministério da Gestão e da Inovação em Serviços Públicos, que fornece login e senha. O manual distingue a plataforma pública, operada por órgãos da administração, da plataforma privada, operada por empresas que prestam serviço à administração.

O efeito prático é relevante para o município. A responsabilidade jurídica pelos dados enviados recai sobre a plataforma que representa o órgão, o que inclui a guarda das credenciais e a precisão das informações. Por isso, a pergunta ao fornecedor do sistema de compras não é se ele “tem integração”, e sim se está credenciado, em qual versão do manual opera e quem corrige quando o portal rejeita um envio.

Autenticação e token de acesso

A plataforma se autentica com login e senha e recebe um JSON Web Token, o JWT. Segundo o manual, o token vale por uma hora e é devolvido no cabeçalho da resposta de login, no campo Authorization. Todas as chamadas às APIs de manutenção precisam levar esse mesmo cabeçalho.

Um detalhe que costuma passar despercebido: quando o token expira no meio de um lote, o envio falha até nova autenticação. Um sistema bem construído renova o token de forma automática e registra o que foi enviado, o que ficou pendente e o motivo. Um sistema frágil deixa o servidor descobrir a falha semanas depois.

Cadastro de órgãos, unidades compradoras e vínculo com a plataforma

Antes do primeiro envio, a plataforma precisa verificar se o órgão já está cadastrado no PNCP, cadastrar as unidades compradoras e vincular os entes que representa ao seu usuário da API. O portal já traz os CNPJs da administração pública divulgados pela Receita Federal, o que reduz o trabalho inicial. Se o órgão não for encontrado, o cadastro precisa ser feito antes de qualquer envio.

No ambiente de produção, o procedimento de cadastro segue o rito de gestão de órgão e entidade descrito no manual. Para a prefeitura, o ponto de controle é simples: confirmar se o CNPJ e as unidades compradoras estão corretos, porque um dado de cadastro errado contamina todas as publicações seguintes.

Quais serviços a integração cobre no manual v2.6

O manual organiza os serviços por objeto da contratação. A integração completa cobre mais do que o edital, e é aí que muitas prefeituras descobrem lacunas depois de meses de operação.

• Plano de contratação: envio do Plano de Contratações Anual e de seus itens. Quem quiser estruturar o plano antes da publicação encontra o passo a passo no conteúdo sobre plano de contratações anual.
• Intenção de registro de preços: divulgação da demanda pelo órgão gerenciador, coleta da manifestação dos participantes e envio de documentos e itens.
• Contratação: editais, avisos e atos, com itens, resultados e documentos, além da retificação e da consulta do histórico.
• Atas de registro de preço: inclusão e manutenção da ata vinculada à contratação de origem.
• Contratos e empenhos: inclusão do contrato, termos aditivos e empenhos, inclusive os decorrentes de emendas parlamentares.
• Órgão e entidade: gestão do cadastro do ente e de suas unidades.

Cada serviço tem campos obrigatórios, tabelas de domínio e códigos de retorno próprios. As tabelas de domínio definem, por exemplo, modalidade, critério de julgamento, modo de disputa, amparo legal, tipo de contrato e tipo de documento. Se o sistema de compras da prefeitura usa classificações internas que não casam com essas tabelas, a integração precisa de um mapeamento explícito e revisado.

Prazos do art. 94 e o papel da integração

A divulgação no PNCP é condição indispensável para a eficácia do contrato e de seus aditamentos, nos termos do art. 94 da Lei 14.133/2021. O prazo é contado em dias úteis a partir da assinatura, e muda conforme a forma de contratação.

Situação	Prazo de divulgação no PNCP	Contagem
Contrato decorrente de licitação	20 dias úteis	Da data de assinatura
Contratação direta (dispensa ou inexigibilidade)	10 dias úteis	Da data de assinatura

Na rotina, o prazo corre contra o setor de compras desde o dia em que o contrato é assinado. Quando a publicação depende de uma pessoa lembrar, baixar, conferir e subir os documentos, o risco se concentra no fim do prazo. Quando o sistema dispara o envio no marco do processo, por exemplo na assinatura, o prazo deixa de ser tarefa de agenda e passa a ser regra do fluxo.

O mesmo vale para contratações diretas, que concentram os apontamentos de controle. Para entender o que cada hipótese exige antes da divulgação, vale ler o conteúdo sobre dispensa de licitação na Lei 14.133, e o detalhamento do contrato e de seus aditivos está em contratos administrativos na Lei 14.133.

Ata de registro de preços e contrato derivado

O sistema de registro de preços tem uma particularidade técnica. A ata é vinculada à contratação de origem, e o contrato que decorre dela precisa apontar para essa ata. Na versão 2.6, o manual corrigiu a obrigatoriedade do campo que identifica a ata nos serviços de inclusão e retificação de contratos: o campo deve ser informado somente quando o contrato estiver vinculado a uma contratação do tipo SRP, e suprimido nos demais casos.

Para quem opera atas, o erro típico é enviar o contrato sem o vínculo, ou com vínculo indevido, e perder a rastreabilidade entre ata e contratação. O conteúdo sobre ata de registro de preços detalha o rito da ata no município; na integração, o que importa é que o vínculo seja gerado pelo sistema, e não digitado.

O que mudou nas versões recentes do manual

O manual é um documento vivo, com histórico de versões publicado. Quem cuida da integração precisa tratá-lo como parte do calendário de manutenção do sistema. As mudanças mais recentes dão uma boa medida do ritmo.

• Versão 2.4, de 9 de abril de 2026: recepção de empenhos de emendas parlamentares e novas tabelas de domínio para tipo de contrato e tipo de documento.
• Versão 2.5, de 11 de junho de 2026: adaptação ao CNPJ alfanumérico, atribuído a partir de julho de 2026 exclusivamente a novas inscrições, além de campos de localidade do fornecedor e de identificação de cadastro de reserva ou remanescente.
• Versão 2.6, de 31 de agosto de 2026: serviços de intenção de registro de preços detalhados no manual, correção da obrigatoriedade do campo da ata em contratos e obrigatoriedade do percentual de desconto ao inserir o resultado do item.

O CNPJ alfanumérico merece atenção da TI. Os números já existentes não mudam, mas todo sistema que valida CNPJ apenas com dígitos precisa aceitar o novo formato para fornecedores novos. Um campo mal validado vira rejeição de envio, e rejeição que ninguém monitora vira publicação atrasada.

Onde a publicação costuma falhar na prática

O manual deixa claro que a plataforma é responsável por manter os dados enviados e por atualizar os domínios que representam o estado da contratação sempre que houver mudança. Isso inclui retificar e excluir metadados já enviados. Na rotina das prefeituras, as falhas mais comuns têm origem fora da API.

• Processo mal instruído: documentos faltando ou inconsistentes no processo interno chegam incompletos ao portal. O guia sobre ETP, DFD e minuta mostra por que a instrução correta começa antes da publicação.
• Situação desatualizada: a contratação mudou de fase no sistema interno, mas o status no PNCP continua o anterior.
• Retificação manual fora do fluxo: alguém corrige o dado direto no portal e o sistema interno passa a divergir do que foi publicado.
• Versão defasada do manual: a integração segue o layout antigo e passa a falhar em campos que mudaram.
• Token expirado sem monitoramento: o lote para no meio e ninguém é avisado.

Em Lagoa Santa (MG), o processo de compras foi estruturado na Aprova de modo que cada modalidade exige o DFD, o ETP, o termo de referência e o mapa de risco antes de o processo avançar. Quando chega a hora de publicar, a instrução já está completa e rastreável, o que reduz o retrabalho jurídico e o risco de glosa. Esse é o ponto que a API sozinha não resolve: a qualidade do dado enviado nasce no processo.

Integrar ou publicar manualmente: como decidir

A publicação manual pelo portal continua possível e atende volumes baixos. O custo aparece quando o volume cresce, porque cada contratação, ata, contrato e aditivo passa a depender de upload individual e de conferência humana. A integração só compensa se o sistema de origem estiver organizado, e a decisão fica mais objetiva com cinco perguntas.

1. Quantas contratações, atas, contratos e aditivos o município publica por mês?
2. A prefeitura tem equipe de TI para acompanhar cada nova versão do manual, ou depende do fornecedor?
3. O sistema de compras já guarda os dados em campos estruturados, ou ainda trabalha com arquivos soltos?
4. Quem monitora as rejeições e o prazo do art. 94 hoje?
5. O fornecedor assume formalmente a manutenção quando o manual muda?

Se a resposta à segunda pergunta for “não”, a integração própria é, na maioria dos casos, a pior opção. Manter o código alinhado ao manual concorre com a operação diária da prefeitura, e a defasagem tende a aparecer como falha silenciosa. Uma plataforma credenciada, com processo eletrônico de compras que já alimenta o PNCP, transfere essa manutenção para quem tem equipe dedicada a ela.

O que cobrar do fornecedor do sistema

A contratação ou renovação do sistema de compras é o momento de transformar a integração em obrigação contratual. Cinco itens costumam resolver a maior parte do risco.

• Credenciamento junto ao Ministério da Gestão e da Inovação em Serviços Públicos, com os CNPJs do município vinculados.
• Versão do manual de integração em operação e prazo para adequação a novas versões.
• Registro de cada envio, com data, resultado e número de controle devolvido pelo PNCP.
• Alerta de rejeição e de prazo próximo do vencimento, endereçado ao responsável do setor.
• Retificação feita pelo sistema, de modo que o processo interno e o portal nunca divirjam.

Para quem avalia esse tipo de solução, a solução de compras e licitações da Aprova conecta o processo eletrônico ao PNCP, de modo que a homologação já dispara a publicação no formato exigido pela versão vigente.

FAQ sobre a API do PNCP

Todo município precisa integrar via API?

Não. A obrigação legal é divulgar os atos no PNCP, e a lei não obriga o município a desenvolver uma integração própria. A API é o meio técnico que as plataformas credenciadas usam para enviar os dados. O município pode publicar manualmente pelo portal ou usar um sistema integrado, e a escolha depende do volume de publicações e da capacidade de acompanhar as atualizações do manual.

Qual o prazo para publicar o contrato no PNCP?

O art. 94 da Lei 14.133/2021 fixa 20 dias úteis para contratos decorrentes de licitação e 10 dias úteis para contratações diretas, contados da assinatura. A divulgação é condição indispensável para a eficácia do contrato e de seus aditamentos.

O que acontece se a publicação atrasar?

O contrato não produz plenos efeitos enquanto não for divulgado, e a falha tende a gerar apontamento do tribunal de contas, principalmente em contratações diretas, onde a rastreabilidade documental é o ponto mais sensível. Também pode haver responsabilização do agente público quando a falha é caracterizada como descumprimento da lei.

Dá para publicar sem integração?

Dá. O portal permite a publicação direta pela interface, com upload individual de cada documento. O limite é operacional: quanto maior o volume, maior o risco de esquecimento, divergência entre o processo aprovado e o dado divulgado e atraso em relação ao prazo do art. 94.

Conclusão

A integração com o PNCP é, antes de tudo, uma decisão de governança. A API em si é bem documentada e está em evolução constante, com versões do manual a cada poucas semanas em 2026. O que decide se a publicação sai correta e no prazo é o que existe antes e depois dela: um processo de compra instruído em campos estruturados, uma plataforma credenciada que responde pelo envio e uma rotina de monitoramento que aponta rejeições e prazos próximos do vencimento.

Para o secretário de Administração, a recomendação prática é tratar o PNCP como resultado do processo, e não como uma etapa separada. Isso significa exigir do fornecedor a versão do manual em operação, o registro de cada envio e o alerta de prazo do art. 94. Significa também revisar o mapeamento entre as classificações internas e as tabelas de domínio do portal, porque é ali que nascem as rejeições mais difíceis de diagnosticar.

Para o gestor de TI, o ponto é a manutenção. Cada nova versão do manual, como a de 31 de agosto de 2026, pode mudar campos obrigatórios, e a pergunta certa é quem absorve essa mudança e em quanto tempo. Se a resposta depende de uma agenda improvisada, o risco já está contratado.

Quem quiser aprofundar o tema pode consultar o manual oficial de integração e comparar, item a item, o que o sistema em uso entrega. Um diagnóstico honesto desse comparativo costuma mostrar rapidamente se a prefeitura tem uma integração de fato ou apenas uma publicação manual com outro nome.