POST
/
api
/
v1
/
schemas
/
{slug}
/
files
curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/files" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -F "files=@dados.jsonl"

{
  "uploaded": [
    {
      "id": 456,
      "file_name": "dados.jsonl",
      "size_bytes": 1048576,
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "schema_slug": "meu-schema",
      "schema_version": "1.0.0",
      "validation": "ok",
      "errors": [],
      "upload_status": "pending"
    },
    {
      "file_name": "invalido.jsonl",
      "size_bytes": 2048,
      "md5": "098f6bcd4621d373cade4e832627b4f6",
      "schema_slug": "meu-schema",
      "schema_version": "1.0.0",
      "validation": "error",
      "errors": [
        "A linha 5 do arquivo não é um JSON válido. O arquivo deve estar no formato JSONL (um objeto JSON por linha)."
      ]
    },
    {
      "id": 123,
      "file_name": "duplicado.jsonl",
      "size_bytes": 5120,
      "md5": "5d41402abc4b2a76b9719d911017c592",
      "schema_slug": "meu-schema",
      "schema_version": "1.0.0",
      "validation": "ok",
      "errors": ["Arquivo já foi enviado anteriormente."],
      "duplicate": true,
      "upload_status": "completed"
    }
  ],
  "success": true
}

​
Autenticação

Este endpoint requer autenticação. Inclua seu token Bearer no cabeçalho Authorization.
Authorization: Bearer SEU_TOKEN_AQUI

​
Parâmetros de Caminho

​
slug
string
required
O slug do schema

​
Corpo da Requisição

​
files
array
required
Array de arquivos JSONL para upload. Cada arquivo deve estar no formato JSONL válido (um objeto JSON por linha) e ter no máximo 100MB de tamanho.

​
Requisitos de Formato de Arquivo

Os arquivos devem estar no formato JSONL (JSON Lines) onde cada linha contém um objeto JSON válido.

​
Exemplo JSONL Válido

{"nome": "João Silva", "idade": 30, "cidade": "São Paulo"}
{"nome": "Maria Santos", "idade": 25, "cidade": "Rio de Janeiro"}
{"nome": "Carlos Oliveira", "idade": 35, "cidade": "Belo Horizonte"}

​
Exemplos Inválidos

// Inválido - JSON incorreto
{nome: "João", idade: 30}

// Inválido - múltiplos objetos em uma linha
{"nome": "João"} {"idade": 30}

// Inválido - formato array em vez de linha por linha
[{"nome": "João"}, {"nome": "Maria"}]

​
Resposta

​
uploaded
array
Array de objetos resultado do upload, um para cada arquivo processado
​
success
boolean
Sempre true para requisições bem-sucedidas (mesmo se alguns arquivos tiverem erros de validação)
curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/files" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -F "files=@dados.jsonl"

{
  "uploaded": [
    {
      "id": 456,
      "file_name": "dados.jsonl",
      "size_bytes": 1048576,
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "schema_slug": "meu-schema",
      "schema_version": "1.0.0",
      "validation": "ok",
      "errors": [],
      "upload_status": "pending"
    },
    {
      "file_name": "invalido.jsonl",
      "size_bytes": 2048,
      "md5": "098f6bcd4621d373cade4e832627b4f6",
      "schema_slug": "meu-schema",
      "schema_version": "1.0.0",
      "validation": "error",
      "errors": [
        "A linha 5 do arquivo não é um JSON válido. O arquivo deve estar no formato JSONL (um objeto JSON por linha)."
      ]
    },
    {
      "id": 123,
      "file_name": "duplicado.jsonl",
      "size_bytes": 5120,
      "md5": "5d41402abc4b2a76b9719d911017c592",
      "schema_slug": "meu-schema",
      "schema_version": "1.0.0",
      "validation": "ok",
      "errors": ["Arquivo já foi enviado anteriormente."],
      "duplicate": true,
      "upload_status": "completed"
    }
  ],
  "success": true
}

​
Códigos de Erro

​
200
Success
Arquivos processados com sucesso (pode incluir erros de validação para arquivos individuais)
​
401
Error
Não autorizado - Token de autenticação inválido ou ausente
​
404
Error
Schema não encontrado
​
422
Error
Erros de validação - Arquivos ausentes, formato de arquivo inválido ou arquivo muito grande

​
Processo de Upload

1

Validação de Arquivo

Cada arquivo enviado é validado para o formato JSONL adequado. As primeiras 100 linhas são verificadas para garantir que cada linha contenha JSON válido.
2

Detecção de Duplicatas

Os arquivos são verificados contra uploads existentes usando comparação de hash MD5 para prevenir uploads duplicados.
3

Registro no Banco de Dados

Arquivos válidos são registrados no banco de dados com metadados incluindo tamanho, versão e status de validação.
4

Upload Assíncrono

Os arquivos são enfileirados para upload para o Oracle Cloud Storage em segundo plano.
5

Fila de Processamento

Arquivos enviados com sucesso entram na fila de processamento e podem ser processados usando o endpoint process-files.

​
Estados do Upload de Arquivos

​
Status de Upload

  • pending: Arquivo está na fila para upload para armazenamento
  • completed: Arquivo enviado com sucesso para armazenamento
  • failed: Falha no upload para armazenamento

​
Status de Validação

  • ok: Arquivo passou na validação JSONL
  • error: Arquivo tem erros de formato JSON

​
Status de Processamento

Arquivos começam com status de processamento pending e podem ser processados usando o endpoint /api/v1/schemas/{slug}/process-files.

​
Melhores Práticas

Sempre valide seus arquivos JSONL localmente antes de fazer upload para evitar erros de validação e uploads falhados.
Faça upload de arquivos em lotes de tamanho razoável. Embora não haja limite rígido no número de arquivos por requisição, lotes muito grandes podem dar timeout.
Arquivos duplicados (mesmo hash MD5) serão rejeitados. Certifique-se de que seus arquivos contenham dados únicos ou modifique o conteúdo se precisar fazer re-upload.
Arquivos são enviados assincronamente para armazenamento. Monitore o upload_status em chamadas subsequentes da API para acompanhar o progresso do upload.

​
Erros Comuns de Validação

​
Formato JSON Inválido

A linha 5 do arquivo não é um JSON válido. O arquivo deve estar no formato JSONL (um objeto JSON por linha).

​
Limite de Tamanho de Arquivo

O tamanho máximo permitido para cada arquivo é 100MB.

​
Nenhum Arquivo Fornecido

É necessário enviar pelo menos um arquivo.

​
Arquivo Duplicado

Arquivo já foi enviado anteriormente.

​
Monitoramento de Uploads

Após fazer upload, você pode monitorar o status dos seus arquivos: 
# Listar arquivos para verificar status de upload
curl -X GET \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/files?upload_status=pending" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

​
Próximos Passos

  1. Monitorar Status de Upload: Verificar se os arquivos foram enviados com sucesso para armazenamento
  2. Processar Arquivos: Usar o endpoint process-files para iniciar processamento DataFlow
  3. Consultar Dados: Uma vez processados, consulte seus dados usando o endpoint query

​
Endpoints Relacionados