> ## 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.

# Referencia de campos

> Definición completa de los campos del request y la respuesta de la transacción QR.

## Referencia de campos

***

## Request — Crear transacción QR

| Campo               | Tipo               | Requerido | Descripción                                                                                                                                                               |
| ------------------- | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`            | `Decimal` (string) | Sí        | Monto del cobro. Hasta 12 dígitos con 2 decimales. Mínimo `0.00`.                                                                                                         |
| `currency`          | `string` (enum)    | No        | Moneda. Actualmente solo `"BOB"`. Default: `"BOB"`.                                                                                                                       |
| `gloss`             | `string`           | Sí        | Descripción visible del cobro. Entre 3 y 100 caracteres.                                                                                                                  |
| `expiration`        | `string`           | Sí        | Vencimiento del QR. Ver [Guía de expiración flexible](/payments/transferencias/guia-expiracion).                                                                          |
| `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. Si se especifica, restringe el QR a ese pagador. Máx. 20 caracteres.                                                                         |
| `externalReference` | `string` \| `null` | No        | ID interno del comercio (orden, carrito). Se devuelve en la respuesta y en webhooks. Máx. 64 caracteres.                                                                  |
| `distribution`      | `object` \| `null` | No        | Split de distribución de fondos `{"cuenta": monto}`. Solo aplica en configuraciones CUCU Direct multi-destino. Si `null`, se usa la configuración de cuenta del comercio. |
| `metadata`          | `object` \| `null` | No        | Datos libres del comercio. Indexados y devueltos en la consulta de estado.                                                                                                |

***

## Response — Transacción creada

| 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 upload al CDN falló (usar `qrImageBase64`). |
| `qrImageBase64`     | `string`            | Imagen del QR como string Base64 (PNG). Siempre presente.                                  |
| `expiresAt`         | `string` (ISO 8601) | Fecha y hora de vencimiento en UTC.                                                        |
| `amount`            | `Decimal`           | Monto confirmado del cobro.                                                                |
| `currency`          | `string`            | Moneda del cobro.                                                                          |
| `status`            | `string` (enum)     | Estado inicial. Siempre `"PENDING"` al crear.                                              |
| `commerceCode`      | `string`            | Slug identificador del comercio en CUCU.                                                   |
| `externalReference` | `string` \| `null`  | La referencia externa enviada en el request.                                               |