POST
/
api
/
v1
/
schemas
/
{slug}
/
process-files
curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/process-files" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "shape_id": 3,
    "executors": 5
  }'

{
  "ids": [1001, 1002],
  "status": "started",
  "schema": "meu-schema",
  "schema_version": "1.2.0",
  "shape": "Standard Processing",
  "executors": 2,
  "files_count": 15,
  "total_size_mb": 245.67
}
Este endpoint é opcional! O sistema DataSnap possui configurações automáticas que permitem o processamento de arquivos sem intervenção manual. Veja a seção “Processamento Automático” abaixo para entender as opções disponíveis.

​
Autenticação

Este endpoint requer autenticação. Inclua seu token Bearer no cabeçalho Authorization.
Authorization: Bearer SEU_TOKEN_AQUI
Este endpoint também requer permissões de uso do DataFlow e irá consumir créditos DataFlow do seu plano.

​
Como Funciona o Processamento

​
Processamento Incremental

Processamento inteligente: Os arquivos enviados são processados somente uma vez. Por exemplo, se você enviar 1GB de arquivos e processar, depois enviar mais 1GB, o sistema processará apenas esse 1GB novo, não os 2GB totais de arquivos.

​
Otimização de Custos

Economia automática: Temos uma configuração para otimizar custos que permite que o sistema exclua automaticamente os arquivos processados com sucesso no término do processamento, liberando espaço de armazenamento e reduzindo custos.

​
Tempo de Processamento

Planejamento importante: O tempo de processamento de cada DataFlow varia, podendo levar de 10 a 30 minutos dependendo do volume de dados e complexidade do processamento.

​
Processamento Automático (Opcional)

O sistema DataSnap oferece três opções de processamento automático que eliminam a necessidade de usar este endpoint manualmente:

​
Processamento Automático ao Enviar

Com esta opção, cada vez que novos arquivos forem enviados para a plataforma, o processamento será iniciado automaticamente. Ideal para fluxos de trabalho em tempo real onde você precisa que os dados estejam disponíveis para análise o mais rápido possível após o upload. Não é necessária nenhuma intervenção manual.

​
Processamento Baseado em Volume

O sistema monitorará o tamanho total dos arquivos pendentes de processamento. Quando o volume acumulado atingir o limite configurado, o processamento será iniciado automaticamente. Esta opção é eficiente para otimizar recursos, pois processa lotes de dados em vez de arquivos individuais, ideal para uploads frequentes de arquivos pequenos.

​
Processamento Programado

Com esta configuração, o sistema processará automaticamente todos os arquivos pendentes x minutos após o upload, dando tempo para acumular quantos arquivos forem necessários até chegar o momento do processamento. Perfeito para estabelecer uma rotina previsível de processamento, como a cada hora ou a cada 30 minutos, independentemente do volume de dados. Ideal para relatórios periódicos ou quando você precisa de atualizações consistentes.
Como configurar: Acesse o painel de controle da DataSnap e configure a opção de processamento automático que melhor se adapta ao seu fluxo de trabalho.

​
Webhooks para Notificações

Para acompanhar o status do processamento automaticamente, você pode configurar webhooks que receberão notificações em tempo real sobre mudanças no status.
Para informações completas sobre configuração, implementação, segurança e exemplos práticos de webhooks, consulte nossa documentação dedicada de Webhooks.

​
Configuração Rápida

  1. Acesse: Webhooks → + Criar Webhook no painel de controle
  2. Informe: URL do webhook
  3. Salve: A configuração

​
Exemplo de Payload

{
  "topic": "schemas.run.status",
  "metadata": {
    "run_id": 24,
    "tenant": "sua_empresa",
    "status": "completed",
    "started_at": "2025-08-12T23:14:28-03:00"
  }
}
A documentação de Webhooks inclui exemplos completos de implementação em múltiplas linguagens, tratamento de erros e melhores práticas de segurança.

​
Parâmetros de Caminho

​
slug
string
required
O slug do schema

​
Corpo da Requisição

O corpo da requisição é opcional. Se o seu plano de tenant permite processamento personalizado, você pode especificar parâmetros personalizados. Caso contrário, o sistema usará configurações padrão.
​
shape_id
integer
ID do shape para o executor - Este parâmetro define qual configuração de hardware será usada pelo executor no processamento DataFlow. Obrigatório se o plano do tenant permite processamento personalizado.
Como funciona: O DataFlow usa uma arquitetura Driver + Executor. Quando você escolhe um shape_id, está definindo o executor. O sistema automaticamente escolherá o driver da mesma arquitetura.
Lembre-se: O sistema sempre precisa de 2 CPUs no mínimo:
  • 1 CPU para o Driver (escolhido automaticamente)
  • 1+ CPUs para o Executor (definido pelo shape_id que você escolher)
Como escolher o shape_id ideal:
  1. Consulte primeiro: Acesse o endpoint Listar Shapes Disponíveis (GET /api/v1/dataflow/shapes)
  2. Analise suas necessidades: Compare o tamanho dos seus arquivos com recommended_file_size_gb
  3. Considere o custo: Verifique final_cost_per_hour para controlar gastos
  4. Escolha a arquitetura: AMD (melhor custo-benefício) ou Intel (performance)
Exemplo prático:
  • Você tem arquivos de 20GB para processar
  • Consulta shapes disponíveis e encontra “AMD Medium” (ID: 7) com recomendação de 25GB
  • Usa "shape_id": 7 na requisição
  • Sistema automaticamente usa “AMD Small” (ID: 6) como driver por ser o default_driver_from_this_architecture: true para AMD
Prefira shapes com default_driver_from_this_architecture: true quando possível - eles foram otimizados para serem drivers eficientes de suas respectivas arquiteturas.
​
executors
integer
Número de executores (trabalhadores) - Define quantas máquinas virtuais trabalharão em paralelo processando seus arquivos. Aceita valores de 1 a 10. Obrigatório se o plano do tenant permite processamento personalizado.
O que são executores: São as máquinas “trabalhadoras” no DataFlow. Enquanto o Driver coordena, os executores fazem o processamento pesado dos dados em paralelo.
Como escolher o número ideal de executores:Para arquivos pequenos (até 5GB):
  • 1-2 executores geralmente são suficientes
  • Mais executores podem desperdiçar recursos
Para arquivos médios (5-20GB):
  • 2-4 executores oferecem bom equilíbrio
  • Aceleram processamento sem gastos excessivos
Para arquivos grandes (20GB+):
  • 4-8 executores maximizam velocidade
  • Ideais para trabalhos urgentes ou datasets volumosos
Para processamentos muito complexos:
  • 8-10 executores (máximo permitido)
  • Use apenas quando velocidade é crítica
Custo vs. Velocidade: Mais executores = processamento mais rápido, mas também:
  • Maior consumo de créditos DataFlow
  • Custo multiplicado pelo número de executores
  • Retorno diminuente após certo ponto
Dica prática: Comece com 2-3 executores para a maioria dos casos. Você pode ajustar em processamentos futuros baseado na performance observada.
Exemplo de configuração completa:
{
  "shape_id": 7,     // AMD Medium para executor
  "executors": 3     // 3 trabalhadores em paralelo
}
Resultado: 1 Driver + 3 Executores = 4 máquinas processando em conjunto

​
Resposta

​
ids
array
Array de IDs de execução criados para os trabalhos de processamento
​
status
string
Status de processamento (sempre “started” para requisições bem-sucedidas)
​
schema
string
Slug do schema que foi processado
​
schema_version
string
Versão do schema que foi processado
​
shape
string
Nome do formato/preset DataFlow usado para processamento
​
executors
integer
Número de executores usados para processamento
​
files_count
integer
Número total de arquivos que foram enfileirados para processamento
​
total_size_mb
number
Tamanho total dos arquivos processados em MB
curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/process-files" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "shape_id": 3,
    "executors": 5
  }'

{
  "ids": [1001, 1002],
  "status": "started",
  "schema": "meu-schema",
  "schema_version": "1.2.0",
  "shape": "Standard Processing",
  "executors": 2,
  "files_count": 15,
  "total_size_mb": 245.67
}

​
Códigos de Erro

​
200
Success
Processamento de arquivos iniciado com sucesso
​
400
Error
Requisição inválida - Erros de validação para parâmetros shape_id ou executors
​
401
Error
Não autorizado - Token de autenticação inválido ou ausente
​
403
Error
Proibido - DataFlow não disponível para o plano do tenant ou desabilitado
​
404
Error
Schema não encontrado
​
422
Error
Entidade não processável - Nenhum arquivo pendente, schema inativo ou outros erros de lógica de negócio
​
500
Error
Erro interno do servidor - Falha ao iniciar o processamento

​
Fluxo de Processamento

1

Descoberta de Arquivos

O sistema identifica todos os arquivos pendentes em todas as versões do schema especificado.
2

Validação do Plano

Verifica se o plano do seu tenant suporta processamento DataFlow personalizado ou usa configurações padrão.
3

Alocação de Recursos

Aloca o número especificado de executores (ou padrão baseado no seu plano).
4

Criação de Trabalho

Cria trabalhos de execução DataFlow para cada versão que possui arquivos pendentes.
5

Início do Processamento

Inicia os trabalhos DataFlow e retorna IDs de execução para rastreamento.

​
Tipos de Plano e Parâmetros

​
Planos Básicos

  • Parâmetros: Nenhum obrigatório (corpo da requisição pode estar vazio)
  • Executores: Fixo em 1
  • Formato: Usa o preset DataFlow padrão do plano
  • Processamento: Apenas processamento padrão

​
Planos Personalizados

  • Parâmetros: shape_id e executors são obrigatórios
  • Executores: 1-10 (configurável pelo usuário)
  • Formato: Escolha entre presets DataFlow disponíveis
  • Processamento: Personalização completa disponível

​
Melhores Práticas

Verifique primeiro se há arquivos pendentes usando o endpoint /api/v1/schemas/{slug}/files?processing_status=pending antes de iniciar o processamento.
Para grandes conjuntos de dados, considere usar mais executores (se seu plano permitir) para acelerar o processamento, mas esteja ciente do aumento no consumo de recursos.
O processamento consome créditos DataFlow baseado no número de arquivos, volume de dados e complexidade do processamento. Monitore seu uso para evitar cobranças inesperadas.

​
Casos de Uso Comuns

​
Processar Todos os Arquivos Pendentes

{
  "shape_id": 1,
  "executors": 1
}

​
Processamento de Alta Performance

{
  "shape_id": 3,
  "executors": 8
}

​
Processamento do Plano Básico

{}

​
Obtendo Formatos Disponíveis

Antes de usar processamento personalizado, você pode recuperar os formatos DataFlow disponíveis: 
curl -X GET \
  "https://api.datasnap.com.br/api/v1/dataflow/shapes" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
Isso retornará os formatos disponíveis com seus IDs, nomes e descrições para ajudá-lo a escolher o shape_id apropriado para suas necessidades de processamento.

​
Solução de Problemas

​
Erro de Nenhum Arquivo Pendente

Se você receber o erro “Não há arquivos pendentes para processar”, verifique:
  • Os arquivos estão enviados e têm processing_status: pending
  • Os arquivos ainda não foram processados com sucesso
  • O schema possui arquivos ativos no sistema

​
Erro DataFlow Não Disponível

Este erro ocorre quando:
  • Seu plano não inclui processamento DataFlow
  • DataFlow está desabilitado para seu tenant
  • Você precisa atualizar seu plano para acessar este recurso

​
Erros de Validação

Para planos de processamento personalizado, certifique-se de que:
  • shape_id existe e está ativo
  • executors está entre 1 e 10
  • Ambos os parâmetros são fornecidos se seu plano os exigir