Documentación de la API REST

API REST para clientes con plan pago vigente: crear, editar, listar y descargar QR dinámicos y consultar sus escaneos desde kioscos, supermercados y cajas. Los QR creados por API llevan el logo y los colores del diseño por defecto de tu cuenta. Límite: 60 pedidos por minuto por clave.

Autenticación

Generá tu clave en Mi cuenta (plan pago vigente). Se muestra una sola vez; se puede regenerar o revocar. Enviala en el encabezado Authorization: Bearer. Todas las respuestas son JSON, salvo las imágenes.

Authorization: Bearer q4u_<40 hex>
Base URL: https://qr4u.cloud/api/v1

Endpoints

Endpoint	Descripción
`POST /api/v1/qrs`	Crea un QR dinámico con el diseño por defecto de la cuenta. Cuerpo JSON: {"url": "https://..."}. Responde 201 con el QR.
`GET /api/v1/qrs`	Lista tus QR (más nuevos primero). Parámetros: limit (1-100, por defecto 50) y offset.
`GET /api/v1/qrs/{code}`	Devuelve un QR: code, url (enlace corto), destination, status, scans, last_scan, created_at.
`PATCH /api/v1/qrs/{code}`	Cambia el destino. Cuerpo JSON: {"url": "https://..."}. El QR impreso sigue igual.
`GET /api/v1/qrs/{code}/stats`	Escaneos totales y fecha del último escaneo.
`GET /api/v1/qrs/{code}.png`	Imagen PNG del QR con su diseño (ECC H).
`GET /api/v1/qrs/{code}.svg`	Imagen SVG del QR con su diseño, logo incrustado.

Ejemplo

curl -X POST https://qr4u.cloud/api/v1/qrs \
  -H "Authorization: Bearer $QR4U_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/menu"}'

HTTP/1.1 201 Created
{
  "code": "k3m9pqx",
  "url": "https://qr4u.cloud/k3m9pqx",
  "destination": "https://example.com/menu",
  "status": "active",
  "scans": 0,
  "last_scan": null,
  "created_at": "2026-10-18T12:00:00Z",
  "kind": "qr",
  "mode": "dynamic",
  "has_design": true,
  "png": "https://qr4u.cloud/api/v1/qrs/k3m9pqx.png",
  "svg": "https://qr4u.cloud/api/v1/qrs/k3m9pqx.svg"
}

Límites

60 pedidos por minuto por clave (ventana deslizante). Al excederlo responde 429 con el encabezado Retry-After (segundos).

Errores

Los errores devuelven JSON con el mismo formato y el código HTTP correspondiente:

{"error": {"code": "invalid_url", "message": "Field \"url\" must be a valid http or https URL."}}

Código	Descripción
`400 invalid_json / invalid_url`	Cuerpo no válido o URL que no es http/https.
`401 unauthorized`	Falta la clave o es inválida.
`402 plan_required`	El plan pago venció.
`404 not_found`	El QR no existe o no es tuyo.
`405 method_not_allowed`	Método no permitido (ver encabezado Allow).
`422 unsafe_url / design_unreadable`	Destino marcado como peligroso por Safe Browsing, o el diseño por defecto no genera un QR legible.
`429 rate_limited`	Más de 60 pedidos por minuto.

Los QR creados por API usan el diseño por defecto de la cuenta, que se define en el panel. Si el diseño no produce un QR legible, la creación se rechaza.