> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /transfers/qr — Crear transacción QR

> Genera un código QR de cobro inmediato escaneable por cualquier usuario de banca móvil en Bolivia.

Genera un código QR de cobro inmediato. El QR puede ser escaneado por cualquier usuario de banca móvil en Bolivia.

## Headers

| Header            | Tipo   | Req | Descripción                                                      |
| ----------------- | ------ | --- | ---------------------------------------------------------------- |
| `Authorization`   | string | Sí  | `Bearer <tu_api_token>`                                          |
| `Content-Type`    | string | Sí  | `application/json`                                               |
| `Idempotency-Key` | string | No  | UUID v4. Evita cobros duplicados en reintentos. Ventana de 24 h. |

## Request Body

| Campo               | Tipo             | Req | Descripción                                                                                     |
| ------------------- | ---------------- | --- | ----------------------------------------------------------------------------------------------- |
| `amount`            | string (Decimal) | Sí  | Monto del cobro. Hasta 12 dígitos con 2 decimales. Mínimo `0.00`.                               |
| `currency`          | string           | No  | Moneda. Solo `"BOB"`. Default: `"BOB"`.                                                         |
| `gloss`             | string           | Sí  | Descripción visible del cobro. Entre 3 y 100 caracteres.                                        |
| `expiration`        | string           | Sí  | Vencimiento del QR. Ej: `"30m"`, `"2h"`, `"7d"`, `"2026-12-31T23:59:59Z"`.                      |
| `singleUse`         | boolean          | No  | Si `true`, el QR se invalida tras el primer pago. Default: `true`.                              |
| `serviceCode`       | string           | No  | Código de clasificación del servicio. Default: `"001"`. Máx. 10 caracteres.                     |
| `payerDocument`     | string \| null   | No  | CI/NIT del pagador esperado. Restringe el QR a ese pagador. Máx. 20 caracteres.                 |
| `externalReference` | string \| null   | No  | ID interno del comercio (orden, carrito). Devuelto en respuesta y webhooks. Máx. 64 caracteres. |
| `distribution`      | object \| null   | No  | Split de fondos `{"cuenta": monto}`. Solo en CUCU Direct multi-destino.                         |
| `metadata`          | object \| null   | No  | Datos libres del comercio. Devueltos en consulta de estado y webhooks.                          |

## Response

| Campo               | Tipo              | Descripción                                                                      |
| ------------------- | ----------------- | -------------------------------------------------------------------------------- |
| `transactionId`     | string            | ID único de la transacción en CUCU. Usar para consultas de estado.               |
| `qrImageUrl`        | string \| null    | URL pública CDN de la imagen PNG. `null` si el CDN falló (usar `qrImageBase64`). |
| `qrImageBase64`     | string            | Imagen del QR como Base64 (PNG). Siempre presente.                               |
| `expiresAt`         | string (ISO 8601) | Fecha y hora de vencimiento en UTC.                                              |
| `amount`            | string            | Monto confirmado del cobro.                                                      |
| `currency`          | string            | Moneda del cobro.                                                                |
| `status`            | string            | Estado inicial. Siempre `"PENDING"` al crear.                                    |
| `commerceCode`      | string            | Slug identificador del comercio en CUCU.                                         |
| `externalReference` | string \| null    | La referencia externa enviada en el request.                                     |

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://qrsimple.cucu.bo/api/v1/transfers/qr \
    -H "Authorization: Bearer <tu_api_token>" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
    -d '{
      "amount": "150.00",
      "currency": "BOB",
      "gloss": "Pedido #ORD-2026-00871",
      "expiration": "30m",
      "singleUse": true,
      "externalReference": "ORD-2026-00871",
      "metadata": {
        "orderId": "ORD-2026-00871",
        "channel": "web"
      }
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch('https://qrsimple.cucu.bo/api/v1/transfers/qr', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <tu_api_token>',
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      amount: '150.00',
      currency: 'BOB',
      gloss: 'Pedido #ORD-2026-00871',
      expiration: '30m',
      singleUse: true,
      externalReference: 'ORD-2026-00871',
      metadata: { orderId: 'ORD-2026-00871', channel: 'web' }
    })
  });
  const data = await response.json();
  ```

  ```python Python theme={"system"}
  import uuid, requests

  response = requests.post(
      'https://qrsimple.cucu.bo/api/v1/transfers/qr',
      headers={
          'Authorization': 'Bearer <tu_api_token>',
          'Content-Type': 'application/json',
          'Idempotency-Key': str(uuid.uuid4())
      },
      json={
          'amount': '150.00',
          'currency': 'BOB',
          'gloss': 'Pedido #ORD-2026-00871',
          'expiration': '30m',
          'singleUse': True,
          'externalReference': 'ORD-2026-00871',
          'metadata': {'orderId': 'ORD-2026-00871', 'channel': 'web'}
      }
  )
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"system"}
  {
    "transactionId": "QR2026061500001",
    "qrImageUrl": "https://cdn.cucu.bo/qr/cucu-pay/QR2026061500001.png",
    "qrImageBase64": "<base64-png>",
    "expiresAt": "2026-06-15T14:30:00Z",
    "amount": "150.00",
    "currency": "BOB",
    "status": "PENDING",
    "commerceCode": "mi-comercio",
    "externalReference": "ORD-2026-00871"
  }
  ```

  ```json 400 Bad Request theme={"system"}
  {
    "detail": "El campo gloss es requerido"
  }
  ```

  ```json 409 Conflict theme={"system"}
  {
    "detail": "concurrent request"
  }
  ```

  ```json 422 Unprocessable Entity theme={"system"}
  {
    "detail": [
      {
        "type": "greater_than_equal",
        "loc": ["body", "amount"],
        "msg": "Input should be greater than or equal to 0",
        "input": "-5.00"
      }
    ]
  }
  ```
</ResponseExample>