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

# CATMAT - Catalogo de Materiais

> Como consultar o catalogo de materiais do governo

O CATMAT (Catalogo de Materiais) e o sistema de classificacao de materiais do governo federal brasileiro. Ele organiza mais de 337.000 itens em uma hierarquia de 4 niveis.

## Hierarquia

```
Grupo (79)
  └── Classe (~700)
        └── PDM (~20.000)
              └── Item (337.000+)
```

| Nivel  | Quantidade | Exemplo                              |
| ------ | ---------- | ------------------------------------ |
| Grupo  | 79         | "EQUIPAMENTOS DE ESCRITORIO"         |
| Classe | \~700      | "MAQUINAS DE CALCULAR"               |
| PDM    | \~20.000   | "CALCULADORA CIENTIFICA"             |
| Item   | 337.000+   | "CALCULADORA CIENTIFICA 240 FUNCOES" |

## Endpoints

### Listar Grupos

```bash theme={null}
GET /api/catmat/grupos
```

Retorna todos os grupos de materiais (79 total).

<ParamField query="page" type="number" default="1">
  Pagina atual
</ParamField>

<ParamField query="limit" type="number" default="20">
  Itens por pagina (max 100)
</ParamField>

**Exemplo:**

```bash theme={null}
curl "https://api.ata360.com.br/api/catmat/grupos?limit=5" \
  -H "Authorization: Bearer $API_KEY"
```

### Listar Classes

```bash theme={null}
GET /api/catmat/classes
```

Retorna classes de materiais. Filtre por grupo.

<ParamField query="grupo" type="number">
  Codigo do grupo para filtrar
</ParamField>

**Exemplo:**

```bash theme={null}
# Classes do grupo 75 (Equipamentos de Escritorio)
curl "https://api.ata360.com.br/api/catmat/classes?grupo=75" \
  -H "Authorization: Bearer $API_KEY"
```

### Listar PDMs

```bash theme={null}
GET /api/catmat/pdm
```

Retorna PDMs (Padrao Descritivo de Material). Filtre por classe.

<ParamField query="classe" type="number">
  Codigo da classe para filtrar
</ParamField>

### Buscar Itens

```bash theme={null}
GET /api/catmat/itens
```

Busca itens de materiais. Use `q` para busca por texto.

<ParamField query="pdm" type="number">
  Codigo do PDM para filtrar
</ParamField>

<ParamField query="q" type="string">
  Busca por descricao (min 3 caracteres)
</ParamField>

**Exemplo:**

```bash theme={null}
# Buscar itens com "papel a4"
curl "https://api.ata360.com.br/api/catmat/itens?q=papel%20a4&limit=5" \
  -H "Authorization: Bearer $API_KEY"
```

## Resposta de Item

```json theme={null}
{
  "data": [
    {
      "codigo": 150233,
      "codigoPdm": 1234,
      "descricao": "PAPEL A4 75G/M2 BRANCO",
      "unidadeFornecimento": "RESMA",
      "ncmCodigo": "4802.56.99",
      "ncmDescricao": "OUTROS PAPEIS E CARTOES",
      "sustentavel": 0,
      "status": 1
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 1250,
    "totalPages": 250
  }
}
```

## Detalhes de um Item CATMAT

### Dados do Item + PDM + Unidades

```bash theme={null}
GET /api/catmat/item/{codigoItem}/details
```

Retorna informacoes completas do item, incluindo o PDM pai e as unidades de fornecimento permitidas.

```bash theme={null}
curl "https://api.ata360.com.br/api/catmat/item/214367/details" \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "item": {
    "codigo": 214367,
    "descricao": "PREGO ARDOX COM CABECA 19 X 36",
    "unidadeFornecimento": "UNIDADE",
    "ncmCodigo": "7317.00.90",
    "ncmDescricao": "OUTROS ARTIGOS SEMELHANTES DE FERRO FUNDIDO",
    "sustentavel": false
  },
  "pdm": {
    "codigo": 632,
    "descricao": "PREGO ARDOX COM CABECA"
  },
  "unidades": [
    { "sigla": "UN", "nome": "UNIDADE", "siglaUnidadeMedida": null, "capacidade": 0 },
    { "sigla": "KG", "nome": "QUILOGRAMA", "siglaUnidadeMedida": "kg", "capacidade": 0 },
    { "sigla": "PCT", "nome": "PACOTE", "siglaUnidadeMedida": null, "capacidade": 0 }
  ]
}
```

<Info>
  Um mesmo PDM pode ter multiplas unidades de fornecimento. Por exemplo, pregos podem ser comprados por unidade (UN), peso (KG) ou pacote (PCT). Essas unidades sao sincronizadas semanalmente da API Compras.gov.
</Info>

### Caracteristicas do Item

```bash theme={null}
GET /api/catmat/item/{codigoItem}/caracteristicas
```

Retorna as caracteristicas detalhadas de um item CATMAT (consultado on-demand na API Compras.gov).

```bash theme={null}
curl "https://api.ata360.com.br/api/catmat/item/214367/caracteristicas" \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "codigoItem": 214367,
  "caracteristicas": [
    { "chave": "MATERIAL", "valor": "ARAME DE ACO", "codigo": "C001", "unidadeMedida": null },
    { "chave": "TIPO CABECA", "valor": "ARDOX", "codigo": "C002", "unidadeMedida": null },
    { "chave": "BITOLA", "valor": "19 X 36", "codigo": "C003", "unidadeMedida": "mm" }
  ]
}
```

<Warning>
  As caracteristicas sao consultadas sob demanda na API Compras.gov (nao sao armazenadas localmente). A primeira chamada pode levar 1-2 segundos.
</Warning>

### Unidades de Fornecimento por PDM

```bash theme={null}
GET /api/catmat/pdm/{codigoPdm}/details
```

Consulta direta por codigo PDM (sem precisar do item).

```bash theme={null}
curl "https://api.ata360.com.br/api/catmat/pdm/632/details" \
  -H "Authorization: Bearer $API_KEY"
```

## Casos de uso

<AccordionGroup>
  <Accordion title="Encontrar codigo de um material">
    Use a busca por texto para encontrar o codigo do item:

    ```bash theme={null}
    curl ".../api/catmat/itens?q=notebook%20dell"
    ```
  </Accordion>

  <Accordion title="Listar materiais de uma categoria">
    Navegue pela hierarquia: grupo → classe → pdm → itens

    ```bash theme={null}
    # 1. Liste grupos
    curl ".../api/catmat/grupos"

    # 2. Liste classes do grupo escolhido
    curl ".../api/catmat/classes?grupo=75"

    # 3. Liste itens da classe
    curl ".../api/catmat/itens?classe=7510"
    ```
  </Accordion>
</AccordionGroup>