Fallos batch de transacciones

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

Fallos batch de transacciones

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 → descarga CSV (Content-Disposition: attachment)
…/failures → cuerpo JSON

Autenticación y permisos

Authorization: Bearer TU_API_KEY

Requiere al menos uno de: transactions:create, entities:bulk_import, events:create (mismo middleware que el resto de /batch-import).

Respuestas HTTP

Código	Cuándo
`200`	Job encontrado (CSV o JSON)
`401`	Sin autenticación
`403`	Sin permiso batch-import
`404`	`jobId` inexistente o de otra organización

Columnas CSV

Columna	Descripción
`external_id`	`externalId` de la transacción
`code`	Código estable — catálogo
`error`	Mensaje legible (igual que `message` en JSON)

Jobs legacy sin code en DB se normalizan al descargar cuando es posible. Si no hay fallos: CSV solo con header.

Respuesta JSON

Campo	Tipo	Descripción
`success`	boolean	Siempre `true` si el job existe
`jobId`	string	Id del job
`kind`	string	`transaction_batch`
`status`	string	`queued`, `running`, `completed`, `failed`, …
`totalItems`, `succeeded`, `failed`, `skipped`	number	Contadores del job
`failures`	array	`{ externalId, code, message }`
`jobFailure`	object	Solo si el job entero falló: `{ code, message, details? }` (p. ej. `INVALID_ENTITY_REFERENCES`)
`truncated`	boolean	`true` si hay más de 500 fallos. La muestra se hidrata desde `failures.csv`; descargá el CSV para la lista completa
`failuresTotal`	number	Total de filas fallidas informado por el artefacto del 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
}

Con batchErrorHandling=rollback_all (default del upload multipart), un error de insert o refs de entidad inválidas (con validación estricta) aborta el batch: 0 filas creadas; el detalle de refs va a failures.csv (S3) y jobFailure, no a un array gigante en metadata. Con continue_collect_errors o stop_keep_success, las refs inválidas y otros fallos de fila se registran por fila y las válidas sí se crean (o se detiene en el primero, según política).

Filas omitidas (duplicados)

GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/skips.csv

Las filas contadas en skipped no son fallos: la transacción no se insertó porque ya existía otra con el mismo externalId en tu organización. Este endpoint lista cuáles, para distinguir una recarga de duplicados de un problema real.

Columna	Descripción
`external_id`	`externalId` de la transacción que ya existía
`reason`	Siempre `DUPLICATE_EXTERNAL_ID`

Misma autenticación y permisos que los endpoints de fallos.

Código	Cuándo
`200`	Descarga CSV
`404`	`jobId` inexistente, de otra organización, o `SKIPS_NOT_AVAILABLE`

SKIPS_NOT_AVAILABLE significa que el job no tiene reporte guardado: jobs terminados antes de que existiera este endpoint, jobs sin filas omitidas, y jobs enviados con skipDuplicates=false (los duplicados los resuelve la base de datos y solo se cuentan, no se listan). Ver también: Códigos de fallo, Importar transacciones, Historial unificado.

⌘I

Comenzando

SDK

Casos de Uso

Webhooks

Workflows

Monitoreo (entidades)

Persona

Mensajería

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Listas personalizadas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Importaciones masivas

Documentos

Enriquecimiento

Servicios

Integraciones

Tutoriales Interactivos

Fallos batch de transacciones

Endpoints

Autenticación y permisos

Respuestas HTTP

Columnas CSV

Respuesta JSON

Filas omitidas (duplicados)

​Endpoints

​Autenticación y permisos

​Respuestas HTTP

​Columnas CSV

​Respuesta JSON

​Filas omitidas (duplicados)

Endpoints

Autenticación y permisos

Respuestas HTTP

Columnas CSV

Respuesta JSON

Filas omitidas (duplicados)