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

# Navegação na API

> Compreenda a estrutura da API DataSnap e como navegar eficientemente entre os endpoints

## Estrutura da API

A API DataSnap segue uma arquitetura RESTful organizada em torno de schemas de dados, com endpoints claros e intuitivos.

<Info>
  Todos os endpoints seguem o padrão `/api/v1/schemas/{slug}/` para operações específicas de schema.
</Info>

## Hierarquia de recursos

### Schemas

Os schemas são o ponto central da organização dos dados no DataSnap:

```
/api/v1/schemas/{slug}/
├── files          # Gerenciamento de arquivos
└── query          # Consultas e análises
```

### Endpoints principais

<CardGroup cols={2}>
  <Card title="Geração de Token de Upload" icon="key" href="/api-reference/endpoint/generate-upload-token-endpoint">
    `POST /api/v1/schemas/{slug}/generate-upload-token`

    Gere URLs pré-assinadas para upload direto
  </Card>

  <Card title="Gerenciamento de Arquivos" icon="folder" href="/api-reference/endpoint/schema-files-endpoint">
    `GET /api/v1/schemas/{slug}/files`

    Liste e gerencie arquivos enviados
  </Card>

  <Card title="Upload de Arquivos" icon="upload" href="/api-reference/endpoint/schema-upload-files-endpoint">
    `POST /api/v1/schemas/{slug}/files`

    Envie arquivos JSONL para armazenamento
  </Card>

  <Card title="Consultas" icon="magnifying-glass" href="/api-reference/endpoint/schema-query-endpoint">
    `POST /api/v1/schemas/{slug}/query`

    Execute consultas SQL nos dados
  </Card>
</CardGroup>

## Padrões de navegação

### Fluxo típico de uso

Siga esta sequência para uma integração completa:

<Steps>
  <Step title="1. Gerar Token de Upload">
    Gere uma URL pré-assinada usando `POST /generate-upload-token`.
  </Step>

  <Step title="2. Upload de Arquivos">
    Use a URL retornada para fazer upload direto via HTTP PUT.
  </Step>

  <Step title="3. Consultas">
    Execute análises com `POST /query` nos dados armazenados.
  </Step>
</Steps>

## Parâmetros de navegação

### Paginação

Todos os endpoints de listagem suportam paginação:

```bash theme={null}
GET /api/v1/schemas/vendas/files?page=1&per_page=50
```

### Filtros

Use filtros para navegar eficientemente pelos dados:

```bash theme={null}
# Filtrar por status de processamento
GET /api/v1/schemas/vendas/files?processing_status=completed

# Filtrar por data
GET /api/v1/schemas/vendas/files?date_from=2024-01-01&date_to=2024-12-31

# Busca por nome
GET /api/v1/schemas/vendas/files?search=vendas_janeiro
```

### Ordenação

Controle a ordem dos resultados:

```bash theme={null}
# Ordenar por data de criação (mais recentes primeiro)
GET /api/v1/schemas/vendas/files?sort_by=created_at&sort_direction=desc

# Ordenar por tamanho do arquivo
GET /api/v1/schemas/vendas/files?sort_by=size_bytes&sort_direction=asc
```

## Navegação por status

### Status de arquivos

Entenda os diferentes status para navegar adequadamente:

| Status      | Significado              | Próxima ação         |
| ----------- | ------------------------ | -------------------- |
| `pending`   | Upload concluído         | Arquivos disponíveis |
| `completed` | Disponível para consulta | Realizar consultas   |
| `failed`    | Falhou no upload         | Verificar erros      |

### Consultas por status

```python theme={null}
# Verificar arquivos pendentes
response = requests.get(
    f"{base_url}/api/v1/schemas/{schema}/files",
    headers=headers,
    params={"processing_status": "pending"}
)

# Arquivos prontos para consulta
response = requests.get(
    f"{base_url}/api/v1/schemas/{schema}/files",
    headers=headers,
    params={"processing_status": "completed"}
)
```

## Navegação avançada

### Consultas complexas

Estruture consultas para navegação eficiente nos dados:

```json theme={null}
{
  "select": ["categoria", "count(*) as total"],
  "where": [
    {"field": "data_venda", "op": ">=", "value": "2024-01-01"},
    {"field": "categoria", "op": "in", "value": ["eletrônicos", "roupas"]}
  ],
  "group_by": ["categoria"],
  "order_by": [{"field": "total", "direction": "desc"}],
  "limit": 10
}
```

### Paginação com cursor

Para grandes volumes de dados, use paginação com cursor:

```json theme={null}
{
  "select": ["id", "produto", "valor"],
  "order_by": [{"field": "id", "direction": "asc"}],
  "limit": 1000,
  "page_token": "eyJpZCI6MTAwMH0="
}
```

## Códigos de resposta

Entenda os códigos para navegar adequadamente pelos erros:

### Códigos de sucesso

* `200 OK`: Operação realizada com sucesso
* `201 Created`: Recurso criado com sucesso

### Códigos de erro

* `400 Bad Request`: Parâmetros inválidos
* `401 Unauthorized`: Token inválido ou ausente
* `404 Not Found`: Schema ou recurso não encontrado
* `422 Unprocessable Entity`: Dados inválidos

## Boas práticas de navegação

### Performance

<AccordionGroup>
  <Accordion title="Use filtros específicos">
    ```bash theme={null}
    # ✅ Bom - filtro específico
    GET /api/v1/schemas/vendas/files?processing_status=completed&date_from=2024-08-01

    # ❌ Evitar - sem filtros
    GET /api/v1/schemas/vendas/files
    ```
  </Accordion>

  <Accordion title="Limite o número de resultados">
    ```bash theme={null}
    # ✅ Bom - limite adequado
    GET /api/v1/schemas/vendas/files?per_page=50

    # ❌ Evitar - muitos resultados
    GET /api/v1/schemas/vendas/files?per_page=1000
    ```
  </Accordion>
</AccordionGroup>

### Monitoramento

Implemente monitoramento para navegação eficiente:

```python theme={null}
def monitorar_uploads(schema_slug):
    while True:
        response = requests.get(f"/api/v1/schemas/{schema_slug}/files")

        if response.json()["meta"]["total"] > 0:
            print("✅ Arquivos disponíveis para consulta!")
            break

        print("⏳ Aguardando uploads...")
        time.sleep(30)
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia prático" icon="play" href="/quickstart">
    Siga nosso guia passo a passo
  </Card>

  <Card title="Referência completa" icon="book-open" href="/api-reference/introduction">
    Explore todos os endpoints disponíveis
  </Card>
</CardGroup>