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 |
