Criar transações em lote

​

Visão geral

• 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.

• 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).

• 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 campo file; o servidor faz o parse e executa o mesmo fluxo. Ideal quando você tem arquivos em vez de JSON.

​

Endpoints

POST http://api.gu1.ai/transactions/batch
POST http://api.gu1.ai/transactions/batch/background
POST http://api.gu1.ai/transactions/batch/background-multi
POST http://api.gu1.ai/transactions/batch/upload   (multipart/form-data)

​

Carga por arquivos (multipart)

• 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 true). Se você enviar vários arquivos e houver um intervalo de tempo de 30 minutos ou mais entre o fim de um arquivo e o início do próximo (por transactedAt), a API retorna 400 com code: "GAP_VALIDATION_REQUIRED" e a lista de intervalos. Para continuar mesmo assim, reenvie com ?validateGap=false.

​

Campos do form

​

Exemplo: envio com FormData (JavaScript)

const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('executeRules', 'true');
form.append('skipDuplicates', 'true');
form.append('validateExistingEntity', 'true');

const response = await fetch('http://api.gu1.ai/transactions/batch/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: form   // Não defina Content-Type; o navegador define o boundary multipart
});
const data = await response.json();

​

Exemplo: cURL

curl -X POST http://api.gu1.ai/transactions/batch/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@transacoes.csv" \
  -F "executeRules=true" \
  -F "skipDuplicates=true"

​

Limites por plano

​

Modelos (templates)

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).

​

Autenticação

Authorization: Bearer YOUR_API_KEY

​

Corpo (sync e background)

​

Corpo (apenas background-multi)

​

Resposta 200 (concluído em 30 s)

​

Resposta 202 (processamento > 30 s ou background)

​

Exemplo de uso

curl -X POST http://api.gu1.ai/transactions/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "externalId": "txn_001",
        "type": "PAYMENT",
        "amount": 50.00,
        "currency": "USD",
        "originExternalId": "customer_001",
        "destinationExternalId": "merchant_100",
        "channel": "web_browser"
      }
    ],
    "executeRules": true,
    "skipDuplicates": true
  }'

​

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

• Criar transação - Uma transação
• Alterar status da transação - Alterar status
• Monitoramento de transações - Detecção de fraude