Criar transações em lote

curl --request POST \
  --url http://api.gu1.ai/transactions/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transactions": [
    {}
  ],
  "executeRules": true,
  "skipDuplicates": true,
  "validateExistingEntity": true,
  "sources": [
    {}
  ]
}
'

{
  "success": true,
  "created": 123,
  "skipped": 123,
  "failed": 123,
  "transactions": [
    {}
  ],
  "errors": [
    {}
  ],
  "processingTime": "<string>",
  "jobId": "<string>",
  "status": "<string>",
  "message": "<string>",
  "fileCount": 123
}

POST

transactions

batch

Criar transações em lote

curl --request POST \
  --url http://api.gu1.ai/transactions/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transactions": [
    {}
  ],
  "executeRules": true,
  "skipDuplicates": true,
  "validateExistingEntity": true,
  "sources": [
    {}
  ]
}
'

{
  "success": true,
  "created": 123,
  "skipped": 123,
  "failed": 123,
  "transactions": [
    {}
  ],
  "errors": [
    {}
  ],
  "processingTime": "<string>",
  "jobId": "<string>",
  "status": "<string>",
  "message": "<string>",
  "fileCount": 123
}

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

Ideal para: importar histórico, arquivos grandes (CSV, Excel, JSON), processadores de alto volume, migração de dados.

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)

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

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)

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

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

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, amount e currency. 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).

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

Authorization: Bearer YOUR_API_KEY

Corpo (sync e background)

transactions

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.

executeRules

boolean

default:"true"

Se as regras são executadas para todas as transações do lote

skipDuplicates

boolean

default:"true"

Ignorar transações com externalId duplicado em vez de falhar todo o lote

validateExistingEntity

boolean

default:"true"

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

Se o passo 2 ou 3 tiver sucesso, preenche *EntityId e pode preencher nome/país a partir da entidade, como no create único.

Corpo (apenas background-multi)

sources

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)

success

boolean

Se a operação em lote foi concluída com sucesso

created

number

Número de transações criadas

skipped

number

Ignoradas (duplicados ou erros de validação)

failed

number

Falhas

transactions

array

Transações criadas

errors

array

Erros por transação: index, externalId, error, code

processingTime

string

Tempo total de processamento

Resposta 202 (processamento > 30 s ou background)

jobId

string

Identificador do job; correlacione com a notificação em tempo real ao concluir

status

string

"processing"

message

string

Mensagem indicando que o processo continua em segundo plano e será notificado no dashboard

fileCount

number

(Apenas background-multi.) Número de arquivos em processamento

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

Respeitar limites: 100.000 por requisição, 50 MB (150 MB no multi).
Sempre usar skipDuplicates: true.
Para importação histórica: executeRules: false e opcionalmente validateExistingEntity: 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

Obter transação Enum Motivo da Transação

⌘I

Documentation Index

​Visão geral

​Endpoints

​Carga por arquivos (multipart)

​Campos do form

​Exemplo: envio com FormData (JavaScript)

​Exemplo: cURL

​Limites por plano

​Modelos (templates)

​Autenticação

​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

​Erros

​Boas práticas

​Próximos passos

Visão geral

Endpoints

Carga por arquivos (multipart)

Campos do form

Exemplo: envio com FormData (JavaScript)

Exemplo: cURL

Limites por plano

Modelos (templates)

Autenticação

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

Erros

Boas práticas

Próximos passos