Skip to main content
POST
Criar transações em lote

Visão geral

Cria múltiplas transações em uma única operação em lote. Este endpoint é otimizado para alto volume. Limites:
  • Um único lote: até 100.000 transações por requisição; corpo da requisição não deve exceder 50 MB.
  • Múltiplos arquivos em uma chamada: use POST /transactions/batch/background-multi com array sources (até 5 arquivos, 100.000 transações cada); limite do corpo 150 MB.
  • Carga por arquivos (multipart): use POST /transactions/batch/upload para enviar arquivos CSV, Excel ou JSON diretamente; máx. 5 arquivos por requisição. O limite por arquivo depende do seu plano.
Comportamento (endpoint síncrono):
  • A API mantém a conexão aberta por até 30 segundos.
  • Se o lote terminar em 30 segundos, retorna 200 com o resumo completo (criadas, ignoradas, regras executadas, tempo, etc.).
  • Se ultrapassar 30 segundos, retorna 202 com um jobId e continua processando em segundo plano. Ao terminar, o cliente é notificado no dashboard (e via socket em tempo real se conectado).
Endpoints em segundo plano (sempre assíncronos):
  • POST /transactions/batch/background — Um único lote; retorna 202 imediatamente e notifica via socket ao terminar.
  • POST /transactions/batch/background-multi — Múltiplos arquivos em uma requisição (máx. 5); retorna 202 e uma notificação quando todos forem processados.
  • POST /transactions/batch/uploadMultipart form-data: envie um ou mais arquivos (CSV, Excel, JSON) no campo file; o servidor faz o parse e executa o mesmo fluxo. Ideal quando você tem arquivos em vez de JSON.
Ideal para: importar histórico, arquivos grandes (CSV, Excel, JSON), processadores de alto volume, migração de dados.

Endpoints

Carga por arquivos (multipart)

Use POST /transactions/batch/upload quando tiver arquivos CSV, Excel ou JSON e quiser que o servidor faça o parse. A requisição deve ser multipart/form-data (FormData), não JSON.
  • Máx. 5 arquivos por requisição.
  • Formatos aceitos: CSV (.csv), Excel (.xlsx, .xls), JSON (.json).
  • Limite de transações por arquivo conforme o plano da organização (ver Limites por plano).
  • Query: validateGap (padrão false). Se você enviar validateGap=true com vários arquivos, a API verifica se não há intervalo de 30 minutos ou mais entre o fim de um arquivo e o início do próximo (por transactedAt). Se houver, retorna 400 com code: "GAP_VALIDATION_REQUIRED" e a lista de intervalos. Por padrão a validação está desativada; use ?validateGap=true para ativá-la.

Campos do form

Exemplo: envio com FormData (JavaScript)

Exemplo: cURL

Limites por plano

O máximo de transações por arquivo (tanto no upload quanto no background-multi) depende do plano da organização: Se a carga batch estiver desabilitada para sua organização, os endpoints retornam 403. Entre em contato com o suporte para habilitar ou alterar o plano.

Modelos (templates)

Para montar arquivos CSV, Excel ou JSON que atendam ao esquema:
  1. Dashboard: Em Monitoramento de transações, abra o modal Carga em lote. Use os botões Baixar CSV, Baixar Excel ou Baixar JSON para obter modelos com os cabeçalhos corretos e uma linha de exemplo. É a forma mais fácil de começar.
  2. Campos obrigatórios por linha: Cada transação deve incluir pelo menos externalId, type, amount e currency. Recomendados: transactedAt, status, originName, destinationName, description. Esquema completo em Criar transação.
  3. CSV/Excel: Os nomes das colunas podem ser camelCase (externalId, transactedAt) ou snake_case (external_id, transacted_at); o servidor normaliza. Data em ISO 8601 (ex. 2025-01-15T10:30:00.000Z).
Não há URL pública para baixar modelos fora do dashboard; use o modal de carga em lote para obter os modelos atualizados.

Autenticação

Corpo (sync e background)

array
required
Array de objetos de transação (mín. 1, máx. 100.000 por requisição). Mesma estrutura de Criar transação. Corpo máx. 50 MB.exchangeRate opcional por linha: somente quando a conversão automática falha; ver Conversão de moeda.
boolean
default:"true"
Se as regras são executadas para todas as transações do lote
boolean
default:"true"
Ignorar transações com externalId duplicado em vez de falhar todo o lote
Override opcional. true: hard-fail. false: soft-link. Se omitido, segue validateExistingEntity. Também ?linkEntityStrict=true|false.
boolean
default:"true"
Padrão do lote true (sem mudança para quem omite o campo): refs não resolvidas → 400. Com false: auto-vincula se encontrar e segue sem vínculo se não.
Se o passo 2 ou 3 tiver sucesso, preenche *EntityId e pode preencher nome/país a partir da entidade, como no create único. Com lado vinculado (inclusive quando você já enviou *EntityId), originTaxId / originExternalId e destinationTaxId / destinationExternalId são sempre sincronizados a partir da entidade antes do insert — mesma denormalização canônica de Criar transação — origem. Cada linha criada também recebe o campo linkedEntityGu1, controlado pelo servidor, dentro de originDetails e destinationDetails. O valor é linked, unresolved ou not_requested. Gu1 ignora e sobrescreve qualquer valor incluído no arquivo.

Corpo (apenas background-multi)

array
required
Array de objetos: { "fileName": "opcional", "transactions": [ ... ] }. Mín. 1, máx. 5 fontes. Cada transactions: máx. 100.000 (ou o limite do seu plano por arquivo). Corpo total máx. 150 MB.

Resposta 200 (concluído em 30 s)

boolean
Se a operação em lote foi concluída com sucesso
number
Número de transações criadas
number
Ignoradas (duplicados ou erros de validação)
number
Falhas
array
Transações criadas
array
Erros por transação: index, externalId, error, code
string
Tempo total de processamento

Resposta 202 (processamento > 30 s ou background)

string
Identificador do job; correlacione com a notificação em tempo real ao concluir
string
"processing"
string
Mensagem indicando que o processo continua em segundo plano e será notificado no dashboard
number
(Apenas background-multi.) Número de arquivos em processamento

Exemplo de uso

Erros

  • 400 - Lote vazio ou tamanho excedido (máx. 100.000 por requisição)
  • 413 - Corpo > 50 MB (ou 150 MB no multi). Dividir em lotes menores.

Boas práticas

  1. Respeitar limites: 100.000 por requisição, 50 MB (150 MB no multi).
  2. Sempre usar skipDuplicates: true.
  3. Para importação histórica: executeRules: false e opcionalmente validateExistingEntity: false.
  4. Tratar 200 vs 202: 200 = resultado no corpo; 202 = job em background, aguardar notificação.
  5. Validar campos obrigatórios conforme Criar transação.
  6. Usar background-multi para muitos arquivos (até 10 em uma chamada).

Próximos passos