API REST

Gestiona tus enlaces y consulta analytics desde tus propios sistemas. La API está incluida en todos los planes — lo que escala con el plan son los límites de volumen y de peticiones.

Autenticación

Crea una API key en Ajustes → API de tu cuenta y envíala en cada petición. La key determina tu organización: solo ves y modificas tus enlaces.

Authorization: Bearer qr_live_xxxxxxxxxxxxxxxx

URL base: https://qr-top.com/api/v1 — respuestas en JSON, envueltas en { "data": … }; los errores devuelven { "error": "mensaje" } con su código HTTP.

Endpoints

Método y ruta	Qué hace
GET /links	Lista los enlaces con contador de escaneos
POST /links	Crea un enlace (destinationUrl obligatorio; title, slug, routingRules, expiresAt*, expiredUrl, utmParams opcionales)
GET /links/:id	Detalle de un enlace
PATCH /links/:id	Actualiza destino, título, estado o smart routing*
DELETE /links/:id	Elimina el enlace y sus escaneos (irreversible)
GET /links/:id/stats	Analytics: totales, hoy, 7 días, dispositivos y serie diaria
GET /me	Organización, plan, uso frente a límites y features

* Slug personalizado y smart routing (reglas por dispositivo/idioma/país/horario, A/B, límite de escaneos, expiración) requieren plan Pro o superior. El campo backupUrl (salvaguarda 404: monitorizamos tu destino y conmutamos al respaldo si cae, con aviso por email) requiere Business. Fuera de plan devuelven 403 con un mensaje claro.

Ejemplo: crear un enlace con regla horaria

Terminal

curl -X POST https://qr-top.com/api/v1/links \
  -H "Authorization: Bearer qr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://ejemplo.com/carta",
    "title": "Carta del restaurante",
    "routingRules": [
      { "hours": { "from": "08:00", "to": "12:00", "tz": "Europe/Madrid" },
        "to": "https://ejemplo.com/desayunos" }
    ]
  }'

Límites de peticiones

Por organización y minuto, con ventana deslizante: 30 en Free, 100 en Pro y Business. Al superarlo recibirás un 429 con cabeceras X-RateLimit-*; reintenta con backoff. Los escaneos de tus QRs no consumen este límite — son ilimitados en todos los planes.

Webhooks de escaneo (Business)

Configura una URL en Ajustes → API y cada escaneo registrado enviará un POST JSON en tiempo real — ideal para Zapier, Make, n8n o tu propio backend. El body va firmado con HMAC-SHA256 en la cabecera X-QRTop-Signature para que verifiques la autenticidad. Sin reintentos: si tu receptor no responde, el evento se pierde (los datos siguen en Analytics).

Payload

{
  "event": "scan",
  "link": { "id": "k3j2h1g4f5d6", "slug": "promo", "shortUrl": "https://q-r.top/promo" },
  "scan": {
    "scannedAt": "2026-07-25T12:34:56.000Z",
    "country": "ES", "city": "Madrid", "region": "MD",
    "deviceType": "mobile", "referer": null
  }
}

Verificación

// Verificación de la firma (Node.js)
const crypto = require("crypto");
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.QRTOP_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const valid = expected === req.headers["x-qrtop-signature"];

Códigos de estado

Código	Significado
200 / 201	OK / recurso creado
400	Petición inválida (URL no http/https, regla mal formada…)
401	API key ausente, inválida o caducada
403	Función o límite no incluido en tu plan
404	El recurso no existe o no es de tu organización
409	Slug ya en uso
429	Rate limit superado

¿Prefieres no escribir código? Conecta tu asistente de IA por MCP y pídeselo con palabras.

Guía del conector MCP →