La API

La API la sirve el mismo Cloudflare Worker que resuelve tus enlaces, en el origen de Kilo QR. Hoy eso significa que las peticiones van a qr2r.com bajo el prefijo /api:

https://qr2r.com/api

Cada ruta de estas guías es relativa a esa base - /links significa https://qr2r.com/api/links. Una forma rápida de confirmar que una clave funciona es la raíz de la API, que devuelve tu identidad:

{ "api": "qr2r", "version": 0, "user": { "uid": 42, "email": "", "admin": false } }

Envía tu clave como token bearer en la cabecera Authorization. La clave se comprueba antes que la cookie de sesión, así que un cliente de API se queda en un solo modo de autenticación sin que se cuele una cookie de navegador caduca.

Authorization: Bearer qr2r_live_1a2b3c…

Las claves empiezan por qr2r_live_ (o qr2r_test_ para una clave en modo de desarrollo). Ese prefijo qr2r_ es un identificador de infraestructura que deliberadamente no se rebautizó - la misma razón por la que el dominio sigue siendo qr2r.com. Generas una clave en el panel, bajo API keys; el token completo se muestra una sola vez en la creación, y Kilo guarda solo su hash SHA-256, así que ponla directamente en un gestor de secretos. Una petición sin clave válida (y sin sesión) se rechaza:

{ "error": "unauthorized" }

Una clave lleva uno o ambos de dos ámbitos. Una clave de lectura solo puede llamar a métodos seguros - GET, HEAD, OPTIONS. Una clave de escritura tiene permitidos además POST, PUT, PATCH y DELETE. Un intento de escritura con una clave de solo lectura se rechaza:

{ "error": "insufficient_scope", "required": "write" }

Los ámbitos son toda la historia de permisos de una clave: una clave puede gestionar enlaces, reglas y leer analítica, pero nunca puede gestionar miembros, facturación ni otras claves - esas acciones quedan ligadas a una sesión interactiva. Dale a una integración una clave de lectura cuando lo único que hace es extraer números.

Cada respuesta de error es un objeto JSON con una cadena error, más campos extra donde ayudan. Los fallos de validación llevan la lista completa de problemas bajo issues:

{ "error": "invalid_body", "issues": [ /* zod issues */ ] }

Los códigos que más te encontrarás:

• 400 invalid_body - el cuerpo de la petición no pasó la validación.
• 401 unauthorized - clave ausente o inválida.
• 402 plan_required - la función necesita un plan superior (lleva feature).
• 403 insufficient_scope / forbidden - la clave no puede realizar este método o acción.
• 404 not_found - no existe tal enlace, regla o dominio en tu espacio de trabajo.
• 409 - un conflicto, como name_taken o cap_reached.
• 422 destination_unsafe - el destino no pasó la comprobación de seguridad.
• 429 rate_limited - demasiadas peticiones (ver abajo).

Las peticiones autenticadas tienen límite de tasa. El cubo general permite 60 peticiones por minuto por usuario. Además, una clave de API tiene su propio techo por clave y por minuto tomado del límite api_rpm de tu plan. Supera cualquiera y la respuesta es:

{ "error": "rate_limited", "retry_after": 42 }

El valor retry_after (enviado también como cabecera Retry-After) es el número de segundos hasta que se reinicia la ventana. Espera ese tiempo y reintenta.

Con una clave en la mano, la siguiente guía recorre los endpoints de enlaces una llamada a la vez.