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" }
}'
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();
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())
{
"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"
}
{
"detail": "X-Api-Key inválido o merchant inactivo"
}
{
"detail": "Solicitud duplicada en curso"
}
{
"detail": [
{
"type": "missing",
"loc": ["body", "gloss"],
"msg": "Field required"
}
]
}
POST /qr — Crear QR de cobro
POST /qr: genera un QR de cobro en bolivianos, de monto fijo o abierto, con vencimiento flexible y referencia a tu pedido; escaneable desde cualquier banca móvil.
POST
/
api
/
v1
/
qr
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" }
}'
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();
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())
{
"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"
}
{
"detail": "X-Api-Key inválido o merchant inactivo"
}
{
"detail": "Solicitud duplicada en curso"
}
{
"detail": [
{
"type": "missing",
"loc": ["body", "gloss"],
"msg": "Field required"
}
]
}
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. |
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. |
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" }
}'
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();
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())
{
"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"
}
{
"detail": "X-Api-Key inválido o merchant inactivo"
}
{
"detail": "Solicitud duplicada en curso"
}
{
"detail": [
{
"type": "missing",
"loc": ["body", "gloss"],
"msg": "Field required"
}
]
}