Skip to main content
GET
/
batch-import
/
transaction-jobs
/
{jobId}
/
failures
Falhas batch de transações
curl --request GET \
  --url http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures \
  --header 'Authorization: Bearer <token>'

​
Endpoints

GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures.csv
GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures
  • …/failures.csv → download CSV (Content-Disposition: attachment)
  • …/failures → corpo JSON

​
Autenticação e permissões

Authorization: Bearer SUA_API_KEY
Requer pelo menos um de: transactions:create, entities:bulk_import, events:create.

​
Respostas HTTP

CódigoQuando
200Job encontrado (CSV ou JSON)
401Sem autenticação
403Sem permissão batch-import
404jobId inexistente ou de outra organização

​
Colunas CSV

ColunaDescrição
external_idexternalId da transação
codeCódigo estável — catálogo
errorMensagem legível (igual a message no JSON)
Jobs legacy sem code na DB são normalizados no download quando possível. Se não houver falhas: CSV só com header.

​
Resposta JSON

CampoTipoDescrição
successbooleanSempre true se o job existe
jobIdstringId do job
kindstringtransaction_batch
statusstringqueued, running, completed, failed, …
totalItems, succeeded, failed, skippednumberContadores do job
failuresarray{ externalId, code, message }
jobFailureobjectSe o job inteiro falhou: { code, message, details? } (p. ex. INVALID_ENTITY_REFERENCES)
truncatedbooleantrue se há mais de 500 falhas persistidas
failuresTotalnumberTotal de linhas com falha armazenadas
{
  "success": true,
  "jobId": "abc-123",
  "kind": "transaction_batch",
  "status": "completed",
  "totalItems": 10,
  "succeeded": 9,
  "failed": 1,
  "skipped": 0,
  "failures": [
    {
      "externalId": "txn-009",
      "code": "CONSTRAINT_VIOLATION",
      "message": "…"
    }
  ],
  "truncated": false,
  "failuresTotal": 1
}
Com batchErrorHandling=rollback_all (default), o primeiro erro de insert costuma abortar o batch e não persistir falhas por linha. Use continue_collect_errors ou stop_keep_success para popular este endpoint. Referências de entidade inválidas com validateExistingEntity=true falham o job inteiro (jobFailure), não linhas individuais no CSV.
Ver também: Códigos de falha, Importar transações, Histórico unificado.