API de codis QR: com integrar la generació a la teva web o app

L'API de codigo-qr.es té dos tiers.

Endpoint públic (sense compte):

`POST /api/v1/qr/render` genera un QR estàtic i retorna la imatge en base64. Límit: 50 peticions al dia per IP.

Endpoints Pro (requereixen API key):

| Mètode | Ruta | Per a que serveix | |--------|------|-------------------| | `GET` | `/api/v1/qr` | Llistar tots els teus QR | | `POST` | `/api/v1/qr` | Crear QR estàtic o dinàmic | | `GET` | `/api/v1/qr/{id}` | Detall d'un QR | | `PATCH` | `/api/v1/qr/{id}` | Canviar destí o nom | | `DELETE` | `/api/v1/qr/{id}` | Eliminar un QR | | `GET` | `/api/v1/qr/{id}/image` | Descarregar imatge PNG o SVG | | `GET` | `/api/v1/qr/{id}/stats` | Estadístiques d'escanejos |

Totes les respostes Pro segueixen el format `{ "data": {...}, "error": null }`. Si hi ha error, `data` és null i `error` conté `code` i `message`.

Pas 1. Crea un compte a codigo-qr.es.

Pas 2. Activa el pla Pro. L'API completa és exclusiva Pro a 5,99€/mes.

Pas 3. Ves a /panel/compte i prem «Generar API key». El token es mostra una sola vegada. Guarda'l en un gestor de contrasenyes o variable d'entorn.

Afegeix aquesta capcalera a cada petició:

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

Si la key no és vàlida o el pla ha expirat, l'API retorna `401 UNAUTHORIZED` o `403 PLAN_REQUIRED`. Pots revocar la key en qualsevol moment; deixa de funcionar de seguida.

L'endpoint públic és la manera més ràpida de provar l'API o de generar QR simples des d'un script sense gestionar autenticació:

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

Paràmetres:

- `value` (obligatori): el contingut del QR. Pot ser una URL, text, email, dades WiFi...
• `format`: `"png"` (per defecte) o `"svg"`
• `size`: `256`, `512` (per defecte) o `1024`

Si superes 50 peticions al dia, reps `429 RATE_LIMITED` amb el header `Retry-After`.

Un QR dinàmic codifica una URL curta fixa (`/r/{slug}`) però el seu destí final es pot canviar quan vulguis. El codi imprès no canvia mai.

Crear un QR dinàmic:

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

Canviar el destí sense reimprimir:

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

L'API serveix quan el volum o l'automatització fan inviable generar QR a mà des del panell.

Comerç electrònic: El sistema ERP genera un QR per albarà amb l'enllaç de seguiment. Si la URL canvia, `PATCH` actualitza el destí sense reimprimir res.

Restaurants: El TPV crea un QR per taula en obrir el torn. El cuiner actualitza la carta al CMS; el QR redirigeix sempre a la versió actual.

Esdeveniments: El sistema de ticketing genera un QR únic per entrada. A la porta, l'escàner verifica el QR via l'API.

Logística: Cada paquet porta un QR que apunta a la seva pàgina de seguiment. Els escanejos queden a `GET /api/v1/qr/{id}/stats`.

Tier pública: 50 peticions per dia per IP, finestra de 24 hores, sense registre.

Tier Pro: 60 peticions per minut per usuari, sense límit diari total.

Si superes el límit, l'API retorna `429` amb les capcaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining` i `Retry-After`.

Ves a la documentació completa de l'API per a tots els paràmetres.