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

# Introdução

> Documentação completa da API para gerenciamento de esquemas, geração de tokens de upload e consultas no DataSnap

## Bem-vindo à API DataSnap

A API DataSnap fornece endpoints completos para gerenciar seus esquemas de dados, gerar tokens de upload e executar consultas. Esta documentação cobre todos os endpoints disponíveis com exemplos detalhados e formatos de resposta.

## Como funciona o DataSnap

O DataSnap segue um fluxo simples e eficiente em duas etapas principais:

<Steps>
  <Step title="Upload de Arquivos">
    ⚠️ <strong>Sistema antigo descontinuado</strong><br />
    O endpoint `POST /api/v1/schemas/{slug}/files` não funciona mais.<br /><br />
    <strong>Novo sistema:</strong> Gere um token de upload e faça upload direto para a nuvem.

    **Endpoints:**

    * `POST /api/v1/schemas/logs-de-acoes/generate-upload-token` (gerar token)
    * `PUT {upload_url}/nome-arquivo.jsonl` (fazer upload)
  </Step>

  <Step title="Consultas">
    Realize consultas SQL avançadas nos dados com suporte a filtros, agrupamentos e paginação.
    Você pode realizar consultas via API ou no DataSnap Web.

    **Endpoint:** `POST /api/v1/schemas/{slug}/query`
  </Step>
</Steps>

## Autenticação

Todos os endpoints da API requerem autenticação usando tokens Bearer. Inclua seu token no cabeçalho Authorization de cada requisição:

```bash theme={null}
Authorization: Bearer SEU_TOKEN_AQUI
```

A API utiliza tokens JWT para acesso seguro aos seus dados de esquema, geração de tokens de upload e execução de consultas.

<Warning>
  Mantenha seu token seguro e nunca o exponha em código público. Use variáveis de ambiente para armazenar suas credenciais.
</Warning>

## URLs Base

```
Produção: https://api.datasnap.cloud
```

## Endpoints Principais

### Upload de Arquivos (Novo Sistema)

<CardGroup cols={2}>
  <Card title="Geração de Token de Upload" icon="key" href="/api-reference/endpoint/generate-upload-token-endpoint">
    ✅ <strong>Sistema atual</strong> - Gere URLs pré-assinadas para upload direto de arquivos.
  </Card>

  <Card title="Gerar Token de Upload (Alternativo)" icon="key" href="/api-reference/endpoint/schema-upload-token-endpoint">
    ✅ <strong>Sistema alternativo</strong> - Mesma funcionalidade com documentação alternativa.
  </Card>

  <Card title="Upload de Arquivos (Antigo)" icon="upload" href="/api-reference/endpoint/schema-upload-files-endpoint">
    ❌ <strong>Descontinuado</strong> - Sistema antigo não funcional.
  </Card>
</CardGroup>

### Gerenciamento e Consultas

<CardGroup cols={2}>
  <Card title="Listar Arquivos" icon="list" href="/api-reference/endpoint/schema-files-endpoint">
    Visualize e gerencie arquivos enviados com filtros avançados e paginação.
  </Card>

  <Card title="Executar Consultas" icon="magnifying-glass" href="/api-reference/endpoint/schema-query-endpoint">
    Realize consultas SQL complexas com filtros, agrupamentos e funções de agregação.
  </Card>
</CardGroup>

## Formato dos Dados

### JSONL (JSON Lines)

O DataSnap trabalha exclusivamente com arquivos no formato JSONL, onde cada linha contém um objeto JSON válido:

```jsonl theme={null}
{"id": 1, "nome": "João Silva", "idade": 30, "cidade": "São Paulo"}
{"id": 2, "nome": "Maria Santos", "idade": 25, "cidade": "Rio de Janeiro"}
{"id": 3, "nome": "Carlos Oliveira", "idade": 35, "cidade": "Belo Horizonte"}
```

### Validação Automática

Todos os arquivos são validados automaticamente durante o upload:

* ✅ Cada linha deve ser um JSON válido
* ✅ Estrutura consistente entre linhas
* ✅ Tamanho máximo de 10MB por arquivo (recomendado)

## Códigos de Resposta

| Código | Significado         | Descrição                                    |
| ------ | ------------------- | -------------------------------------------- |
| `200`  | Sucesso             | Requisição processada com sucesso            |
| `400`  | Requisição Inválida | Parâmetros ou dados inválidos                |
| `401`  | Não Autorizado      | Token inválido ou ausente                    |
| `404`  | Não Encontrado      | Esquema ou recurso não encontrado            |
| `422`  | Erro de Validação   | Dados não atendem aos critérios de validação |
| `500`  | Erro do Servidor    | Erro interno do sistema                      |

<Info>
  **Nota sobre Upload:** O novo sistema de upload funciona em duas etapas:

  1. `POST /api/v1/schemas/{slug}/generate-upload-token` - Gera URL de upload
  2. `PUT {upload_url}/nome-arquivo.jsonl` - Faz upload direto para nuvem

  Não há mais processamento intermediário - os dados ficam disponíveis para consulta imediatamente após o upload.
</Info>

## Exemplo de Fluxo Completo

Veja um exemplo prático de como usar toda a API:

<CodeGroup>
  ```bash cURL theme={null}
  # 1. Gerar token de upload
  curl -X POST \
    "https://api.datasnap.cloud/api/v1/schemas/seu-schema/generate-upload-token" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"minutes": 15}'

  # 2. Upload direto para nuvem (usando URL retornada)
  curl -X PUT \
    "{pre_signed_url}/dados.jsonl" \
    -H "Content-Type: application/octet-stream" \
    --data-binary "@dados.jsonl"

  # 3. Executar consulta
  curl -X POST \
    "https://api.datasnap.cloud/api/v1/schemas/logs-de-acoes/query" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "select": ["cidade", "sum(valor) as total_vendas"],
      "group_by": ["cidade"],
      "order_by": [{"field": "total_vendas", "direction": "desc"}],
      "limit": 10
    }'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = "seu_token_aqui"
  BASE_URL = "https://api.datasnap.cloud"
  HEADERS = {"Authorization": f"Bearer {TOKEN}"}

  # 1. Gerar token de upload
  token_response = requests.post(
      f"{BASE_URL}/api/v1/schemas/seu-schema/generate-upload-token",
      headers=HEADERS,
      json={"minutes": 15}
  )
  token_data = token_response.json()
  upload_url = token_data["upload_url"]

  # 2. Upload direto para nuvem
  with open("dados.jsonl", "rb") as arquivo:
      upload_response = requests.put(
          f"{upload_url}/dados.jsonl",
          headers={"Content-Type": "application/octet-stream"},
          data=arquivo
      )

  # 3. Consultar
  query_data = {
      "select": ["cidade", "sum(valor) as total_vendas"],
      "group_by": ["cidade"],
      "order_by": [{"field": "total_vendas", "direction": "desc"}],
      "limit": 10
  }
  query_response = requests.post(
      f"{BASE_URL}/api/v1/schemas/seu-schema/query",
      headers=HEADERS,
      json=query_data
  )

  print(query_response.json())
  ```
</CodeGroup>

## Limites e Quotas

A API DataSnap implementa limites para garantir estabilidade e performance para todos os usuários.

### Resumo dos Limites

* **Upload**: 10MB máximo por arquivo (recomendado para melhor experiência)
* **Listagem**: 100 requisições por minuto
* **Consultas**: 50 requisições por minuto
* **Geração de tokens**: 2 requisições por minuto

<Info>
  Para informações detalhadas sobre todos os limites, estratégias de otimização e exemplos de código, consulte nossa [documentação completa de Limites e Quotas](/limites-e-quotas).
</Info>

### Boas Práticas

<Tip>
  * **Gere tokens apenas quando necessário** - evite expiração desnecessária
  * **Monitore expiração das URLs** - tokens válidos por tempo limitado
  * **Use nomes únicos para arquivos** - evite conflitos no upload
  * **Valide dados localmente** - formato JSONL obrigatório
  * **Mantenha arquivos abaixo de 10MB** - para melhor performance
  * **Implemente retry** - para uploads que podem falhar temporariamente
  * **Use paginação** - para consultas com muitos resultados
</Tip>

## Suporte

Precisa de ajuda? Nossa equipe está pronta para auxiliar:

<CardGroup cols={2}>
  <Card title="Guia de Desenvolvimento" icon="code" href="/development">
    Boas práticas para integrar o DataSnap em suas aplicações.
  </Card>

  <Card title="Suporte Técnico" icon="headset" href="mailto:support@datasnap.cloud">
    Entre em contato para suporte técnico especializado.
  </Card>
</CardGroup>