​
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
├── process-files  # Processamento de dados
└── query          # Consultas e análises

​
Endpoints principais

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 processamento

Processamento

POST /api/v1/schemas/{slug}/process-filesInicie o processamento de arquivos pendentes

Consultas

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

​
Padrões de navegação

​
Fluxo típico de uso

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

1. Upload

Envie seus arquivos JSONL para o schema desejado usando POST /files.
2

2. Monitoramento

Verifique o status dos arquivos com GET /files e filtros de status.
3

3. Processamento

Inicie o processamento com POST /process-files quando necessário.
4

4. Consultas

Execute análises com POST /query após o processamento.

​
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ído, aguardando processamentoProcessar arquivos
processingEm processamentoAguardar conclusão
completedProcessado com sucessoRealizar consultas
failedFalhou no processamentoVerificar 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
  • 429 Too Many Requests: Limite de taxa excedido

​
Boas práticas de navegação

​
Performance

​
Monitoramento

Implemente monitoramento para navegação eficiente: 
def monitorar_processamento(schema_slug):
    while True:
        response = requests.get(
            f"/api/v1/schemas/{schema_slug}/files",
            params={"processing_status": "pending"}
        )
        
        if response.json()["meta"]["total"] == 0:
            print("✅ Todos os arquivos processados!")
            break
            
        print(f"⏳ {response.json()['meta']['total']} arquivos pendentes")
        time.sleep(30)

​
Próximos passos

Guia prático

Siga nosso guia passo a passo

Referência completa

Explore todos os endpoints disponíveis