Skip to main content

​
Estrutura da API

A API DataSnap segue uma arquitetura RESTful organizada em torno de schemas de dados, com endpoints claros e intuitivos.
Todos os endpoints seguem o padrão /api/v1/schemas/{slug}/ para operações específicas de schema.

​
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

Geração de Token de Upload

POST /api/v1/schemas/{slug}/generate-upload-tokenGere URLs pré-assinadas para upload direto

Gerenciamento de Arquivos

GET /api/v1/schemas/{slug}/filesListe e gerencie arquivos enviados

Upload de Arquivos

POST /api/v1/schemas/{slug}/filesEnvie arquivos JSONL para armazenamento

Consultas

POST /api/v1/schemas/{slug}/queryExecute consultas SQL nos dados

​
Padrões de navegação

​
Fluxo típico de uso

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

1. Gerar Token de Upload

Gere uma URL pré-assinada usando POST /generate-upload-token.
2

2. Upload de Arquivos

Use a URL retornada para fazer upload direto via HTTP PUT.
3

3. Consultas

Execute análises com POST /query nos dados armazenados.

​
Parâmetros de navegação

​
Paginação

Todos os endpoints de listagem suportam paginação: 
GET /api/v1/schemas/vendas/files?page=1&per_page=50

​
Filtros

Use filtros para navegar eficientemente pelos dados: 
# 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: 
# 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

​
Status de arquivos

Entenda os diferentes status para navegar adequadamente:
StatusSignificadoPróxima ação
pendingUpload concluídoArquivos disponíveis
completedDisponível para consultaRealizar consultas
failedFalhou no uploadVerificar erros

​
Consultas por status

# 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"}
)

​
Consultas complexas

Estruture consultas para navegação eficiente nos dados: 
{
  "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: 
{
  "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

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

# ✅ Bom - limite adequado
GET /api/v1/schemas/vendas/files?per_page=50

# ❌ Evitar - muitos resultados
GET /api/v1/schemas/vendas/files?per_page=1000

​
Monitoramento

Implemente monitoramento para navegação eficiente: 
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

Guia prático

Siga nosso guia passo a passo

Referência completa

Explore todos os endpoints disponíveis