Criar transações em lote
Referência API
Criar transações em lote
Criar múltiplas transações em uma única chamada para cenários de alto volume — na API de monitoramento de transações gu1 para fraude e AML.
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-multicom arraysources(até 5 arquivos, 100.000 transações cada); limite do corpo 150 MB. - Carga por arquivos (multipart): use
POST /transactions/batch/uploadpara enviar arquivos CSV, Excel ou JSON diretamente; máx. 5 arquivos por requisição. O limite por arquivo depende do seu plano.
- 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
jobIde continua processando em segundo plano. Ao terminar, o cliente é notificado no dashboard (e via socket em tempo real se conectado).
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/upload— Multipart form-data: envie um ou mais arquivos (CSV, Excel, JSON) no campofile; o servidor faz o parse e executa o mesmo fluxo. Ideal quando você tem arquivos em vez de JSON.
Endpoints
Carga por arquivos (multipart)
UsePOST /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ãofalse). Se você enviarvalidateGap=truecom 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 (portransactedAt). Se houver, retorna 400 comcode: "GAP_VALIDATION_REQUIRED"e a lista de intervalos. Por padrão a validação está desativada; use?validateGap=truepara 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:- 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.
- Campos obrigatórios por linha: Cada transação deve incluir pelo menos
externalId,type,amountecurrency. Recomendados:transactedAt,status,originName,destinationName,description. Esquema completo em Criar transação. - 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).
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 loteboolean
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.*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, codestring
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
- Respeitar limites: 100.000 por requisição, 50 MB (150 MB no multi).
- Sempre usar
skipDuplicates: true. - Para importação histórica:
executeRules: falsee opcionalmentevalidateExistingEntity: false. - Tratar 200 vs 202: 200 = resultado no corpo; 202 = job em background, aguardar notificação.
- Validar campos obrigatórios conforme Criar transação.
- Usar background-multi para muitos arquivos (até 10 em uma chamada).
Próximos passos
- Criar transação - Uma transação
- Alterar status da transação - Alterar status
- Monitoramento de transações - Detecção de fraude