> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ata360.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# APIs de Origem

> Mapeamento das APIs governamentais que alimentam a base de dados ATA360

## 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

<Warning>
  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.
</Warning>

## 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

<Info>
  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
</Info>

## 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                              |