---
title: "Crear Transactions externas en lote"
method: POST
path: "/transactions/external/bulk"
tags: ["Transactions"]
---

# Crear Transactions externas en lote

`POST /transactions/external/bulk`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/transactions/external/bulk`
- Auth: API key in header `x-api-key`

Registra un lote de Transactions externas.

Una Transaction externa registra un pago que el deudor hizo por fuera de Toku —transferencia, caja, efectivo— para dejar sus Invoices saldados. Se usa para cargar muchos de esos pagos en una sola llamada, con el mismo contenido de un registro individual en cada elemento de `transactions`. Acepta como máximo 100 por llamada.

Cada elemento se procesa por separado, así que la llamada responde `201` incluso si algunos elementos no se pudieron registrar: `response_counts` resume cuántos quedaron registrados, cuántos se descartaron por repetidos y cuántos fallaron, `error_detail` agrupa los descartados por motivo —Invoice inexistente, anulado o ya pagado, monto que no coincide con la suma de los montos de los Invoices, o error al guardar— y `transactions` devuelve, en el mismo orden del lote, el identificador de cada Transaction creada o `null` cuando ese elemento no se registró.

Dentro del mismo lote, dos elementos con los mismos Invoices, la misma fecha y el mismo `external_id` se consideran repetidos y solo se registra el primero; los elementos con pagos parciales quedan fuera de esa comparación.

**Límite de tasa:** 1 solicitud por segundo. Al superarlo, la API responde `429`. Ver [Límites de tasa](/reference/limites-de-tasa).

## Headers

- `x-account-key` string

## Request body

- CreateBulkExternalTransactionRequest: Lote de pagos hechos por fuera de Toku que se registran juntos.
  - `transactions` CreateExternalTransactionRequest[], required: Pagos que componen el lote; hasta 100 por llamada.
    - `amount` number: Monto total del pago registrado.
    - `currency` 'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD', required: Moneda, en código [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). Cubre las monedas de los países donde Toku opera —`CLP` (peso chileno), `MXN` (peso mexicano) y `BRL` (real)— más `USD` y `CLF`, la Unidad de Fomento chilena. La moneda determina cuántos decimales admiten los montos: `CLP` no admite decimales, `MXN`, `BRL` y `USD` admiten dos, y `CLF` cuatro.
    - `external_id` string: Referencia externa que la Organization asigna a la Transaction.
    - `id_account` string, required: Identificador público de la Account que hizo el pago.
    - `id_customer` string: Identificador público del Customer al que se atribuye el pago.
    - `invoices` PublicInvoiceToPayDetail[]: Invoices que cubre el pago. Si va vacío, el pago queda asociado solo a la Account.
      - `amount` number: Monto del pago que se imputa a este Invoice.
      - `amount_in_invoice_currency` number: Monto imputado al Invoice expresado en la moneda del Invoice.
      - `id_invoice` string, required: Identificador público del Invoice que se salda.
      - `is_partial_payment` boolean: Cuando es `true`, el Invoice queda parcialmente pagado en vez de saldado por completo.
    - `payment_method_detail` string: Detalle del medio con que se pagó, tal como lo informa la Organization.
    - `provider_external_id` string: Referencia que el proveedor del pago asigna a la Transaction.
    - `transaction_data` object: Datos libres que la Organization adjunta a la Transaction.
    - `transaction_date` string, date-time: Fecha en que se hizo el pago; si se omite, se usa la fecha actual.

## Response `201`

Resultado del lote, con el recuento por categoría y el identificador de cada elemento.

- PublicCreateBulkExternalTransactionResponse: Variante del resultado de creación en lote con los identificadores públicos de las Transactions.
  - `error_detail` PublicCreateBulkExternalTransactionErrorDetail, required: Variante del detalle de errores en que los Invoices se identifican con su id público.
    - `amount_mismatch` object[]: Elementos cuyo `amount` no coincide con la suma de los montos de sus Invoices.
    - `customer_not_found` object[]: Elementos cuyo Customer no se pudo resolver a partir de su referencia.
    - `failed_to_save` object[]: Elementos que no se pudieron guardar o cuya Account no era utilizable.
    - `invalid_payment_intent` object[]: Elementos con un Payment Intent que no se pudo usar.
    - `invoice_already_paid` object[]: Elementos con algún Invoice que ya estaba pagado.
    - `invoice_being_paid` object[]: Elementos con algún Invoice que tenía un cobro en curso.
    - `invoice_is_void` object[]: Elementos con algún Invoice anulado.
    - `invoice_not_found` object[]: Elementos con algún Invoice que no existe o que no se pudo leer.
  - `response_counts` BulkResponseCounts, required: Recuento de elementos del lote por resultado.
    - `duplicates` integer: Elementos descartados por repetir a otro del mismo lote.
    - `error` integer: Elementos que no se pudieron procesar.
    - `format_error` integer: Elementos descartados porque les faltaba un campo obligatorio.
    - `not_found` integer: Elementos descartados porque una entidad referida no se pudo usar.
    - `success` integer: Elementos que quedaron registrados o actualizados.
    - `unchanged` integer: Elementos que ya existían sin cambios y se dejaron intactos.
  - `success` boolean, required: Indica que el lote se procesó; los resultados por elemento van en los demás campos.
  - `transactions` string[]: Identificador público de la Transaction de cada elemento, en el mismo orden del lote; `null` cuando ese elemento no quedó registrado.

## Other responses

- `401`: Faltan las credenciales o son inválidas.
- `403`: No tienes acceso a este recurso.
- `404`: El recurso solicitado no existe.
- `422`: El cuerpo de la petición no pasó la validación.
- `429`: Se superó el límite de peticiones permitidas.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/transactions/external/bulk/post.md)

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)