API de códigos QR: cómo integrar la generación en tu web o app

La API de codigo-qr.es tiene dos tiers.

Endpoint público (sin cuenta):

`POST /api/v1/qr/render` genera un QR estático y devuelve la imagen en base64. Límite: 50 peticiones al día por IP.

Endpoints Pro (requieren API key):

| Método | Ruta | Para qué sirve | |--------|------|----------------| | `GET` | `/api/v1/qr` | Listar todos tus QR | | `POST` | `/api/v1/qr` | Crear QR estático o dinámico | | `GET` | `/api/v1/qr/{id}` | Detalle de un QR | | `PATCH` | `/api/v1/qr/{id}` | Cambiar destino o nombre | | `DELETE` | `/api/v1/qr/{id}` | Eliminar un QR | | `GET` | `/api/v1/qr/{id}/image` | Descargar imagen PNG o SVG | | `GET` | `/api/v1/qr/{id}/stats` | Estadísticas de escaneos |

Todas las respuestas Pro siguen el formato `{ "data": {...}, "error": null }`. Si hay error, `data` es null y `error` contiene `code` y `message`.

Paso 1. Crea una cuenta en codigo-qr.es.

Paso 2. Activa el plan Pro. La API completa es exclusiva Pro a 5,99€/mes.

Paso 3. Ve a /panel/cuenta y pulsa «Generar API key». El token se muestra una sola vez. Guárdalo en un gestor de contraseñas o variable de entorno.

Añade este header a cada petición:

```bash curl https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_tu_token_aqui" ```

Si la key no es válida o el plan ha expirado, la API devuelve `401 UNAUTHORIZED` o `403 PLAN_REQUIRED`. Puedes revocar la key en cualquier momento desde el panel; deja de funcionar de inmediato.

El endpoint público es la forma más rápida de probar la API o de generar QR simples desde un script sin gestionar autenticación:

```bash curl -X POST https://codigo-qr.es/api/v1/qr/render \ -H "Content-Type: application/json" \ -d '{"value":"https://tudominio.com","format":"png","size":512}' ```

Parámetros:

- `value` (obligatorio): el contenido del QR. Puede ser una URL, texto, email, datos WiFi...
• `format`: `"png"` (por defecto) o `"svg"`
• `size`: `256`, `512` (por defecto) o `1024`

La respuesta devuelve la imagen en base64 dentro del envelope JSON:

```json { "data": { "image": "iVBORw0KGgo...", "format": "png", "size": 512 }, "error": null } ```

Si superas 50 peticiones al día desde la misma IP, recibes `429 RATE_LIMITED` con el header `Retry-After` indicando cuándo se reinicia el contador.

Un QR dinámico codifica una URL corta fija (`/r/{slug}`) pero su destino final se puede cambiar cuando quieras. El código impreso no cambia nunca.

Crear un QR dinámico:

```bash curl -X POST https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_tu_token" \ -H "Content-Type: application/json" \ -d '{ "label": "Carta restaurante mayo", "type": "url", "value": "https://turestaurante.com/carta-mayo", "is_dynamic": true, "tracking_mode": "redirect" }' ```

Cambiar el destino sin reimprimir:

```bash curl -X PATCH https://codigo-qr.es/api/v1/qr/{id} \ -H "Authorization: Bearer cqr_tu_token" \ -H "Content-Type: application/json" \ -d '{"destination": "https://turestaurante.com/carta-junio"}' ```

Descargar la imagen del QR:

```bash curl -o mi-qr.png \ "https://codigo-qr.es/api/v1/qr/{id}/image?format=png&size=1024" \ -H "Authorization: Bearer cqr_tu_token" ```

Ver estadísticas de escaneos:

```bash curl "https://codigo-qr.es/api/v1/qr/{id}/stats?period=30d" \ -H "Authorization: Bearer cqr_tu_token" ```

Respuesta: ```json { "data": { "total": 312, "period": "30d", "by_day": [{"date": "2026-05-01", "count": 18}], "by_country": [{"country": "ES", "count": 290}] }, "error": null } ```

La API sirve cuando el volumen o la automatización hacen inviable generar QR a mano desde el panel.

Ecommerce: QR en albaranes y facturas

El sistema ERP genera el PDF del albarán. Con una llamada a `POST /api/v1/qr`, obtiene un QR que apunta a la URL de seguimiento del pedido. Si la URL cambia, `PATCH /api/v1/qr/{id}` actualiza el destino sin regenerar ni reimprimir nada.

Restaurantes: carta por mesa desde el POS

El sistema de caja crea un QR por mesa al abrir el turno. Apunta a la carta del día, que el chef actualiza en el CMS. El QR en la mesa no cambia; el destino sí. Sin plastificar cartas nuevas cada semana.

Eventos: entradas personalizadas en lote

Un sistema de ticketing genera un QR único por entrada con `POST /api/v1/qr` y lo incrusta en el PDF. En la puerta, el scanner verifica el QR leyendo `GET /api/v1/qr/{id}` para confirmar si es válido.

Logística: paquetes con tracking

Cada paquete recibe un QR que apunta a su página de seguimiento. El cliente escanea desde el sobre y ve el estado en tiempo real. Los escaneos quedan en `GET /api/v1/qr/{id}/stats`.

La API aplica límites de tasa para garantizar disponibilidad.

Tier pública (`/api/v1/qr/render`):
• Límite: 50 peticiones por día por IP
• Ventana: 24 horas
• Sin registro requerido

Tier Pro (endpoints con API key):
• Límite: 60 peticiones por minuto por usuario
• Sin límite diario total

Al superar el límite, la API devuelve `429 Too Many Requests` con estos headers:

``` X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1747612800 Retry-After: 43 ```

`X-RateLimit-Reset` es el timestamp Unix en el que se reinicia el contador. `Retry-After` son los segundos hasta ese momento.

Ver la documentación completa de la API para todos los parámetros y respuestas de error.