> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/cobros/generar-cobros-masivos.md).

# Generar cobros masivos

Crea varios cobros independientes en una sola solicitud. Cada cobro tiene su propia referencia y enlace. Para agrupar cobros existentes en un único enlace, consulta [Consolidar cobros](https://docs.qentaz.com/documentation/cobros/crear-cobro-multiple.md).

## Endpoint

`POST` `{{base_url}}/transaction/batch`

## Headers

| Nombre            | Obligatorio | Descripción                                                        |
| ----------------- | ----------- | ------------------------------------------------------------------ |
| `Content-Type`    | Sí          | `application/json`                                                 |
| `x-auth-token`    | Sí          | Token de autenticación.                                            |
| `child-id`        | No          | Identificador de la cuenta administrada.                           |
| `idempotency-key` | No          | Clave para identificar el lote y detectar una solicitud duplicada. |

## Body

| Campo          | Tipo          | Obligatorio | Descripción                                                                                                                                         |
| -------------- | ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transactions` | Array         | Sí          | Lista de al menos un objeto de cobro. Cada objeto usa los campos de [Generar Cobro](https://docs.qentaz.com/documentation/cobros/generar-cobro.md). |
| `process_id`   | String (UUID) | No          | Identificador común del lote. Si no se envía, la API genera uno.                                                                                    |

Cada cobro debe incluir `status`, `currency`, `amount` y `description`, así como al menos uno de `merchant_phone`, `merchant_email` o `merchant_id_number` para identificar al usuario que genera el cobro. Los demás campos y sus condiciones se describen en [Generar Cobro](https://docs.qentaz.com/documentation/cobros/generar-cobro.md).

## Ejemplo

Sustituye el teléfono por el de un usuario registrado de tu comercio.

```bash
curl --location --request POST '{{base_url}}/transaction/batch' \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: {token}' \
  --header 'idempotency-key: lote-facturas-001' \
  --data '{
    "transactions": [
      {
        "status": "PENDING",
        "currency": "COP",
        "amount": 20000,
        "description": "Factura cliente 1",
        "channel": "LINK",
        "merchant_phone": "573001234567",
        "reference_one": "FACT-001"
      },
      {
        "status": "PENDING",
        "currency": "COP",
        "amount": 35000,
        "description": "Factura cliente 2",
        "channel": "LINK",
        "merchant_phone": "573001234567",
        "reference_one": "FACT-002"
      }
    ]
  }'
```

## Respuesta

El siguiente ejemplo ilustra una respuesta parcial para un lote en el que el segundo elemento no incluye un identificador del usuario que genera el cobro.

Un `200` puede contener tanto cobros creados como errores individuales. Revisa ambas listas: `position` corresponde al índice del objeto en `transactions` y comienza en 0. `process_id` identifica el lote y también aparece en cada resultado exitoso.

```json
{
  "process_id": "550e8400-e29b-41d4-a716-446655440000",
  "success": {
    "total": 1,
    "data": [{
      "external_reference": "ABC123DEF",
      "channel": "LINK",
      "link": "https://pago.trazo.co/mi-comercio/t/ABC123DEF",
      "position": 0,
      "process_id": "550e8400-e29b-41d4-a716-446655440000"
    }]
  },
  "errors": {
    "total": 1,
    "data": [{
      "position": 1,
      "name": "Either a merchant phone number (merchant_phone) or a merchant email address (merchant_email) or a merchant id number (merchant_id_number) is required."
    }]
  },
  "created_at": "2026-10-28T10:30:00-05:00"
}
```

La creación puede ser parcial; corrige y reintenta únicamente los elementos fallidos para evitar duplicar los exitosos. Si envías `idempotency-key`, la API rechaza una clave duplicada para el comercio cuando encuentra transacciones creadas con ella durante el día operativo actual. No reutilices esa clave para un nuevo lote o para reintentar los elementos fallidos.

## Errores

* `400`: el cuerpo no cumple el esquema o la clave de idempotencia está duplicada.
* `401`: token ausente, vencido o inválido.
