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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
file | File | Sim | Um ou mais arquivos (CSV, Excel, JSON). Repita o campo file para vários arquivos. |
executeRules | string | Não | "true" (padrão) ou "false" |
skipDuplicates | string | Não | "true" (padrão) ou "false" |
validateExistingEntity | string | Não | "true" (padrão) ou "false" |
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:| Plano | Máx. transações por arquivo |
|---|---|
| Freemium | 4.000 |
| Startup | 12.000 |
| Growth | 30.000 |
| Enterprise | 100.000 |
| Por uso (pay-as-you-go) | 100.000 |
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 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.Se as regras são executadas para todas as transações do lote
Ignorar transações com
externalId duplicado em vez de falhar todo o loteCom
true (padrão no lote): por linha, cada lado (origem/destino) só é validado se você enviar pelo menos um identificador daquele lado (*EntityId, *ExternalId ou *TaxId na raiz). Cada campo enviado deve existir na org; senão 400 INVALID_ENTITY_REFERENCES e nenhuma linha criada (conforme batchErrorHandling). Ordem de auto-vinculação: entityId → externalId → taxId.Com false: comportamento permissivo como Criar transação (padrão false lá).*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.
Corpo (apenas background-multi)
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)
Se a operação em lote foi concluída com sucesso
Número de transações criadas
Ignoradas (duplicados ou erros de validação)
Falhas
Transações criadas
Erros por transação:
index, externalId, error, codeTempo total de processamento
Resposta 202 (processamento > 30 s ou background)
Identificador do job; correlacione com a notificação em tempo real ao concluir
"processing"Mensagem indicando que o processo continua em segundo plano e será notificado no dashboard
(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