> ## 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 /qr — Crear QR de cobro

> Genera un QR de cobro escaneable desde cualquier banca móvil de Bolivia.

Genera un QR de cobro. Se paga escaneándolo desde la app de cualquier banco de Bolivia.

## Headers

| Header            | Tipo   | Req | Descripción                                                                    |
| ----------------- | ------ | --- | ------------------------------------------------------------------------------ |
| `X-Api-Key`       | string | Sí  | Tu API key.                                                                    |
| `Content-Type`    | string | Sí  | `application/json`                                                             |
| `Idempotency-Key` | string | No  | UUID v4. Un reintento con la misma key devuelve el mismo QR (ventana de 24 h). |

## Request Body

| Campo               | Tipo             | Req | Descripción                                                                                                             |
| ------------------- | ---------------- | --- | ----------------------------------------------------------------------------------------------------------------------- |
| `amount`            | string (Decimal) | Sí  | Monto con 2 decimales. `0` = QR de monto abierto: el pagador digita el importe.                                         |
| `gloss`             | string           | Sí  | Descripción visible del cobro. Entre 3 y 100 caracteres.                                                                |
| `expiration`        | string           | Sí  | Vencimiento: `"30m"`, `"2h"`, `"7d"` o `"2026-12-31T23:59:59Z"`. Ver [expiración](/payments/cobros-qr/guia-expiracion). |
| `currency`          | string           | No  | Solo `"BOB"`. Default: `"BOB"`.                                                                                         |
| `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 de tu orden o carrito. Vuelve en la respuesta y en la consulta de estado. 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 de tu sistema. Vuelven en la consulta de estado.                                                           |

## Response

| Campo               | Tipo              | Descripción                                                             |
| ------------------- | ----------------- | ----------------------------------------------------------------------- |
| `qrId`              | string            | Identificador del QR. Úsalo para consultar el estado.                   |
| `qrImageUrl`        | string \| null    | URL pública de la imagen PNG. Prefiérela; `null` si no está disponible. |
| `qrImageBase64`     | string            | Imagen PNG en Base64. Siempre presente.                                 |
| `expiresAt`         | string (ISO 8601) | Vencimiento efectivo en UTC.                                            |
| `amount`            | string            | Monto del cobro.                                                        |
| `currency`          | string            | `BOB`.                                                                  |
| `status`            | string            | `PENDING` al crear.                                                     |
| `merchantCode`      | string            | Código de tu comercio en CUCU.                                          |
| `externalReference` | string \| null    | La referencia que enviaste.                                             |

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

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

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

  response = requests.post(
      'https://qrsimple.cucu.bo/api/v1/qr',
      headers={
          'X-Api-Key': '<tu_api_key>',
          'Idempotency-Key': str(uuid.uuid4())
      },
      json={
          'amount': '150.00',
          'gloss': 'Pedido #ORD-2026-00871',
          'expiration': '30m',
          'externalReference': 'ORD-2026-00871',
          'metadata': {'channel': 'web'}
      }
  )
  print(response.json())
  ```
</RequestExample>

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

  ```json 401 Unauthorized theme={"system"}
  {
    "detail": "X-Api-Key inválido o merchant inactivo"
  }
  ```

  ```json 409 Conflict theme={"system"}
  {
    "detail": "Solicitud duplicada en curso"
  }
  ```

  ```json 422 Unprocessable Entity theme={"system"}
  {
    "detail": [
      {
        "type": "missing",
        "loc": ["body", "gloss"],
        "msg": "Field required"
      }
    ]
  }
  ```
</ResponseExample>