APIs de Origem

Visao Geral do Fluxo

APIs Governamentais (PNCP, Compras.gov)
    |
    v
Cloudflare Worker (pncp-ata360)
    |-- Transforma para ItemFlat
    |-- Insere no ClickHouse (items_flat)
    |-- Armazena metadados no D1 (sync_status, api_keys)
    |-- Armazena JSONs e PDFs no R2
    v
API ATA360 (endpoints publicos)

PNCP (Portal Nacional de Contratacoes Publicas)

Base URL: https://pncp.gov.br/api/ O PNCP e a fonte primaria da ATA360, responsavel por ~50.4M itens na base.

Dados Coletados

Dado	Endpoint PNCP	O que extraimos
ATAs de Registro de Preco	`/v1/orgaos/{cnpj}/compras/{ano}/{seq}/atas`	Metadados da ATA (vigencia, orgao, objeto)
Itens da Compra	`/v1/orgaos/{cnpj}/compras/{ano}/{seq}/itens`	Descricao, preco estimado, situacao
Resultados da Compra	`/v1/orgaos/{cnpj}/compras/{ano}/{seq}/itens/{seq}/resultados`	Vencedor, preco final, CNPJ fornecedor
Contratos	`/v1/contratos/{cnpj}/{ano}/{seq}`	Metadados do contrato, vigencia, fornecedor
Termos Aditivos	`/v1/contratos/{cnpj}/{ano}/{seq}/termos`	Aditivos, apostilamentos
Arquivos/Documentos	`.../arquivos`	PDFs do edital, contrato, ATA
Contratacoes	`/v1/contratacoes/publicacao`	Dispensas, inexigibilidades
VwFtPNCPCompraItem	Enriquecimento	NCM, unidade_medida, situacao_item, criterio_julgamento

Limitacoes do PNCP

A API do PNCP nao retorna o campo catalogoCodigoItem (codigo CATMAT/CATSER) na maioria das respostas. Por isso, 99.95% dos itens PNCP tem codigo_item = 0 no ClickHouse. A busca textual e usada como fallback para esses itens.

Compras.gov.br (API Compras)

Base URL: https://dadosabertos.compras.gov.br/modulo-pesquisa-preco/ O Compras.gov fornece dados estruturados com codigos CATMAT e informacoes mais detalhadas dos itens.

Dados Coletados

Dado	Endpoint	O que extraimos
ARPItem (Itens de ATA)	`/v1/informacao-arp-item`	Items com codigo CATMAT, quantidade, fornecedor, UASG
ContratosItem	`/v1/informacao-contratos-item`	Items de contratos com precos realizados
Pesquisa de Precos	`/v1/pesquisa-preco-material-servico`	Precos oficiais (consultado on-demand, nao ingerido)
CATMAT Grupos	`/v1/catmat-grupo`	79 grupos de materiais
CATMAT Classes	`/v1/catmat-classe`	~700 classes de materiais
CATMAT PDM	`/v1/catmat-pdm`	~20K Padroes Descritivos de Material
CATMAT Itens	`/v1/catmat-item`	337K+ itens do catalogo de materiais (inclui NCM)
CATMAT Unidades de Fornecimento	`/modulo-material/6_consultarMaterialUnidadeFornecimento`	Unidades permitidas por PDM (ex: UN, KG, PCT)
CATMAT Caracteristicas	`/modulo-material/7_consultarMaterialCaracteristicas`	Caracteristicas detalhadas por item (chave/valor)
CATSER Grupos	`/v1/catser-grupo`	147 grupos de servicos
CATSER Classes	`/v1/catser-classe`	~900 classes de servicos
CATSER Itens	`/v1/catser-item`	3K+ itens do catalogo de servicos
UASGs	`/v1/uasg`	21K+ unidades administrativas

Vantagens do Compras.gov

Retorna codigo_item (CATMAT/CATSER) em todos os registros
Informacoes de classificacao do fornecedor (ME/EPP)
Quantidades homologadas e empenhadas
Situacao SICAF do fornecedor
Modulo Pesquisa de Precos com dados oficiais
Unidades de fornecimento padrao por PDM (multiplas por produto)
Caracteristicas detalhadas por item CATMAT (material, tipo, bitola, etc.)
NCM (Nomenclatura Comum do Mercosul) por item

Dados On-Demand vs Ingeridos

Nem todos os dados do Compras.gov sao ingeridos para o ClickHouse. Alguns sao consultados sob demanda:

Ingeridos (D1): Grupos, Classes, PDMs, Itens, Unidades de Fornecimento, UASGs, Orgaos
Ingeridos (ClickHouse): ARPItem, ContratosItem
On-demand (proxy): Pesquisa de Precos oficial, Caracteristicas por item

Mapeamento Coluna → API

A tabela abaixo mostra de qual API cada campo da items_flat se origina:

Campo	PNCP	Compras.gov	Obs
source, source_system	-	-	Gerado internamente
id_item	-	-	Hash gerado
codigo_item	Raro (0.05%)	Sempre	PNCP quase nunca retorna
descricao_item	Sim	Sim	Ambos
valor_unitario	Sim	Sim	Ambos
valor_total	Sim	Sim	Ambos
quantidade	Sim	Sim	Ambos
cnpj_fornecedor	Sim	Sim	Ambos
nome_fornecedor	Sim	Sim	Ambos
classificacao_fornecedor	-	Sim	Somente Compras.gov
porte_fornecedor	Sim	Sim	Ambos
situacao_sicaf	-	Sim	Somente Compras.gov ARPItem
codigo_uasg	Extraido	Sim	PNCP: extraido do controle
uf, municipio	-	-	JOIN com tabela UASG (D1)
nome_orgao	Sim	Sim	Ambos
cnpj_orgao	Extraido	-	Extraido do numero_controle_pncp
quantidade_homologada_*	-	Sim	Somente Compras.gov ARPItem
quantidade_empenhada	-	Sim	Somente Compras.gov ARPItem
maximo_adesao	-	Sim	Somente Compras.gov
ncm_codigo, ncm_descricao	Enriquecimento	-	PNCP VwFtPNCPCompraItem
unidade_medida	Enriquecimento	-	PNCP VwFtPNCPCompraItem
situacao_item	Enriquecimento	-	PNCP VwFtPNCPCompraItem
criterio_julgamento	Enriquecimento	-	PNCP VwFtPNCPCompraItem
tipo_beneficio	Enriquecimento	-	PNCP VwFtPNCPCompraItem
valor_estimado	Enriquecimento	-	PNCP VwFtPNCPCompraItem
data_assinatura	Sim	Sim	Ambos
data_atualizacao	Sim	Sim	Ambos

​Visao Geral do Fluxo

​PNCP (Portal Nacional de Contratacoes Publicas)

​Dados Coletados

​Limitacoes do PNCP

​Compras.gov.br (API Compras)

​Dados Coletados

​Vantagens do Compras.gov

​Dados On-Demand vs Ingeridos

​Mapeamento Coluna → API

Visao Geral do Fluxo

PNCP (Portal Nacional de Contratacoes Publicas)

Dados Coletados

Limitacoes do PNCP

Compras.gov.br (API Compras)

Dados Coletados

Vantagens do Compras.gov

Dados On-Demand vs Ingeridos

Mapeamento Coluna → API