Falhas batch de transações
curl --request GET \
--url http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyReferência API
Falhas batch de transações
Baixe relatórios CSV ou JSON com linhas de transações que falharam em um job batch, incluindo número da linha, códigos de erro e mensagens de validação.
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>'import requests
url = "http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyEndpoints
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
transactions:create, entities:bulk_import, events:create.
Respostas HTTP
| Código | Quando |
|---|---|
200 | Job encontrado (CSV ou JSON) |
401 | Sem autenticação |
403 | Sem permissão batch-import |
404 | jobId inexistente ou de outra organização |
Colunas CSV
| Coluna | Descrição |
|---|---|
external_id | externalId da transação |
code | Código estável — catálogo |
error | Mensagem legível (igual a message no JSON) |
code na DB são normalizados no download quando possível. Se não houver falhas: CSV só com header.
Resposta JSON
| Campo | Tipo | Descrição |
|---|---|---|
success | boolean | Sempre true se o job existe |
jobId | string | Id do job |
kind | string | transaction_batch |
status | string | queued, running, completed, failed, … |
totalItems, succeeded, failed, skipped | number | Contadores do job |
failures | array | { externalId, code, message } |
jobFailure | object | Se o job inteiro falhou: { code, message, details? } (p. ex. INVALID_ENTITY_REFERENCES) |
truncated | boolean | true se houver mais de 500 falhas. A amostra é hidratada do failures.csv; baixe o CSV para a lista completa |
failuresTotal | number | Total de linhas com falha informado pelo artefato do job |
{
"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 (padrão do upload multipart), um erro de insert ou refs de entidade inválidas (validação estrita) aborta o batch: 0 linhas criadas; o detalhe das refs vai para failures.csv (S3) e jobFailure, não para um array gigante em metadata. Com continue_collect_errors ou stop_keep_success, refs inválidas e outros falhas por linha são registradas por linha e as válidas são criadas (ou o processamento para no primeiro erro, conforme a política).Linhas ignoradas (duplicatas)
GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/skips.csv
skipped não são falhas: a transação não foi inserida porque já existia
outra com o mesmo externalId na sua organização. Este endpoint lista quais, para diferenciar um
reenvio de duplicatas de um problema real.
| Coluna | Descrição |
|---|---|
external_id | externalId da transação que já existia |
reason | Sempre DUPLICATE_EXTERNAL_ID |
| Código | Quando |
|---|---|
200 | Download CSV |
404 | jobId inexistente, de outra organização, ou SKIPS_NOT_AVAILABLE |
SKIPS_NOT_AVAILABLE significa que o job não tem relatório salvo: jobs finalizados antes deste
endpoint existir, jobs sem linhas ignoradas, e jobs enviados com skipDuplicates=false (as
duplicatas são resolvidas pelo banco e apenas contadas, não listadas).
Ver também: Códigos de falha, Importar transações, Histórico unificado.Was this page helpful?