Referencia para desarrolladores

Integra QR dinámicos sin fricción.

Crea, consulta y administra recursos QR desde tu servidor. Cada creación entrega una URL pública estable, PNG y SVG; las ediciones y descargas no consumen cuota.

Base URLhttps://qrfolio.link/api/v1

Autenticación

Todas las solicitudes usan una API key mediante Bearer Authentication. Crea llaves independientes por aplicación desde tu panel.

Abre /app/api, asigna un nombre y selecciona los permisos necesarios.

Copia el secreto qrf_live_…. Solo se muestra una vez.

Guárdalo en un administrador de secretos y envíalo en cada solicitud.

bash

curl 'https://qrfolio.link/api/v1/qrs' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE'

qrs:read

Listar, consultar y descargar PNG/SVG.

qrs:write

Crear, editar, activar y desactivar recursos.

No expongas la llaveÚsala únicamente en backend. Nunca la incluyas en JavaScript del navegador, repositorios o aplicaciones distribuidas.

Rotación y revocaciónUsa Rotar en el panel API para generar un secreto nuevo cuando renueves credenciales o sospeches una exposición. El secreto anterior deja de funcionar inmediatamente y el nuevo se muestra una sola vez; la llave conserva su nombre, permisos, vencimiento e historial. Usa Revocar para deshabilitarla permanentemente. Las llaves revocadas o expiradas no pueden rotarse.

Cuotas, límites e idempotencia

La cuota API es independiente de los créditos web. Solo crear un QR consume una unidad.

Cuota mensual

Crear consume cuota; leer, editar, activar y descargar no. Los planes ilimitados siguen registrando uso.

Rate limit

Todas las operaciones cuentan para el límite por minuto, calculado individualmente por API key.

Idempotencia

Cada POST requiere una Idempotency-Key. Repetirla con el mismo payload devuelve el recurso original.

Enlaces estables

Cancelar el acceso bloquea operaciones API, pero no elimina los enlaces públicos ya creados.

Oferta privada

Un administrador puede asignarte un plan Stripe no publicado. Solo aparecerá en tu panel y no habilitará acceso hasta que completes Checkout.

Tipos de QR

El campo payload depende de type. No se admiten propiedades adicionales. Las URLs deben ser públicas y usar HTTP o HTTPS.

bank

json

{
  "title": "Cuenta principal",
  "type": "bank",
  "payload": {
    "beneficiary": "Ana Martínez",
    "bank": "BBVA",
    "clabe": "032180000118359719",
    "account": "0123456789"
  }
}

redirect

json

{
  "title": "Catálogo",
  "type": "redirect",
  "payload": {
    "url": "https://example.com/catalogo"
  }
}

content

json

{
  "title": "Horarios",
  "type": "content",
  "payload": {
    "text": "Lunes a viernes de 9:00 a 18:00"
  }
}

json

{
  "title": "Soporte",
  "type": "whatsapp",
  "payload": {
    "phone": "+525512345678",
    "message": "Hola, necesito información"
  }
}

vcard

json

{
  "title": "Contacto comercial",
  "type": "vcard",
  "payload": {
    "fullName": "Ana Martínez",
    "jobTitle": "Directora comercial",
    "company": "Empresa Demo",
    "phones": [
      "+525512345678"
    ],
    "email": "[email protected]",
    "website": "https://example.com"
  }
}

links

json

{
  "title": "Mis enlaces",
  "type": "links",
  "payload": {
    "links": [
      {
        "label": "Sitio oficial",
        "url": "https://example.com"
      },
      {
        "label": "Instagram",
        "url": "https://instagram.com/example"
      }
    ]
  }
}

Listar recursos

GET/qrs?page=1&pageSize=20qrs:read

Lista exclusivamente QR creados por la API. pageSize admite de 1 a 100.

bash

curl 'https://qrfolio.link/api/v1/qrs?page=1&pageSize=20' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE'

json

{
  "items": [{ "id": "8a70…", "title": "Catálogo", "type": "redirect", "version": 1,
    "active": true, "url": "https://qrfolio.link/q/…", "image_png_url": "https://qrfolio.link/api/v1/qrs/8a70…/image.png" }],
  "total": 1, "page": 1, "pageSize": 20, "pages": 1
}

Crear un QR

POST/qrsqrs:write

Envía un tipo habilitado y su payload. La respuesta incluye consumo de cuota, URL pública y descargas.

bash

curl -X POST 'https://qrfolio.link/api/v1/qrs' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE' \
+  -H 'Idempotency-Key: pedido-8472' \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"Catálogo","type":"redirect","payload":{"url":"https://example.com/catalogo"}}'

json

{
  "id": "8a70a917-…", "slug": "c12f…", "type": "redirect", "title": "Catálogo",
  "payload": { "url": "https://example.com/catalogo" }, "version": 1, "active": true,
  "url": "https://qrfolio.link/q/c12f…",
  "image_png_url": "https://qrfolio.link/api/v1/qrs/8a70a917-…/image.png",
  "image_svg_url": "https://qrfolio.link/api/v1/qrs/8a70a917-…/image.svg",
  "quota": { "quota": 1000, "used": 24, "periodEnd": "2026-11-01T00:00:00.000Z", "unlimited": false }
}

Consultar un QR

GET/qrs/{id}qrs:read

Obtén el payload normalizado, estado actual, versión y URLs del recurso.

bash

curl 'https://qrfolio.link/api/v1/qrs/ID_DEL_QR' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE'

Editar un QR

PATCH/qrs/{id}qrs:write

Conserva el tipo original y envía la versión más reciente. Una edición exitosa incrementa version; no consume cuota.

bash

curl -X PATCH 'https://qrfolio.link/api/v1/qrs/ID_DEL_QR' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE' \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"Catálogo actualizado","payload":{"url":"https://example.com/nuevo"},"version":1}'

Control de concurrenciaSi otra operación ya modificó el QR, recibirás 409. Consulta el recurso otra vez y reintenta con su nueva versión.

Activar o desactivar

PATCH/qrs/{id}/activeqrs:write

Un recurso desactivado conserva sus datos, pero su URL pública deja de resolver hasta reactivarlo.

bash

curl -X PATCH 'https://qrfolio.link/api/v1/qrs/ID_DEL_QR/active' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE' \
+  -H 'Content-Type: application/json' \
+  -d '{"active":false}'

Descargar PNG y SVG

Las descargas requieren qrs:read, cuentan para el rate limit y no consumen cuota.

GET/qrs/{id}/image.pngqrs:read

bash

curl 'https://qrfolio.link/api/v1/qrs/ID_DEL_QR/image.png' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE' \
+  --output qr.png

GET/qrs/{id}/image.svgqrs:read

bash

curl 'https://qrfolio.link/api/v1/qrs/ID_DEL_QR/image.svg' \
+  -H 'Authorization: Bearer qrf_live_TU_LLAVE' \
+  --output qr.svg

Respuestas y errores

Los errores usan respuestas JSON de NestJS con un código HTTP y un mensaje legible.

400

Campos, payload, URL o Idempotency-Key inválidos.

401

Llave ausente, inválida, expirada o revocada.

403

Scope insuficiente, cuenta bloqueada o acceso API inactivo.

404

El recurso no existe o pertenece a otra cuenta.

409

Versión obsoleta o clave de idempotencia reutilizada con otros datos.

429

Cuota de creación agotada o demasiadas solicitudes por minuto.

json

{
  "statusCode": 409,
  "message": "El QR cambió. Consulta la versión actual antes de editarlo",
  "error": "Conflict"
}