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

}

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_body

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

}

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_body

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

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

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

As linhas contadas em 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`

Mesma autenticação e permissões dos endpoints de falhas.

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.

⌘I

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

Serviços

Integrações

Tutoriais Interativos

Falhas batch de transações

Endpoints

Autenticação e permissões

Respostas HTTP

Colunas CSV

Resposta JSON

Linhas ignoradas (duplicatas)

​Endpoints

​Autenticação e permissões

​Respostas HTTP

​Colunas CSV

​Resposta JSON

​Linhas ignoradas (duplicatas)

Endpoints

Autenticação e permissões

Respostas HTTP

Colunas CSV

Resposta JSON

Linhas ignoradas (duplicatas)