Crear transacciones en lote

​

Resumen

• Un solo lote: hasta 100.000 transacciones por petición; el cuerpo no debe superar 50 MB.
• Varios archivos en una llamada: usar POST /transactions/batch/background-multi con un array sources (hasta 5 archivos, 100.000 transacciones cada uno); límite del cuerpo 150 MB.
• Carga por archivos (multipart): usar POST /transactions/batch/upload para enviar archivos CSV, Excel o JSON directamente; máx. 5 archivos por petición. El límite por archivo depende de tu plan.

• La API mantiene la conexión abierta hasta 30 segundos.
• Si el lote termina en 30 segundos, responde 200 con el resumen completo (creadas, omitidas, reglas ejecutadas, tiempo, etc.).
• Si supera 30 segundos, responde 202 con un jobId y sigue procesando en segundo plano. Al terminar se notifica en el dashboard (y por socket en tiempo real si está conectado).

• POST /transactions/batch/background — Un solo lote; devuelve 202 de inmediato y notifica por socket al terminar.
• POST /transactions/batch/background-multi — Varios archivos en una petición (máx. 5); devuelve 202 y una notificación cuando se procesan todos.
• POST /transactions/batch/upload — Multipart form-data: enviar uno o más archivos (CSV, Excel, JSON) en el campo file; el servidor los parsea y ejecuta el mismo flujo. Ideal cuando tenés archivos en lugar de JSON.

​

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 archivos (multipart)

• Máx. 5 archivos por petición.
• Formatos aceptados: CSV (.csv), Excel (.xlsx, .xls), JSON (.json).
• Límite de transacciones por archivo según el plan de la organización (ver Límites por plan).
• Query: validateGap (por defecto true). Si enviás varios archivos y hay un salto de tiempo de 30 minutos o más entre el fin de un archivo y el inicio del siguiente (por transactedAt), la API devuelve 400 con code: "GAP_VALIDATION_REQUIRED" y la lista de saltos. Para continuar igual, reenviá con ?validateGap=false.

​

Campos del form

​

Ejemplo: envío con 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   // No pongas Content-Type; el navegador setea el boundary multipart
});
const data = await response.json();

​

Ejemplo: cURL

curl -X POST http://api.gu1.ai/transactions/batch/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@transacciones.csv" \
  -F "executeRules=true" \
  -F "skipDuplicates=true"

​

Límites por plan

​

Plantillas

1. Dashboard: En Monitoreo de transacciones, abrí el modal Carga batch. Usá los botones Descargar CSV, Descargar Excel o Descargar JSON para obtener plantillas con los encabezados correctos y una fila de ejemplo. Es la forma más sencilla de empezar.
2. Campos requeridos por fila: Cada transacción debe incluir al menos externalId, type, amount y currency. Recomendados: transactedAt, status, originName, destinationName, description. Esquema completo en Crear transacción.
3. CSV/Excel: Los nombres de columna pueden ser camelCase (externalId, transactedAt) o snake_case (external_id, transacted_at); el servidor los normaliza. Fecha en ISO 8601 (ej. 2025-01-15T10:30:00.000Z).

​

Autenticación

Authorization: Bearer YOUR_API_KEY

​

Cuerpo (sync y background)

​

Cuerpo (solo background-multi)

​

Respuesta 200 (completado en 30 s)

​

Respuesta 202 (procesamiento > 30 s o background)

​

Ejemplo 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
  }'

​

Errores

• 400 - Lote vacío o tamaño excedido (máx. 100.000 por request)
• 413 - Cuerpo > 50 MB (o 150 MB en multi). Dividir en lotes más pequeños.

​

Buenas prácticas

1. Respetar límites: 100.000 por request, 50 MB (150 MB multi).
2. Usar siempre skipDuplicates: true.
3. Para importación histórica: executeRules: false y opcionalmente validateExistingEntity: false.
4. Manejar 200 vs 202: 200 = resultado en el cuerpo; 202 = job en background, esperar notificación.
5. Validar campos requeridos según Crear transacción.
6. Usar background-multi para muchos archivos (hasta 10 en una llamada).

​

Próximos pasos

• Crear transacción - Una transacción
• Cambiar estado de transacción - Cambiar estado
• Monitoreo de transacciones - Detección de fraude