Skip to main content
POST
Crear transacciones en lote

Resumen

Crea múltiples transacciones en una sola operación en lote. Este endpoint está optimizado para alto volumen. Límites:
  • 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.
Comportamiento (endpoint síncrono):
  • 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).
Endpoints en segundo plano (siempre asíncronos):
  • 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/uploadMultipart 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.
Ideal para: importar histórico, archivos grandes (CSV, Excel, JSON), procesadores de pagos de alto volumen, migración de datos.

Endpoints

Carga por archivos (multipart)

Usá POST /transactions/batch/upload cuando tengas archivos CSV, Excel o JSON y quieras que el servidor los parsee. La petición debe ser multipart/form-data (FormData), no JSON.
  • 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 false). Si enviás validateGap=true con varios archivos, la API comprueba que no haya un salto de tiempo de 30 minutos o más entre el fin de un archivo y el inicio del siguiente (por transactedAt). Si lo hay, devuelve 400 con code: "GAP_VALIDATION_REQUIRED" y la lista de saltos. Por defecto la validación está desactivada; usá ?validateGap=true para activarla.

Campos del form

Ejemplo: envío con FormData (JavaScript)

Ejemplo: cURL

Límites por plan

El máximo de transacciones por archivo (tanto en upload como en background-multi) depende del plan de la organización: Si la carga batch está deshabilitada para tu organización, los endpoints devuelven 403. Contactá a soporte para habilitarla o cambiar de plan.

Plantillas

Para armar archivos CSV, Excel o JSON que cumplan el esquema:
  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).
No hay una URL pública para descargar plantillas fuera del dashboard; usá el modal de carga batch para obtener las plantillas actualizadas.

Autenticación

Cuerpo (sync y background)

array
required
Array de objetos de transacción (mín. 1, máx. 100.000 por petición). Misma estructura que Crear transacción. Cuerpo máx. 50 MB.exchangeRate opcional por fila: solo si falla la conversión automática; ver Conversión de moneda.
boolean
default:"true"
Si se ejecutan reglas para todas las transacciones del lote
boolean
default:"true"
Omitir transacciones con externalId duplicado en lugar de fallar todo el lote
Override opcional. true: hard-fail. false: soft-link. Si se omite, manda validateExistingEntity. También ?linkEntityStrict=true|false.
boolean
default:"true"
Default de batch true (sin cambio para quien omite el campo): refs sin resolver → 400. Con false: auto-vincula si encuentra y sigue sin vínculo si no.
Si hay match en el paso 2 o 3, se rellenan *EntityId y, si no enviaste nombre/país, se pueden rellenar *Name y *Country desde la entidad (como en creación individual). Cuando un extremo queda vinculado (incluso si ya enviaste *EntityId), originTaxId / originExternalId y destinationTaxId / destinationExternalId se sincronizan siempre desde la entidad antes del insert — misma denormalización canónica que Crear transacción — origen. Cada fila creada también recibe el campo linkedEntityGu1, propiedad del servidor, dentro de originDetails y destinationDetails. Su valor es linked, unresolved o not_requested. Gu1 ignora y sobrescribe cualquier valor incluido en el archivo.

Cuerpo (solo background-multi)

array
required
Array de objetos: { "fileName": "opcional", "transactions": [ ... ] }. Mín. 1, máx. 5 fuentes. Cada transactions: máx. 100.000 (o el límite de tu plan por archivo). Cuerpo total máx. 150 MB.

Respuesta 200 (completado en 30 s)

boolean
Si la operación en lote se completó correctamente
number
Número de transacciones creadas
number
Omitidas (duplicados o errores de validación)
number
Fallidas
array
Transacciones creadas
array
Errores por transacción: index, externalId, error, code
string
Tiempo total de procesamiento

Respuesta 202 (procesamiento > 30 s o background)

string
Identificador del job; correlacionar con la notificación en tiempo real al completar
string
"processing"
string
Mensaje indicando que el proceso continúa en segundo plano y se notificará en el dashboard
number
(Solo background-multi.) Número de archivos en proceso

Ejemplo de uso

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