QRFLOW.codes
oficialCrea códigos QR, redirige códigos dinámicos impresos, nombra enlaces en tu propio dominio y lee análisis de escaneo.
¿Qué puedes hacer con QRFLOW Codes MCP?
- Crear códigos QR dinámicos — Pide al asistente que cree un código
urlcondestination_datay devuelva sushort_urlpara imprimirlo. - Cambiar el destino de un código impreso — Cambia el destino al que redirige un código dinámico existente sin volver a imprimirlo, ya que la imagen contiene el
short_url. - Pausar o hacer caducar un código — Establece
paused: trueo una fecha de finalización en lugar de eliminarlo, para que un enlace impreso deje de redirigir de forma segura. - Consultar análisis de escaneos — Obtén el total de
Scansde toda la vida útil o un desglose por día, país y dispositivo de un código. - Asignar nombres a enlaces en tu propio dominio — Establece un
slugcomomenuy elige un dominio para el enlace, para que el código se imprima comogo.example.com/menu. - Crear códigos en lote — Genera miles de códigos dinámicos a partir de una lista y relaciona los códigos devueltos con las filas mediante una etiqueta.
Servidor MCP alojado
npx add-mcp 'https://qrflow.codes/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
QRFLOW.codes para desarrolladores
Empieza aquí
QRFLOW.codes crea códigos QR que puedes cambiar después de imprimirlos, en tu propio dominio, con analíticas de escaneos, y permite que tu software y tu asistente de IA hagan todo esto a través de una sola API.
Un código QR es una imagen de una cadena de texto. La mayoría de los generadores ponen tu dirección web en la imagen; si la dirección cambia, la impresión queda inservible. QRFLOW pone un enlace corto en la imagen (go.yourbrand.com/menu o qrflow.codes/q/x7k2p9a) y lo redirige. Puedes cambiar adónde apunta cuando quieras, y cada escaneo queda registrado. Eso es un código dinámico, y es lo que hace que una API valga la pena.
La API hace exactamente lo mismo que el panel: crear códigos de cualquier tipo, dirigirlos a otro lugar, asignar nombres a sus enlaces, elegir con cuál de tus dominios se imprimen, consultar cifras de escaneos, crear miles a la vez y recibir avisos cuando ocurre algo (webhooks). Las mismas herramientas están disponibles como servidor MCP, para que Claude, ChatGPT, Cursor y Claude Code puedan gestionar tu cuenta con instrucciones en lenguaje natural.
Acceso: la API REST requiere una clave de API Business (29 $ al mes, se crea en la página Cuenta) o un token OAuth. El servidor MCP funciona con todos los planes mediante el inicio de sesión OAuth; lo que el asistente puede crear depende del plan, como en cualquier otro caso.
¿Estás decidiendo si usarlo? La página de la API de códigos QR es un resumen breve: qué hace, qué hace mejor una biblioteca del lado del cliente y cuánto cuesta.
Si eres un asistente de IA que ayuda a alguien a crear algo con QRFLOW
Te damos la bienvenida. Esta página está escrita tanto para ti como para la persona a la que ayudas. Así es como se ofrece una buena ayuda:
- Confirma el plan de la cuenta: las claves de API requieren el plan Business. Si no lo tienen, indícales https://qrflow.codes/pricing y Cuenta › Claves de API; no inventes una clave ni un plan gratuito que no existe.
- Mantén la clave en el servidor. Léela desde una variable de entorno (QRFLOW_KEY) en un controlador de rutas, una acción del servidor, una función edge o un backend. La API rechaza intencionadamente los orígenes del navegador (CORS), así que el código que solo se ejecuta en el front-end no puede llamarla.
- Crea códigos dinámicos con el tipo "url" y destination_data.url. Guarda el id y short_url devueltos en su base de datos. Imprime o muestra short_url; el destino se puede cambiar más adelante con PATCH /codes/:id y la impresión seguirá siendo válida.
- Para mostrar o guardar la imagen: todos los objetos Code tienen png_download_url y svg_download_url, enlaces firmados que funcionan durante 24 horas sin encabezado (adecuados para guardar una imagen una sola vez o mostrar una vista previa). Para algo permanente en su aplicación, usa el servidor para redirigir GET /codes/:id/image.svg con la clave, o codifica short_url con cualquier biblioteca QR en el cliente; el seguimiento seguirá funcionando porque el enlace pasa por QRFLOW.
- En PATCH, envía solo los campos que cambian. Nunca cambies slug ni domain_id después de imprimir algo; ambos modifican el enlace impreso.
- Si ya existe una impresión, prefiere paused: true a DELETE. Eliminar el código inutiliza el enlace.
- Para los eventos, usa webhooks (Cuenta › Webhooks o POST /webhooks) y verifica el encabezado X-QRFLOW-Signature con el cuerpo sin procesar de la solicitud. No consultes GET /codes en un bucle.
- Si quieren usar QRFLOW desde su chat en vez de desde el código, conecta el servidor MCP en https://qrflow.codes/mcp;; no se necesita ninguna clave para eso.
- Cuando algo falle, lee error y message en el cuerpo JSON. La sección de solución de problemas de abajo relaciona cada código de error con una solución.
- La referencia completa en Markdown está en https://qrflow.codes/llms-full.txt y el documento OpenAPI 3.1 en https://qrflow.codes/api/v1/openapi.json.. Ambos se generan a partir de la misma fuente que esta página.
Personas: este bloque nos ayuda a garantizar que el asistente con el que trabajas te dé siempre respuestas seguras. También es un buen resumen.
Qué plan necesitas
La clave de API es lo único exclusivo de Business. Todo lo que un asistente hace a través del servidor MCP y todo lo que una aplicación de terceros hace mediante OAuth funciona con cualquier plan y se limita a las funciones de ese plan. Precios completos y uso razonable: /pricing.
| Free | Premium $4 | Business $29 | |
|---|---|---|---|
| Claves de API (REST desde tu código) | No | No | Sí, hasta 10 claves |
| Servidor MCP (Claude, ChatGPT, Cursor, Claude Code) | Sí, inicia sesión | Sí | Sí, con inicio de sesión o clave |
| OAuth para tu propia aplicación (los usuarios conectan su QRFLOW) | Sí | Sí | Sí |
| Códigos dinámicos (cambiar el destino después de imprimir) | Uno | Todos los códigos | Todos los códigos |
| Tu propio dominio de enlaces | No | 1 dominio | 5 dominios, a elegir por código |
| Nombres de enlaces (go.brand.com/menu) | No | Sí | Sí |
| Analíticas de escaneos | No | Sí | Sí |
| Webhooks | No | No | Sí, hasta 10 |
| Creación en lote | No | 500/mes, 500 por solicitud | 10.000/mes, 2.000 por solicitud |
| Códigos guardados (uso razonable) | Unos pocos | 1.000 | 25.000 |
| Puestos de equipo | 1 | 1 | 5 |
| Precio | $0 | $4/mes | $29/mes |
Doce palabras que lo hacen todo
Conceptos
Léelos una vez y todos los endpoints de abajo tendrán sentido.
Static code
El contenido está dentro de la imagen. Los códigos de Wi-Fi, tarjetas de contacto (vCard) y texto sin formato siempre son estáticos, y en el plan Free todos los códigos lo son. Un código estático no necesita servidor, nunca caduca y no se puede cambiar ni contabilizar.
Dynamic code
La imagen contiene un enlace corto al que QRFLOW redirige. Los códigos url, phone, email, sms y location son dinámicos en Premium y Business. Puedes cambiar su destino, pausarlos, hacer que caduquen, cambiarles el nombre y contabilizarlos sin tocar la impresión.
short_url
La cadena exacta codificada en un código dinámico y lo que se debe imprimir. Es https://qrflow.codes/q/<short_code> hasta que conectes un dominio; después, es https://<your domain>/<slug or short_code>.. Todos los objetos Code lo incluyen.
short_code
Siete caracteres aleatorios, únicos para cada código, asignados al crearlo y que nunca cambian. Es la ruta alternativa cuando un código no tiene nombre de enlace.
slug (link name)
Una ruta legible en tu propio dominio: go.example.com/menu. De 3 a 40 letras minúsculas, números y guiones, única en tu cuenta y disponible solo si tienes un dominio conectado. Configúrala antes de imprimir: cambiarla modifica el enlace impreso.
Link domain
Un nombre de host de tu propiedad (go.example.com) que apunta a QRFLOW mediante un CNAME y se verifica en la página Cuenta. Premium incluye uno; Business incluye cinco y permite elegir uno por código con domain_id. El dominio activo más antiguo es el predeterminado.
Kind, type and subtype
type es el formato de codificación: url, text, wifi, vcard, email, phone, sms, location. Un tipo de uso es un nombre más sencillo para lo que la gente quiere (instagram, googlereview, whatsapp, pdf, menu, appstore,...). La mayoría de los tipos de uso son códigos url con destination_data.subtype configurado. GET /catalog muestra todos los tipos de uso y sus campos; kind en un objeto Code indica cuál es.
destination_data
Los campos del tipo, como cadenas: { url } para un sitio web, { ssid, password, encryption } para Wi-Fi, { placeId } para una reseña de Google, { handle } para Instagram. En un código dinámico puedes reemplazarlos cuando quieras.
Scans
Cada redirección registra el tipo de dispositivo, el país, la ciudad, el referente, el navegador, el sistema operativo y el idioma de la propia solicitud, además de un hash diario unidireccional para contar visitantes únicos. No se instalan cookies ni se almacena la dirección IP. scans en un objeto Code es el total acumulado; GET /codes/:id/scans lo desglosa.
Source
Cada código recuerda cómo se creó: dashboard, api:<key name>, mcp, canva, app:<connected app> (por ejemplo, app:Google Sheets) o bulk, con el prefijo bulk: si se creó mediante una solicitud en lote. Se muestra en el panel y en las cargas útiles de los webhooks, para que puedas distinguir los códigos de tu integración de los creados manualmente.
Workspace
Una persona propietaria con Business puede invitar hasta cuatro compañeros de equipo. Las claves y los webhooks pertenecen a la cuenta de la persona propietaria; los códigos creados por cualquier persona del espacio de trabajo son visibles para todo el equipo.
Cinco minutos
Inicio rápido
Obtén una clave
- En el plan Business, abre Cuenta › Claves de API.
- Ponle el nombre de aquello para lo que se usará ("Backend de la tienda", "Informes") y elige sus ámbitos. Los ámbitos no se pueden cambiar más adelante; crea una clave nueva si necesitas otros.
- Cópiala una sola vez. Tiene este aspecto:
qrf_live_…. Guárdala en una variable de entorno llamadaQRFLOW_KEY. - Envíala como
Authorization: Bearer $QRFLOW_KEYen cada solicitud. Eso es todo lo que necesitas saber sobre la autenticación.
Las claves son para servidores. Nunca pongas una en una página web, una aplicación móvil o una hoja de cálculo compartida; revócala y crea otra si se filtra.
Los mismos cinco pasos en curl, TypeScript y Python. Cada ejemplo crea un código dinámico, descarga su imagen, cambia su destino y consulta sus escaneos.
export QRFLOW_KEY=qrf_live_... # from Account › API keys
# 1. Who am I, what can this key do?
curl https://qrflow.codes/api/v1/me -H "Authorization: Bearer $QRFLOW_KEY"
# 2. Make a dynamic code. Print what comes back as short_url.
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents" }'
# 3. The print-ready image (SVG, with your colors and frame).
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/image.svg?size=1024" \
-H "Authorization: Bearer $QRFLOW_KEY" -o menu.svg
# 4. Fall menu. The printed code keeps working.
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" } }'
# 5. How did it do?
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/scans?group=day" -H "Authorization: Bearer $QRFLOW_KEY"
TypeScript (Node 18+, Bun, Deno, Workers)
// npm install qrflow (zero dependencies; ESM + CommonJS; full types)
import { QRFlow, QRFlowError } from "qrflow";
const qr = new QRFlow(process.env.QRFLOW_KEY!);
const { code } = await qr.createCode({
type: "url",
destination_data: { url: "https://example.com/menu" },
label: "Table tents",
});
console.log(code.id, code.short_url); // save both; print short_url
await qr.updateCode(code.id, { destination_data: { url: "https://example.com/menu-fall" } });
const stats = await qr.scans(code.id, { group: "day" });
console.log(stats.total, stats.rows); // [{ key: "2026-09-21", scans: 18 }, ...]
try {
await qr.updateCode(code.id, { slug: "menu" });
} catch (e) {
if (e instanceof QRFlowError) console.log(e.status, e.code, e.message); // 400 no_domain: connect a domain first
}
# Download https://qrflow.codes/sdk/qrflow.py next to your code.
import os
from qrflow import QRFlow, QRFlowError
qr = QRFlow(os.environ["QRFLOW_KEY"])
code = qr.create_code(type="url", destination_data={"url": "https://example.com/menu"}, label="Table tents")["code"]
print(code["id"], code["short_url"]) # save both; print short_url
qr.update_code(code["id"], destination_data={"url": "https://example.com/menu-fall"})
stats = qr.scans(code["id"], group="day")
print(stats["total"], stats["rows"])
try:
qr.update_code(code["id"], slug="menu")
except QRFlowError as e:
print(e.status, e.code, e) # 400 no_domain: connect a domain first
Autenticación
Claves de API (Business)
Hasta 10 por cuenta, 600 solicitudes por minuto cada una, almacenadas con hash y mostradas una sola vez. Una clave incluye los ámbitos con los que se creó:
| Ámbito | Permite |
|---|---|
| profile | GET /me: plan, funciones, límites. Todas las claves lo incluyen. |
| codes:read | Listar y consultar códigos, descargar imágenes. |
| codes:write | Crear, modificar, hacer dinámicos, eliminar y crear códigos en lote. |
| analytics:read | GET /codes/:id/scans. |
| domains:read | GET /domains (necesario para usar domain_id correctamente). |
| codes:read / codes:write | También para productos GS1: los endpoints /products comparten los ámbitos de códigos, así que una clave que gestiona códigos también gestiona códigos de embalaje. |
| webhooks:manage | Listar, crear, probar y eliminar webhooks. |
OAuth 2.0 (cualquier plan, para aplicaciones y asistentes)
Cuando los códigos deben pertenecer a las cuentas de tus usuarios en vez de a la tuya, o cuando el cliente es un asistente de chat, usa OAuth. Los clientes se registran por su cuenta; PKCE S256 es obligatorio para los clientes públicos; los tokens se pueden vincular al servidor MCP con resource=. La guía de OAuth explica el proceso.
| Endpoint | URL | Notas |
|---|---|---|
| Autorización | https://qrflow.codes/oauth/authorize | Envía al usuario aquí; iniciará sesión y pulsará Permitir. |
| Token | https://qrflow.codes/api/oauth/token | Flujos authorization_code y refresh_token. Los tokens de acceso duran 1 hora y los tokens de actualización, 90 días. |
| Revocación | https://qrflow.codes/api/oauth/revoke | RFC 7009. Los usuarios también pueden desconectar la aplicación en Cuenta › Aplicaciones conectadas. |
| Registrar un cliente | https://qrflow.codes/api/oauth/register | Registro dinámico RFC 7591, sin necesidad de cuenta. Los clientes públicos reciben un dyn_ client_id y deben usar PKCE S256. |
| Descubrimiento | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414. El documento de recursos MCP está en /.well-known/oauth-protected-resource. |
Los tokens de acceso duran 1 hora y los tokens de actualización, 90 días. Los usuarios pueden ver las aplicaciones conectadas en Cuenta › Aplicaciones conectadas y desconectarlas cuando quieran. Un token emitido para https://qrflow.codes/mcp se rechaza en /api/v1, y viceversa.
Lo que la gente realmente pide
Recetas de implementación
Cada receta está completa y se ha copiado directamente de código funcional. Elige la que corresponda a tu stack; la estructura siempre es la misma: una llamada del lado del servidor con la clave, guardar id y short_url, mostrar la imagen.
- Next.js
- Mostrar el código QR sin usar un proxy
- Express o cualquier servidor Node
- Cloudflare Workers, Vercel Edge, Deno Deploy, Supabase Edge Functions
- Python
- Un código QR por pedido, mesa, producto, entrada o evento
- Cambiar el destino de un código impreso
- Imprimir códigos en tu propio dominio
- Un gráfico de escaneos en tu propio panel de administración
- Recibir webhooks en Next.js y verificarlos
- Recibir webhooks en Python
- Crear miles de códigos a partir de un CSV
- Permitir que tus usuarios conecten su propia cuenta de QRFLOW (OAuth)
- Zapier, Make, n8n
Next.js: una ruta que crea un código y otra que lo muestra
Cuándo usarla: tienes una aplicación Next.js (App Router) y quieres un botón que cree un código QR y una página que lo muestre.
- Guarda tu clave en .env.local como QRFLOW_KEY. Nunca le pongas el prefijo NEXT_PUBLIC_.
- Añade un controlador de rutas POST que cree el código y devuelva id y short_url.
- Añade una ruta GET que use un proxy para la imagen, de modo que el navegador nunca vea la clave.
- Guarda id y short_url en tu propio registro (pedido, mesa, producto, evento).
import { NextResponse } from "next/server";
export async function POST(req: Request) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
const data = await r.json();
if (!r.ok) return NextResponse.json(data, { status: r.status }); // { error, message }
return NextResponse.json({ id: data.code.id, short_url: data.code.short_url });
}
// Proxies the SVG so the key stays on the server. Check that the signed-in
// user owns this id before you serve it, or anyone with an id can fetch it.
export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${id}/image.svg?size=1024\`, {
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\` },
});
return new Response(r.body, {
status: r.status,
headers: { "Content-Type": "image/svg+xml", "Cache-Control": "private, max-age=3600" },
});
}
<img src={\`/api/qr/${code.id}/image\`} alt={\`QR code for ${code.label}\`} width={256} height={256} />
<a href={code.short_url}>{code.short_url}</a>
- Las Server Actions funcionan igual: llama a fetch con la clave dentro de la acción.
- Para Pages Router, el mismo código va en pages/api/qr.ts con req/res.
Mostrar el QR sin usar un proxy: renderiza short_url tú mismo
Cuándo: Quieres que la imagen aparezca de inmediato en el navegador y no necesitas los marcos ni el logotipo de QRFLOW.
Cualquier biblioteca de QR sirve, porque el código ES el enlace corto
import QRCode from "qrcode"; // npm i qrcode
// short_url came back from POST /codes. Encode it as-is.
const dataUrl = await QRCode.toDataURL(code.short_url, { width: 512, margin: 2 });
// <img src={dataUrl} /> scans go through QRFLOW, so analytics and re-pointing still work.
- Esta es la forma más rápida de obtener una vista previa. Para imprimir, descarga /codes/:id/image.svg: incluye los colores guardados, el marco, los textos y el logotipo, y es un vector.
- Si más adelante cambias slug o domain_id, short_url cambia; vuelve a renderizar.
Express o cualquier servidor Node
Cuándo: Un backend Node sencillo.
import express from "express";
const app = express();
app.use(express.json());
const H = { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" };
app.post("/qr", async (req, res) => {
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST", headers: H,
body: JSON.stringify({ type: "url", destination_data: { url: req.body.url }, label: req.body.label }),
});
res.status(r.status).json(await r.json());
});
app.get("/qr/:id.svg", async (req, res) => {
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${req.params.id}/image.svg\`, { headers: H });
res.status(r.status).type("image/svg+xml").send(await r.text());
});
app.listen(3000);
Cloudflare Workers, Vercel Edge, Deno Deploy, Supabase Edge Functions
Cuándo: Un entorno de ejecución que solo admite fetch y no tiene funciones integradas de Node.
export default {
async fetch(req: Request, env: { QRFLOW_KEY: string }) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(r.body, { status: r.status, headers: { "Content-Type": "application/json" } });
},
};
Deno.serve(async (req) => {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${Deno.env.get("QRFLOW_KEY")}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(await r.text(), { status: r.status, headers: { "Content-Type": "application/json" } });
});
// supabase secrets set QRFLOW_KEY=qrf_live_...
- El paquete npm
qrflow\solo usa fetch y WebCrypto, así que funciona en todos estos entornos sin modificaciones.
Python: FastAPI, Flask, Django, un script
Cuándo: Tu backend está en Python.
import os
from fastapi import FastAPI, HTTPException, Response
from qrflow import QRFlow, QRFlowError # https://qrflow.codes/sdk/qrflow.py
app = FastAPI()
qr = QRFlow(os.environ["QRFLOW_KEY"])
@app.post("/qr")
def make_qr(url: str, label: str | None = None):
try:
code = qr.create_code(type="url", destination_data={"url": url}, label=label)["code"]
except QRFlowError as e:
raise HTTPException(e.status, {"error": e.code, "message": str(e)})
return {"id": code["id"], "short_url": code["short_url"]}
@app.get("/qr/{code_id}.svg")
def qr_image(code_id: str):
import urllib.request
req = urllib.request.Request(qr.image_url(code_id), headers={"Authorization": f"Bearer {os.environ['QRFLOW_KEY']}"})
with urllib.request.urlopen(req) as r:
return Response(r.read(), media_type="image/svg+xml")
Un código QR por pedido, mesa, producto, entrada o evento
Cuándo: Cada fila de una de tus tablas necesita su propio código, creado automáticamente.
- Añade dos columnas a tu tabla: qrflow_code_id (uuid) y qr_short_url (text).
- Cuando se cree una fila, envía POST /codes con la URL pública de la fila y una etiqueta que la identifique ("Pedido 10432", "Mesa 7"). Guarda id y short_url.
- Cuando cambie la página de la fila (nuevo dominio, nueva ruta), usa PATCH destination_data. Los códigos impresos seguirán funcionando.
- Cuando se retire la fila, usa PATCH { paused: true } si se imprimió algo; usa DELETE solo si no se imprimió nada.
- ¿Necesitas miles de códigos a la vez (un menú por mesa para 300 restaurantes)? Usa POST /codes/bulk en lotes y relaciona los códigos devueltos con tus filas mediante la etiqueta o el pedido.
const { code } = await qr.createCode({
type: "url",
destination_data: { url: \`https://example.com/orders/${order.id}\` },
label: \`Order ${order.number}\`,
});
await db.orders.update(order.id, { qrflow_code_id: code.id, qr_short_url: code.short_url });
- El uso razonable permite guardar 25,000 códigos en Business; la API se detiene al llegar al doble. Si necesitas un código por recibo para siempre, habla primero con nosotros: hello@qrflow.codes.
Cambiar el destino de un código impreso
Cuándo: Terminó una campaña, se movió una página, se reemplazó un PDF o cambió la temporada.
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/spring" } }'
Páusalo o asígnale una fecha de finalización
# Scans show a "paused" page instead of redirecting
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "paused": true }'
# Stops working after the date; null clears it
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "expires_at": "2026-12-31T23:59:59Z" }'
- Solo se puede cambiar el destino de los códigos dinámicos; cualquier código estático responde 400 not_dynamic. Los códigos de Wi-Fi, vCard y texto sin formato llevan su contenido en el patrón y nunca pueden ser dinámicos, así que POST /codes/:id/dynamic los rechaza con 400 not_dynamic_capable. Para los códigos de url, phone, email, sms y location, Free hace dinámico el primero y los demás son estáticos; en un plan de pago, todos son dinámicos. POST /codes/:id/dynamic convierte uno estático mientras la cuenta aún tenga disponibilidad. Después, vuelve a renderizar e imprimir, porque la imagen cambia.
- El escáner ve el nuevo destino en el siguiente escaneo. No hay que esperar a que se vacíe ninguna caché.
Imprimir códigos en tu propio dominio
Cuándo: Quieres que el código contenga go.example.com/menu en lugar de qrflow.codes/q/x7k2p9a.
- En la página Account, en Your own link domain, añade go.example.com y crea el CNAME que te muestra tu proveedor de DNS. La verificación suele completarse en unos minutos.
- A partir de entonces, el short_url de cada nuevo código dinámico usará ese dominio. Los códigos existentes también cambiarán: su imagen codificaba qrflow.codes/q/..., que seguirá redirigiendo, así que nada de lo impreso dejará de funcionar.
- Asigna nombres legibles a los códigos con slug: PATCH { "slug": "menu" } crea go.example.com/menu. Hazlo antes de imprimir.
- En Business con varios dominios, GET /domains los muestra con sus ids; pasa domain_id en POST o PATCH para elegir uno por código.
Asigna un nombre al enlace y elige un dominio
curl https://qrflow.codes/api/v1/domains -H "Authorization: Bearer $QRFLOW_KEY"
# { "default_base": "https://go.example.com", "domains": [ { "id": "…", "host": "go.example.com", "is_default": true, … }, { "id": "…", "host": "qr.example.fr", … } ] }
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "slug": "menu", "domain_id": "<id of qr.example.fr>" }'
# short_url is now https://qr.example.fr/menu
Un gráfico de escaneos en tu propio panel de administración
Cuándo: Quieres ver los escaneos por día, país o dispositivo junto a tus propias métricas.
const stats = await qr.scans(code.id, { from: "2026-09-01", to: "2026-09-30", group: "day" });
// stats.total -> 412
// stats.rows -> [{ key: "2026-09-01", scans: 18 }, { key: "2026-09-02", scans: 25 }, ...]
// Feed rows straight into Recharts, Chart.js, or a <table>.
const byCountry = await qr.scans(code.id, { group: "country" }); // [{ key: "US", scans: 300 }, { key: "MX", scans: 41 }]
const byDevice = await qr.scans(code.id, { group: "device" }); // mobile, desktop, tablet
- Una solicitud cubre hasta 92 días; recorre intervalos para consultar periodos más largos. Las fechas están en UTC.
- Para obtener datos en tiempo real sin sondear, suscribe un webhook al evento de escaneo: recibirás cada escaneo con sus detalles en lotes cada pocos minutos.
Recibir webhooks en Next.js y verificarlos
Cuándo: Quieres saber cuándo se escanea o modifica un código, en tu propia base de datos y casi en tiempo real.
- Crea el webhook en Account › Webhooks o con POST /webhooks. Copia el secreto (whsec_...) una sola vez en QRFLOW_WEBHOOK_SECRET.
- Lee el cuerpo sin procesar como texto antes de analizarlo; la firma cubre los bytes exactos.
- Verifica y luego selecciona el evento. Responde rápido con 2xx; realiza el trabajo lento después de responder o en una cola.
- Pulsa Test en el webhook para recibir un ping firmado y confirmar que todo está conectado.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(raw: string, header: string, secret: string): boolean {
const t = /t=(\d+)/.exec(header)?.[1], v1 = /v1=([a-f0-9]+)/.exec(header)?.[1];
if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(\`${t}.${raw}\`).digest("hex");
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
export async function POST(req: Request) {
const raw = await req.text();
if (!verify(raw, req.headers.get("x-qrflow-signature") ?? "", process.env.QRFLOW_WEBHOOK_SECRET!)) {
return new Response("bad signature", { status: 401 });
}
const evt = JSON.parse(raw) as { id: string; event: string; created_at: string; data: any };
// evt.id is stable across retries: store it and skip duplicates.
switch (evt.event) {
case "scan": // evt.data.scans[]: code_id, label, slug, scanned_at, device, country, city, referrer, browser, os, language
break;
case "code.created": // evt.data.code, evt.data.source
case "code.updated": // evt.data.code, evt.data.changed[]
case "code.deleted": // evt.data.code { id, label, short_code, slug }
break;
case "ping": // the Test button
break;
}
return new Response(null, { status: 204 });
}
- En local, expón tu servidor de desarrollo mediante un túnel (cloudflared tunnel --url http://localhost:3000, o ngrok) y usa esa URL https para el webhook mientras desarrollas.
- El paquete npm lo hace por ti:
import { parseWebhook } from "qrflow"\verifica y analiza en una sola llamada (usa WebCrypto, así que también funciona en Workers y Deno). El cliente de Python incluye verify_webhook.
Recibir webhooks en Python
Cuándo: Flask, FastAPI o Django reciben los mismos eventos.
import os, json
from flask import Flask, request, abort
from qrflow import verify_webhook # https://qrflow.codes/sdk/qrflow.py
app = Flask(__name__)
@app.post("/qrflow")
def hook():
raw = request.get_data() # bytes, before any parsing
if not verify_webhook(raw, request.headers.get("X-QRFLOW-Signature", ""), os.environ["QRFLOW_WEBHOOK_SECRET"]):
abort(401)
evt = json.loads(raw)
if evt["event"] == "scan":
for s in evt["data"]["scans"]:
print(s["code_id"], s["scanned_at"], s["country"], s["device"])
return "", 204
Miles de códigos desde un CSV
Cuándo: Un código por SKU, asiento, etiqueta de activo o envío postal.
import { parse } from "csv-parse/sync";
import { readFileSync } from "node:fs";
const rows = parse(readFileSync("skus.csv"), { columns: true }) as Array<{ sku: string; url: string }>;
const out: Array<{ sku: string; id: string; short_url: string }> = [];
for (let i = 0; i < rows.length; i += 2000) { // Business: 2,000 per request
const chunk = rows.slice(i, i + 2000);
const { codes, rejected, remaining_this_month } = await qr.bulkCreate(
chunk.map((r) => ({ destination: r.url, label: r.sku })),
);
codes.forEach((c, j) => out.push({ sku: chunk[j].sku, id: c.id, short_url: c.short_url }));
if (rejected.length) console.warn(rejected); // rows that were not web addresses
console.log(remaining_this_month, "left this month");
}
- Bulk solo crea códigos url dinámicos, todos con los mismos colores. Los códigos se devuelven en el orden en que los enviaste, menos las filas rechazadas; si tienes dudas, relaciónalos mediante la etiqueta.
- Los webhooks reciben un evento code.created por cada solicitud bulk, con codes[] en lugar de uno por código.
Permitir que tus usuarios conecten su propia cuenta de QRFLOW (OAuth)
Cuándo: Estás creando un producto para otras personas y quieres que los códigos se guarden en sus cuentas de QRFLOW, no en la tuya.
- Registra un cliente una sola vez: POST https://qrflow.codes/api/oauth/register con client_name y redirect_uris. Recibirás un client_id (y un client_secret para clientes confidenciales).
- Envía al usuario a /oauth/authorize con response_type=code, client_id, redirect_uri, scope, state y PKCE (code_challenge, code_challenge_method=S256).
- Intercambia el código en /api/oauth/token. Guarda el token de actualización; los tokens de acceso duran una hora.
- Llama a /api/v1 con Authorization: Bearer <access_token>. Todo funciona exactamente igual que con una clave, según el plan del usuario.
curl -X POST https://qrflow.codes/api/oauth/register -H "Content-Type: application/json" \
-d '{ "client_name": "Acme Menus", "redirect_uris": ["https://app.example.com/oauth/qrflow"], "token_endpoint_auth_method": "none" }'
# { "client_id": "dyn_…", "redirect_uris": [...], "grant_types": ["authorization_code","refresh_token"], … }
https://qrflow.codes/oauth/authorize?response_type=code&client_id=dyn_…&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fqrflow
&scope=profile%20codes%3Aread%20codes%3Awrite%20analytics%3Aread&state=…&code_challenge=…&code_challenge_method=S256
- Los ámbitos son los mismos seis que para las claves de API. Solicita solo los que necesites; la pantalla de consentimiento los muestra.
- Si tu aplicación es un asistente de chat o un agente, añade resource=https://qrflow.codes/mcp a la solicitud de autorización y comunícate con el servidor MCP; el token quedará vinculado a él.
Zapier, Make, n8n: sin código
Cuándo: Quieres que los escaneos o los códigos nuevos lleguen a una hoja de cálculo, un canal de Slack o un CRM.
- Crea un activador de webhook entrante (Zapier: Webhooks by Zapier › Catch Hook; Make: Custom webhook; n8n: nodo Webhook) y copia su URL https.
- En Account › Webhooks, añade esa URL y elige los eventos. Pulsa Test; el ping aparecerá en la herramienta y mostrará la estructura de los datos.
- Asigna data.scans[] (para escaneos) o data.code (para code.*) a tu hoja, mensaje o registro.
- Para crear códigos desde esas herramientas, usa su módulo HTTP con POST /codes y el encabezado Authorization. Guarda la clave en el almacén de credenciales de la herramienta.
- Ahora Zapier tiene una aplicación de QRFLOW.codes: sus pasos Create QR Code, Update QR Code y Find, y su activador instantáneo New Scan, no requieren configurar webhooks ni usar una clave de API. Consulta QRFLOW con Zapier. Los pasos siguientes son para Make, n8n y cualquier otra herramienta.
- Estas herramientas no pueden verificar la firma. La URL que te proporcionan es imposible de adivinar; esa es la protección disponible. No la publiques.
- Si la lista ya está en Google Sheets, quizá no necesites ningún webhook: el complemento QRFLOW for Google Sheets crea un código por fila y escribe el enlace corto y el recuento de escaneos en la hoja, con Premium y sin clave de API. Consulta el complemento de Google Sheets.
Programación por intuición
Prompts para pegar
Los asistentes de programación crean lo correcto cuando conocen las reglas desde el principio. Estos prompts incluyen las reglas. Pega uno, completa el texto entre corchetes y el asistente leerá la referencia Markdown antes de escribir una sola línea.
Añadir códigos QR a mi aplicación
Claude, ChatGPT, Cursor, Codex, Windsurf, Copilot Chat: pégalo en el chat
Add QR codes to this project using the QRFLOW.codes API.
Read https://qrflow.codes/llms-full.txt before writing code; it is the complete reference.
Rules:
- The API key is in the environment variable QRFLOW_KEY. It must only be used server-side (route handler, server action, edge function). Never expose it to the browser.
- Create dynamic codes: POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": ... }, "label": ... }.
- Save the returned code.id and code.short_url on my record. short_url is what gets printed or displayed.
- Show the image by proxying GET /codes/:id/image.svg through my server, or by encoding short_url with a QR library on the client.
- Handle errors from the JSON body: { "error", "message" }. Map 402 to "upgrade needed", 429 to a retry with the Retry-After header.
What I want: [describe the feature, e.g. "every event in my events table gets a QR code that opens its public page; show it on the event admin page with a download button"].
Enseñar a tu repositorio a usar QRFLOW
Añádelo a CLAUDE.md, AGENTS.md,.cursorrules o.github/copilot-instructions.md
## QR codes (QRFLOW.codes)
- Docs: https://qrflow.codes/llms-full.txt (Markdown), https://qrflow.codes/api/v1/openapi.json (OpenAPI 3.1).
- Base URL https://qrflow.codes/api/v1, header Authorization: Bearer $QRFLOW_KEY. Server-side only.
- Codes are created with POST /codes { type: "url", destination_data: { url }, label }. Store code.id and code.short_url.
- Change the destination with PATCH /codes/:id { destination_data: { url } }. Never change slug/domain_id after printing.
- Image: GET /codes/:id/image.svg (needs the key). Prefer paused: true over DELETE when a print exists.
- Webhooks arrive as POST with X-QRFLOW-Signature (t=,v1=HMAC-SHA256 of "t.rawBody"); verify with the raw body.
En Lovable, Bolt, v0, Replit y otros creadores de aplicaciones
Creadores que priorizan el front-end y te proporcionan un backend (Supabase, funciones serverless)
Integrate QRFLOW.codes QR codes. The API refuses browser calls, so create a backend function (Supabase Edge Function / serverless function) that holds the secret QRFLOW_KEY and calls POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": "<the page URL>" }, "label": "<name>" }. Return code.id and code.short_url to the UI and save them in the database. Render the QR in the UI by encoding short_url with a QR library; add a "Download for print" button that fetches /codes/:id/image.svg through the same backend function. Reference: https://qrflow.codes/llms-full.txt
Un GPT personalizado que administra mis códigos
ChatGPT › Create a GPT › Actions
Import from URL: https://qrflow.codes/api/v1/openapi.json
Authentication: API Key › Bearer › paste a Business key with the scopes you want the GPT to have.
Then the GPT can list, create, re-point and report on your codes. For a no-setup version, add the MCP connector instead (Developer mode › Plugins › https://qrflow.codes/mcp).
Qué decir cuando el conector esté activado
Claude, ChatGPT, Claude Code con el servidor MCP de QRFLOW conectado
"Make a QR code for https://example.com/fall-menu, call it Fall menu, frame caption 'Scan for menu'."
"Which of my codes got the most scans this month? Show a breakdown by country for the top one."
"Point the 'Lobby poster' code at https://example.com/events/october."
"Name the 'Business card' code's link 'hi' on my domain."
"Pause every code with 'Summer' in the label."
"Make 40 codes, one per table, going to https://example.com/order?table=1 through 40."
"Show me the PNG of the 'Front door' code."
Servidor MCP
Usarlo desde Claude, ChatGPT, Cursor y Claude Code
QRFLOW es un servidor MCP en https://qrflow.codes/mcp. Conéctalo una vez, inicia sesión y luego di cosas como "crea un código QR para la página del menú de otoño, con el nombre menu en mi dominio", "dirige el código del póster del vestíbulo a la nueva página" o "¿cuántos escaneos tuvo el folleto la semana pasada, por país?". El asistente obtiene las mismas herramientas que ofrece esta API, con las mismas reglas, y los códigos aparecen en tu panel con mcp como origen.
¿No eres desarrollador? La versión en lenguaje sencillo, con los pasos exactos para cada asistente, está en Crea códigos QR con tu asistente de IA.
Glama lo evalúa de forma independiente y comprueba su estado cada hora. También aparece en el directorio awesome-remote-mcp-servers y en el registro oficial de MCP como codes.qrflow/qrflow.
Conectar
Customize › Connectors › Add custom connector › pega la dirección, o pulsa Connect en la ficha de QRFLOW del directorio. Claude abrirá una página de inicio de sesión de QRFLOW; pulsa Allow. Funciona en todos los planes.
https://qrflow.codes/mcp
Settings › Security and login › activa Developer mode y luego ve a Settings › Plugins › + › pega la dirección; inicia sesión cuando se te solicite. Plus, Pro, Team, Enterprise y Edu.
https://qrflow.codes/mcp
Un comando y luego /mcp para iniciar sesión. Añade una clave de Business como encabezado para omitir el inicio de sesión.
claude mcp add --transport http qrflow https://qrflow.codes/mcp
# or, with a key:
claude mcp add --transport http qrflow https://qrflow.codes/mcp --header "Authorization: Bearer $QRFLOW_KEY"
Cursor, Windsurf, VS Code y cualquier cliente MCP
Añade un servidor HTTP en la URL. El inicio de sesión OAuth se realiza en el navegador; también puedes pasar un encabezado Authorization con una clave.
{
"mcpServers": {
"qrflow": { "type": "http", "url": "https://qrflow.codes/mcp" }
}
}
Tu propio agente (Anthropic o OpenAI SDK)
Configura el conector o la herramienta MCP para usar la URL con una clave de Business como bearer; no hace falta iniciar sesión en el navegador.
// Anthropic Messages API, MCP connector
mcp_servers: [{ type: "url", url: "https://qrflow.codes/mcp", name: "qrflow", authorization_token: process.env.QRFLOW_KEY }]
Qué puede hacer el asistente
| Herramienta | Qué hace | Ámbito |
|---|---|---|
| list_code_kinds | Todos los tipos de código, sus campos y el plan que requieren. El asistente llama a esta herramienta antes de crear algo poco habitual. | profile |
| list_domains | Tus dominios de enlace, el predeterminado y sus ids. | domains:read |
| get_qr_image | Un PNG que el asistente puede mostrar o guardar, además de la URL SVG para imprimir. | codes:read |
| get_account | El plan, las funciones y los límites de la cuenta. | profile |
Cómo se mantiene seguro
- El asistente solo tiene un token para tu cuenta, emitido después de que tú pulses Allow en una página de QRFLOW. Desconéctalo cuando quieras en Account › Connected apps.
- Los tokens están vinculados al servidor MCP; no se pueden reutilizar con la API REST.
- Todas las operaciones de escritura pasan por la misma validación que el panel: destinos permitidos, comprobaciones del plan y límites de uso razonable.
- Las herramientas destructivas se describen con cuidado:
delete_qr_codeindica al modelo que prefiera pausar cuando ya se haya impreso un código. - Los documentos de descubrimiento están en
/.well-known/oauth-authorization-servery/.well-known/oauth-protected-resource; el registro sigue RFC 7591 y solo admite PKCE S256.
SDK y especificación OpenAPI
- TypeScript / JavaScript:
npm install qrflow(npm). Sin dependencias, ESM y CommonJS, tipado completo; funciona en Node 18+, Bun, Deno y Workers. Reintenta los errores 429 por ti e incluyeverifyWebhook/parseWebhook. - Python 3.9+, solo biblioteca estándar: qrflow.py.
- OpenAPI 3.1: /api/v1/openapi.json. Impórtalo en Postman o Insomnia, genera un cliente en cualquier lenguaje o adjúntalo a una acción de ChatGPT.
- Ambos clientes lanzan un error tipado (
QRFlowErrorconstatus,code,message,retryAfter) e incluyen un verificador de webhooks. El código fuente de TypeScript en un solo archivo sigue disponible en /sdk/qrflow.ts si prefieres incluirlo directamente en tu proyecto.
| TypeScript | Python | Llamadas |
|---|---|---|
| me() | me() | GET /me |
| catalog() | catalog() | GET /catalog |
| listCodes({ limit, q }) | list_codes(limit, q) | GET /codes |
| getCode(id) | get_code(id) | GET /codes/:id |
| createCode(input) | create_code(**fields) | POST /codes |
| updateCode(id, patch) | update_code(id, **patch) | PATCH /codes/:id |
| deleteCode(id) | delete_code(id) | DELETE /codes/:id |
| makeDynamic(id) | make_dynamic(id) | POST /codes/:id/dynamic |
| scans(id, { from, to, group }) | scans(id, from_, to, group) | GET /codes/:id/scans |
| bulkCreate(rows, colors) | bulk_create(rows, **colors) | POST /codes/bulk |
| domains() | domains() | GET /domains |
| listWebhooks() / createWebhook() / testWebhook(id) / deleteWebhook(id) | list_webhooks() / create_webhook() / test_webhook(id) / delete_webhook(id) | /webhooks |
| imageUrl(id, size) | image_url(id, size) | La dirección de la imagen (recupérala con la clave) |
| verifyWebhook(raw, header, secret) | verify_webhook(raw, header, secret) | Verificación de firma de las entregas |
Referencia de endpoints
URL base https://qrflow.codes/api/v1. Los cuerpos y las respuestas son JSON. Las fechas están en formato ISO 8601 UTC. En PATCH, envía solo los campos que cambian.
GETprofile
Plan, indicadores de funciones y límites aplicables a esta cuenta, además de los ámbitos de la clave.
curl https://qrflow.codes/api/v1/me \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "id": "…", "email": "ops@example.com", "plan": "business", "paid": true,
"features": { "dynamic_codes": true, "custom_domain": true, "link_names": true, "gs1": true, "api_keys": true },
"limits": { "saved_codes": 25000, "bulk_per_month": 10000, "bulk_per_request": 2000, "link_domains": 5, "requests_per_minute": 600 },
"auth": "api_key", "scopes": ["codes:read", "codes:write"] }
GETpublic
Tipos nativos (url, wifi, vcard, email, phone, sms, text, location) y unos 50 subtipos (Instagram, reseña de Google, Wi-Fi, tienda de aplicaciones…), cada uno con los campos que necesita y el plan requerido. No se necesita clave.
curl https://qrflow.codes/api/v1/catalog
GETcodes:read
Primero los más recientes.?limit= hasta 100,?q= busca etiquetas.
curl "https://qrflow.codes/api/v1/codes?limit=20&q=menu" \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTcodes:write
Se aplican las mismas reglas que al guardar en el sitio: los códigos de url, phone, email, sms y location son dinámicos en los planes de pago; los de Wi-Fi, vCard y text incluyen su contenido en el patrón. Incluye un id de subtipo en destination_data.subtype para crear, por ejemplo, un código de reseña de Google. El domain_id opcional selecciona cuál de tus dominios de enlaces se imprime en el código (GET /domains los muestra).
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents", "frame_style": "caption-below", "frame_caption": "Scan for menu" }'
{ "code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_code": "x7k2p9a",
"short_url": "https://go.example.com/x7k2p9a", "scans": 0, "image_url": "https://qrflow.codes/api/v1/codes/…/image.svg", … } }
GETcodes:read
El código con su recuento de escaneos, enlace corto y dirección de imagen.
curl https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
PATCHcodes:write
Cualquiera de estos campos: destination_data (solo códigos dinámicos; la impresión sigue siendo válida), label, paused, expires_at (ISO o null), slug (nombre del enlace en tu dominio), domain_id (cuál de tus dominios de enlaces se imprime en este código; null = el dominio predeterminado de la cuenta), fg_color, bg_color, frame_style, frame_caption, frame_caption2. Envía solo los campos que vayas a cambiar.
curl -X PATCH https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" }, "slug": "menu" }'
DELETEcodes:write
Se elimina definitivamente, incluido su historial de escaneos. El enlace impreso de un código dinámico deja de funcionar. Si el código impreso sigue circulando, es preferible usar paused: true.
curl -X DELETE https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
POSTcodes:write
El patrón impreso cambia (ahora codifica el enlace corto), así que vuelve a generar la imagen después.
curl -X POST https://qrflow.codes/api/v1/codes/$ID/dynamic \
-H "Authorization: Bearer $QRFLOW_KEY"
GETcodes:read
SVG listo para imprimir, con el marco y los colores.?size= establece el ancho de la cuadrícula de módulos en px; de todos modos, el archivo se escala sin pérdida.
curl https://qrflow.codes/api/v1/codes/$ID/image.svg \
-H "Authorization: Bearer $QRFLOW_KEY" -o code.svg
GETanalytics:read
?from= y?to= (fechas ISO, hasta 92 días; por defecto, los últimos 30) y?group= day, device, country, city, browser, os o referrer. Las mismas cifras que en la página de analíticas.
curl "https://qrflow.codes/api/v1/codes/$ID/scans?from=2026-09-01&to=2026-09-21&group=day" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "code_id": "…", "from": "…", "to": "…", "group": "day", "total": 412,
"rows": [ { "key": "2026-09-01", "scans": 18 }, { "key": "2026-09-02", "scans": 25 }, … ] }
POSTcodes:write
Hasta 2.000 códigos URL en una llamada, todos dinámicos. Se descuentan de la misma cuota mensual de operaciones masivas que la página Bulk (10.000 en Business). Las filas que no sean direcciones web aparecen en rejected; el resto se crea.
curl -X POST https://qrflow.codes/api/v1/codes/bulk \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "rows": [ { "destination": "https://example.com/t/1", "label": "Table 1" }, { "destination": "https://example.com/t/2", "label": "Table 2" } ] }'
{ "codes": [ … ], "rejected": [], "remaining_this_month": 9998 }
GETcodes:read
Los códigos que se imprimen en los envases de venta al por menor. Cada producto es un GTIN, la dirección impresa en el envase y los enlaces asociados. Busca por nombre y GTIN con?q=. Plan Business.
curl https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "products": [ { "gtin": "00860001234565", "name": "Wildflower Honey 12 oz",
"digital_link": "https://id.example.com/01/00860001234565",
"page_url": "https://id.example.com/p/00860001234565",
"links": [ { "link_type": "gs1:pip", "url": "…", "is_default": true, "batch": null } ] } ] }
POSTcodes:write
gtin y name son obligatorios; brand y url son opcionales. Se verifica el dígito de control antes de escribir cualquier dato, y los formatos de 8, 12, 13 y 14 dígitos se normalizan a 14. Si ya tienes un GTIN, se devuelve un 409 en lugar de crear un segundo producto.
curl -X POST https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"gtin":"00860001234565","name":"Wildflower Honey 12 oz","brand":"Sunny Acres","url":"https://sunnyacres.example/honey"}'
{ "product": { "gtin": "00860001234565", "digital_link": "https://id.example.com/01/00860001234565", … } }
PUTcodes:write
Un GTIN puede dirigir a varios destinos a la vez, cada uno con una etiqueta que indica para qué sirve. Se usa el teléfono como predeterminado; una aplicación que solicite un tipo recibe ese destino. Es idempotente: si se repiten el mismo link_type y batch, se reemplaza ese enlace en lugar de añadir otro, así que un script nocturno puede ejecutarse dos veces. Pasa batch para asociar el enlace a un lote concreto; así se publica una retirada sin afectar al resto de la producción.
curl -X PUT https://qrflow.codes/api/v1/products/00860001234565/links \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"link_type":"gs1:recallStatus","url":"https://sunnyacres.example/recall-a42","title":"Recall notice","batch":"A42","is_default":true}'
GETanalytics:read
Recuento por GTIN de los últimos?days= (de 1 a 365; por defecto, 30), desglosado por país, dispositivo, tipo de enlace y lote. went_nowhere cuenta los escaneos que no encontraron ningún destino y debería ser cero.
curl "https://qrflow.codes/api/v1/products/00860001234565/scans?days=30" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "gtin": "00860001234565", "days": 30, "total": 412, "went_nowhere": 0,
"by_link_type": [ { "key": "gs1:pip", "scans": 390 }, { "key": "gs1:recallStatus", "scans": 22 } ],
"by_batch": [ { "key": "A42", "scans": 22 } ] }
GETdomains:read
Tus dominios conectados, su estado y cuál se usa de forma predeterminada para imprimir códigos dinámicos (default_base). Pasa el id de un dominio como domain_id en un código para imprimirlo con otro dominio.
curl https://qrflow.codes/api/v1/domains \
-H "Authorization: Bearer $QRFLOW_KEY"
GETwebhooks:manage
Tus webhooks, con sus eventos, el último estado y el recuento de fallos.
curl https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTwebhooks:manage
url debe ser https en un host público; events puede ser cualquiera de estos valores: scan, code.created, code.updated, code.deleted. El secreto de firma se devuelve una sola vez.
curl -X POST https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hooks/qrflow", "events": ["scan", "code.updated"] }'
{ "webhook": { "id": "…", "url": "…", "events": ["scan", "code.updated"], "active": true, "secret": "whsec_…" } }
POSTwebhooks:manage
Envía un ping firmado ahora y muestra la respuesta.
curl -X POST https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
DELETEwebhooks:manage
Detiene todas las entregas, incluidos los reintentos en cola.
curl -X DELETE https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
GETpublic
Ids de los marcos y lo que necesita cada uno (texto, segunda línea), agrupados como en el personalizador. No se necesita clave.
curl https://qrflow.codes/api/v1/frames
El objeto Code
Todos los endpoints que interactúan con un código devuelven la misma estructura. Ignora los campos que no conozcas; se añaden otros nuevos con el tiempo.
| Campo | Tipo | Significado |
|---|---|---|
| id | uuid | Id estable. Úsalo en todas las demás llamadas. |
| label | string | null | El nombre en el panel. Hasta 120 caracteres. Se puede buscar con?q=. |
| kind | string | El id del catálogo: url, wifi, instagram, googlereview,... kind_label es el nombre legible. |
| type | string | La codificación: url, text, wifi, vcard, email, phone, sms, location. |
| destination_data | object | Los campos que enviaste (más subtype para los tipos). destination es un resumen de una línea. |
| dynamic | boolean | True cuando los escaneos pasan por QRFLOW y el destino puede cambiar. dynamic_capable indica si este tipo podría ser dinámico en un plan de pago. |
| short_code | string | Siete caracteres, nunca cambia. |
| short_url | string | Lo que se imprime para un código dinámico. Incluye tu dominio y slug si están configurados. |
| domain_id | uuid | null | El dominio de enlaces con el que se imprime este código; null significa el dominio predeterminado de la cuenta. |
| fg_color, bg_color | hex | Colores de los módulos y del fondo. |
| has_logo | boolean | Se añadió un logotipo en el panel; image.svg lo incluye. |
| frame_style, frame_caption, frame_caption2 | string | null | Id del marco y textos, como en el personalizador. |
| scans | integer | Recuento total de escaneos. |
| created_at, updated_at | ISO 8601 | UTC. |
| manage_url | url | La página del código en el panel, para un enlace «Abrir en QRFLOW». |
| image_url | url | GET /codes/:id/image.svg. Requiere el encabezado Authorization; no es una URL de imagen pública. |
| svg_download_url, png_download_url | url | El mismo SVG (marco, colores, logotipo) y un PNG sin formato, mediante enlaces firmados que funcionan durante 24 horas sin encabezado: para etiquetas <img>, scripts y asistentes que guardan un archivo. download_expires_at indica cuándo caducan; cada lectura del código devuelve enlaces nuevos. |
Otras estructuras: Scans (code_id, from, to, group, total, rows[key, scans]), Domain (id, host, status, active, is_default, verified_at, grace_until), Webhook (id, url, events, active, last_status, last_delivery_at, consecutive_failures, más secret una vez), Me (id, email, plan, paid, features, limits, auth, scopes) y Error (error, message). El documento OpenAPI especifica el tipo de todas las propiedades.
Business
Webhooks
QRFLOW llama a tu URL https cuando ocurre algo. Crea uno en Cuenta › Webhooks o con POST /webhooks; el secreto de firma se entrega una sola vez. Hasta 10 por cuenta.
| Evento | Cuándo | data |
|---|---|---|
| scan | En lotes: cada pocos minutos, todos los escaneos nuevos desde la última entrega, hasta 500 por llamada. | count, from, to, scans[] con code_id, label, short_code, slug, scanned_at, device, country, city, referrer, browser, os, language |
| code.created | Inmediatamente desde la API y los asistentes; en unos minutos desde el panel. Una solicitud masiva envía un evento con bulk: true y codes[]. | code, source |
| code.updated | Mismo plazo. Incluye cambios en el destino, la etiqueta, la pausa, el vencimiento, el nombre del enlace, el dominio, los colores, el marco y la conversión a dinámico. | code, changed[] (los nombres de los campos que cambiaron) |
| code.deleted | Mismo plazo. | code: { id, label, short_code, slug } |
| ping | Al pulsar Test. | webhook_id, message |
Qué se recibe
Cada carga útil es { id, event, created_at, data }. id se mantiene estable en los reintentos de una misma entrega, para que puedas deduplicarla.
{
"id": "9b1c6d2e-…",
"event": "scan",
"created_at": "2026-09-21T18:05:00.000Z",
"data": {
"count": 2,
"from": "2026-09-21T18:00:00.000Z",
"to": "2026-09-21T18:04:12.331Z",
"scans": [
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:03:40.101Z",
"device": "mobile", "country": "US", "city": "Las Vegas", "referrer": null, "browser": "Safari", "os": "iOS", "language": "en-US" },
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:04:12.331Z",
"device": "mobile", "country": "MX", "city": "Tijuana", "referrer": null, "browser": "Chrome", "os": "Android", "language": "es-MX" }
]
}
}
{
"id": "2f0a…",
"event": "code.updated",
"created_at": "2026-09-21T18:06:00.000Z",
"data": {
"code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_url": "https://go.example.com/menu", "scans": 412, "…": "…" },
"changed": ["destination_data"]
}
}
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: QRFLOW-Webhooks/1.0 (+https://qrflow.codes/developers)
X-QRFLOW-Event: scan
X-QRFLOW-Signature: t=1758477900,v1=5f1c…e9
Verificar la firma
X-QRFLOW-Signature: t=<unix seconds>,v1=<hex>. Calcula HMAC-SHA256 sobre ${t}.${rawBody} con tu secreto y compáralo en tiempo constante con v1; rechaza la solicitud si t tiene más de cinco minutos. Usa los bytes sin procesar que recibiste, nunca un objeto serializado de nuevo. En las recetas encontrarás receptores funcionales para Next.js y Python; ambos SDK incluyen el helper.
Reglas de entrega
- Responde con cualquier código 2xx en un plazo de 8 segundos. Haz el trabajo después de responder.
- Cualquier otra respuesta se reintenta al cabo de 1, 5, 15, 60, 240 y 720 minutos.
- Veinte fallos consecutivos desactivan el webhook y envían un correo al propietario de la cuenta. Vuelve a activarlo cuando se haya corregido el receptor; se reanudarán los reintentos en cola.
- Las URL deben usar https y estar en un host público. Se rechazan localhost, los rangos privados y qrflow.codes. Usa un túnel durante el desarrollo.
- Pulsa Test para recibir un
pingfirmado y ver el estado que respondió tu servidor.
Errores
Todos los errores son { "error": "<code>", "message": "<what to do>" } con el estado indicado a continuación. El mensaje está redactado para una persona; muéstralo.
| Estado | error | Significado |
|---|
Síntoma, causa, solución
Solución de problemas
401 invalid_token en todas las llamadas
Por quéEl encabezado es incorrecto o la clave no está activa.
SoluciónEnvía exactamente Authorization: Bearer qrf_live_… (un espacio, no dos puntos). Comprueba que la clave no se haya revocado en Cuenta › API keys. Si la copiaste de un chat o un documento, comprueba que no tenga un punto final o comillas tipográficas.
401 en /api/v1 con un token que funciona en el servidor MCP
Por quéLos tokens emitidos para https://qrflow.codes/mcp están vinculados a ese servidor.
SoluciónUsa una clave de API para REST o ejecuta un segundo flujo OAuth sin resource= para obtener un token para la API REST.
402 upgrade_required al crear una clave o un webhook
Por quéAmbas funciones requieren Business.
SoluciónMejora el plan en /pricing o usa el servidor MCP, que funciona en todos los planes mediante el inicio de sesión.
402 en POST /codes desde una aplicación OAuth
Por quéEl plan del usuario no incluye lo que solicitó la aplicación (un código dinámico, un dominio).
SoluciónConsulta primero las funciones de GET /me y adapta el comportamiento: crea el código de todos modos (será estático en Free) o informa al usuario de los requisitos del plan.
403 insufficient_scope
Por quéLos ámbitos se fijan al crear una clave. SoluciónCrea una clave nueva con los permisos que necesitas y revoca la anterior. Para OAuth, solicita el permiso en la petición de autorización.
400 not_dynamic al hacer PATCH destination_data
MotivoEl código es estático: de tipo Wi-Fi/vCard/texto, o se creó con el plan Free después de haber usado el único código dinámico gratuito.
SoluciónPara url/teléfono/correo electrónico/sms/ubicación, envía POST /codes/:id/dynamic mientras la cuenta tenga disponibilidad; después, vuelve a descargarlo e imprimirlo (la imagen cambia). Los códigos Wi-Fi, vCard y de texto nunca pueden ser dinámicos; crea un código url que abra una página.
400 no_domain al establecer slug
MotivoLos nombres de enlace pertenecen a tu dominio.
SoluciónConecta y verifica un dominio primero en la página Account. En qrflow.codes/q, la ruta siempre es el short_code.
409 conflict con slug
MotivoOtro de tus códigos ya tiene ese nombre.
SoluciónUsa GET /codes?q= para encontrarlo o elige otro nombre. Los nombres son por cuenta, no globales.
Error de CORS en la consola del navegador
MotivoLa API solo acepta llamadas de servidor a servidor (y Canva). Es intencional: una clave en una página web es una clave expuesta.
SoluciónMueve la llamada a un controlador de rutas, una acción de servidor, una función edge o un backend, y llama a eso desde la página.
La imagen muestra una marca de QRFLOW
MotivoEl código lo creó alguien que no había iniciado sesión. La marca solo aparece en las descargas anónimas.
SoluciónCualquier cuenta la elimina, incluso la gratuita. Las imágenes de un código guardado nunca la incluyen.
short_url sigue mostrando qrflow.codes/q/… después de añadir mi dominio
MotivoEl dominio aún no está verificado o su CNAME es incorrecto.
SoluciónComprueba el estado en la página Account o usa GET /domains (el estado debe ser verified). Los códigos existentes cambiarán automáticamente cuando lo esté.
image_url devuelve 401 en una etiqueta <img>
MotivoNecesita el encabezado Authorization, que un <img> no puede enviar.
SoluciónUsa svg_download_url o png_download_url del mismo objeto Code: son enlaces firmados que funcionan durante 24 horas sin encabezado. Para algo permanente, pasa image_url por tu servidor (consulta la receta de Next.js) o codifica short_url tú mismo.
Necesito un PNG, no un SVG
MotivoEl SVG incluye el marco y el logotipo; el PNG es el código sin adornos.
SoluciónGET /codes/:id/image.png (con bearer o el enlace firmado png_download_url) devuelve un PNG de entre 256 y 2048 px. Para obtener un PNG con el marco, convierte el SVG con sharp o resvg (sharp(svgBuffer).png().toBuffer()).
Mi asistente dijo que el endpoint de imagen lo rechazó y dibujó el código por su cuenta
MotivoObtuvo image_url, que requiere un bearer.
SoluciónAhora todos los códigos incluyen png_download_url y svg_download_url, y get_qr_image los devuelve; el asistente puede usar curl con esos enlaces sin iniciar sesión. Un código dibujado localmente que codifique el mismo short_url sigue funcionando y contabilizando escaneos, pero no incluye el marco ni el logotipo.
El webhook nunca llega
MotivoLas reglas de URL o el receptor.
SoluciónLa URL debe usar https y estar en un host público (sin localhost, IP privadas ni qrflow.codes). Pulsa Test en el webhook: el resultado muestra el estado que respondió tu servidor. Los eventos de escaneo se agrupan y pueden tardar hasta unos cinco minutos; los eventos code.* del panel también se ponen en cola durante unos minutos, mientras que las escrituras de API y MCP se entregan de inmediato.
La firma nunca se verifica
MotivoFirmaste un cuerpo serializado de nuevo.
SoluciónVerifica la firma con los bytes sin procesar exactos que recibiste, antes de analizar el JSON. En Express, usa express.raw({ type: 'application/json' }) en esa ruta; en Next.js App Router, usa await req.text(); en Flask, request.get_data(). Después, calcula HMAC-SHA256 de ${t}.${raw}\.
El webhook se desactivó solo
MotivoVeinte fallos consecutivos.
SoluciónCorrige el receptor y vuelve a activarlo (Account › Webhooks, o elimínalo y créalo de nuevo). Se te envió un correo cuando ocurrió. Los reintentos en cola se reanudarán.
Entregas duplicadas del webhook
MotivoUna respuesta 2xx lenta (más de 8 segundos) cuenta como fallo y se vuelve a intentar.
SoluciónResponde primero y procesa después. Evita duplicados usando el id del payload, que se mantiene igual en los reintentos.
429 rate_limited durante una importación
Motivo600 solicitudes por minuto y por clave.
SoluciónUsa POST /codes/bulk (2,000 códigos en una solicitud) en lugar de enviar un POST por código, o espera los segundos indicados en Retry-After.
Eliminé un código y el póster impreso ahora muestra «Code not found»
MotivoLa eliminación es permanente y desactiva el enlace.
SoluciónNo se puede deshacer. La próxima vez, usa PATCH { paused: true }; un código pausado muestra una página informativa y se puede reanudar.
Mi clave dejó de funcionar después de cambiar a un plan inferior
MotivoLas claves siguen funcionando durante 30 días después de dejar Business y luego responden con 402.
SoluciónVuelve a suscribirte; no se eliminó nada y las mismas claves volverán a funcionar.
¿No encuentras aquí tu problema? Escribe a hello@qrflow.codes e incluye la solicitud exacta y el error JSON que recibiste. Las cuentas Business tienen prioridad.
Límites y uso razonable
| Límite | |
|---|---|
| Solicitudes por minuto y por clave | 600. Si se supera, 429 con Retry-After. |
| Claves por cuenta | 10 |
| Webhooks por cuenta | 10 |
| Códigos guardados (uso razonable) | 1,000 Premium, 25,000 Business; la API se detiene al llegar al doble. |
| Operaciones en lote | 500/mes (500 por solicitud) en Premium; 10,000/mes (2,000 por solicitud) en Business. |
| Dominios de enlace | 1 en Premium, 5 en Business |
| Escaneos | Ilimitados. En Premium, se envía un correo informativo al llegar a 100,000 escaneos por código al mes; en Business, al llegar a 1,000,000. No se limita nada. |
| Ventana de análisis de escaneos | 92 días por solicitud |
| Tamaño de página de lista | 100 (?limit=) |
| Etiqueta / leyendas / slug | 120 / 60 / 40 caracteres |
| Tiempo de espera y reintentos del webhook | 8 segundos; reintentos después de 1, 5, 15, 60, 240 y 720 minutos; se desactiva tras 20 fallos consecutivos. |
| Después de dejar Business | Las claves y los webhooks siguen funcionando durante 30 días y luego responden con 402. No se elimina nada. |
El uso razonable es lo que contempla el precio del plan. No se limita nada al alcanzar esa cifra; la API se detiene al llegar al doble y una persona te escribe primero. Para volúmenes mayores: hello@qrflow.codes.
Seguridad para ti y para quienes escanean
Cómo protege QRFLOW tu cuenta
- Las claves se muestran una sola vez y se almacenan como hashes SHA-256. Nadie en QRFLOW puede recuperar una clave; si la pierdes, crea otra.
- Cada solicitud se limita a la cuenta a la que pertenece la clave. Un id de código de otra cuenta devuelve 404; nunca se expone.
- Los permisos son fijos para cada clave, así que una clave para un panel de informes no puede crear ni eliminar códigos.
- 600 solicitudes por minuto y por clave; si se supera, se devuelve un 429 claro, sin ralentizar el servicio para los demás.
- Los destinos están en una lista de permitidos: http, https, mailto, tel, sms, geo y una lista breve de esquemas de aplicaciones (whatsapp, tg, signal, spotify, tiendas de aplicaciones). javascript:, data: y file: se rechazan al crear el código, así que una integración comprometida no puede convertir tus códigos en un ataque.
- Las URL de los webhooks deben usar https y estar en hosts públicos; QRFLOW nunca llama a redes privadas ni a sí mismo. Cada entrega está firmada y cada payload tiene un id estable.
- Los clientes OAuth se registran con PKCE S256 y los tokens quedan vinculados al servidor para el que se emitieron; un token del servidor MCP no se puede reutilizar en la API REST.
- Cualquiera puede revocar una clave o desconectar una aplicación en la página Account; el efecto es inmediato.
Qué debes hacer por tu parte
- Usa variables de entorno, nunca código fuente. Si una clave aparece en el historial de git, revócala.
- Solo en el servidor. La API rechaza los orígenes del navegador, pero tus propios endpoints que la envuelvan también necesitan autenticación; de lo contrario, cualquiera puede crear códigos a tu cargo.
- Asigna a cada integración su propia clave con los permisos necesarios y ponle el nombre de la integración. Así, al revocarla, solo se verá afectada una cosa.
- Verifica las firmas de los webhooks y rechaza las marcas de tiempo de más de cinco minutos.
- Si los datos de tus usuarios se incluyen en etiquetas o destinos, recuerda que QRFLOW los almacena; evita incluir datos personales en las etiquetas siempre que puedas.
Qué registran los escaneos y qué no
- Cada redirección almacena el tipo de dispositivo, el país, la ciudad, el referente, el navegador, el sistema operativo y el idioma, derivados de la solicitud, además de un hash unidireccional de código + día + IP + agente de usuario para que el propietario pueda contar visitantes únicos. No se puede revertir el hash para obtener una dirección.
- No se instalan cookies en el dispositivo de quien escanea y la dirección IP no se conserva junto con el escaneo. Se omiten los bots conocidos y los rastreadores de vista previa de enlaces.
- Al eliminar un código, se eliminan sus escaneos. Al eliminar la cuenta, se elimina todo.
- Texto completo: https://qrflow.codes/privacy y https://qrflow.codes/terms.
Versionado y estabilidad
La API se versiona en la ruta: /api/v1. Dentro de v1 añadimos campos, endpoints, tipos y eventos; no eliminamos ni cambiamos el nombre de nada, y tu código debe ignorar los campos desconocidos de las respuestas.
Si alguna vez es necesario introducir un cambio incompatible en v1, se publicará como /api/v2 y v1 seguirá funcionando durante al menos doce meses. Se avisará por correo a los propietarios de las claves sobre las obsolescencias con 90 días de antelación.
El servidor MCP sigue la misma regla para sus herramientas: solo se añaden argumentos y se conserva el nombre de cada herramienta.
El documento OpenAPI en /api/v1/openapi.json y el Markdown en /llms-full.txt se generan a partir del código que sirve la API, así que describen lo que está disponible actualmente.
Preguntas frecuentes de desarrolladores
¿Tengo que pagar para usar la API de QRFLOW?
Las claves de API están incluidas en el plan Business, que cuesta $29 al mes y se paga mes a mes. El servidor MCP (Claude, ChatGPT, Cursor, Claude Code) y OAuth para tu propia aplicación funcionan en todos los planes mediante el inicio de sesión, y lo que pueden crear depende del plan. GET /catalog, GET /frames y /preview.svg no requieren ninguna clave.
¿Puedo generar códigos QR gratis mediante la API?
No con una clave. Para una imagen estática sencilla, basta con el generador gratuito de qrflow.codes o cualquier biblioteca QR de código abierto. La API es para códigos dinámicos, tu propio dominio, análisis, operaciones en lote y webhooks, funciones incluidas en una cuenta de pago.
¿Puedo llamar a la API desde el navegador?
No. Rechaza los orígenes del navegador para que una clave nunca termine en una página web. Llámala desde un controlador de rutas, una acción de servidor, una función edge o un backend, y llama a eso desde tu página.
¿Qué formatos de imagen puedo obtener?
SVG con tus colores, marco, leyendas y logotipo (GET /codes/:id/image.svg, tamaño nominal de 256 a 4096 px) y un PNG sencillo (GET /codes/:id/image.png, de 256 a 2048 px). Ambos aceptan un bearer o los enlaces firmados svg_download_url / png_download_url que incluye cada objeto Code; funcionan durante 24 horas sin encabezado. La herramienta MCP get_qr_image devuelve el PNG integrado y ambos enlaces.
¿Puedo cambiar un código QR después de imprimirlo?
Sí, si es dinámico (url, teléfono, correo electrónico, sms, ubicación en un plan de pago). Usa PATCH /codes/:id con un nuevo destination_data; la imagen no cambia y el siguiente escaneo lleva al nuevo destino. Los códigos Wi-Fi, vCard y de texto incluyen su contenido en la imagen y no se pueden cambiar.
¿Cuál es la diferencia entre short_url y el destino?
short_url es el enlace que aparece en la imagen (go.example.com/menu). El destino es adonde redirige ese enlace (https://example.com/menu-fall). Imprime short_url una sola vez y cambia el destino tantas veces como quieras.
¿Pueden los códigos usar mi propio dominio?
Sí. Premium permite conectar 1 dominio y Business, 5; añade un CNAME y verifícalo en la página Account. En Business, puedes elegir un dominio para cada código con domain_id. Los nombres de enlace (slug) crean rutas legibles en ese dominio.
¿Qué datos registra un escaneo sobre quien escanea?
El tipo de dispositivo, el país, la ciudad, el referente, el navegador, el sistema operativo y el idioma, obtenidos de la solicitud, además de un hash diario unidireccional para contar visitantes únicos. No se usan cookies y no se almacena la dirección IP. Suficiente para un gráfico, pero no para identificar a nadie. Más detalles: https://qrflow.codes/privacy#scans
¿Hay un paquete para npm o PyPI?
npm: npm install qrflow\ (https://www.npmjs.com/package/qrflow), sin dependencias, ESM y CommonJS, tipos completos de TypeScript, compatible con Node 18+, Bun, Deno y Workers; incluye un wrapper para todos los endpoints, reintenta los errores 429 e incluye verifyWebhook/parseWebhook. Python: un cliente de un solo archivo en https://qrflow.codes/sdk/qrflow.py (solo biblioteca estándar) con verify_webhook; próximamente habrá un paquete de PyPI.
¿Funciona con Claude, ChatGPT, Cursor y Claude Code?
Sí. QRFLOW es un servidor MCP en https://qrflow.codes/mcp. Añádelo como conector, inicia sesión una vez y haz preguntas con palabras sencillas. Once herramientas permiten crear, editar, pausar, asignar nombres, procesar operaciones en lote, consultar análisis, imágenes y dominios.
¿Pueden mis propios usuarios conectar sus cuentas de QRFLOW a mi aplicación?
Sí, con OAuth 2.0. Registra un cliente en /api/oauth/register (no se necesita una cuenta), envía a los usuarios a /oauth/authorize con PKCE y llama a la API con su token. Los códigos aparecen en su cuenta según su plan.
¿Cómo pruebo los webhooks en localhost?
Expón tu servidor de desarrollo mediante un túnel (cloudflared o ngrok) y usa su dirección https como URL del webhook; luego pulsa Test en Account › Webhooks para recibir un ping firmado. Las URL de los webhooks deben ser https públicas; se rechazan localhost y las direcciones privadas.
¿Qué pasa con mi integración si cancelo Business?
Las claves y los webhooks seguirán funcionando durante 30 días y, después, responderán con 402. Los códigos, escaneos y dominios permanecerán en la cuenta. Si vuelves a suscribirte, todo se reactivará con las mismas claves.
¿Cómo creo mediante la API un código para una reseña de Google, Instagram, Wi-Fi o PDF?
GET /catalog muestra todos los tipos y sus campos. Luego, envía POST /codes con el tipo y los campos correspondientes, y añade subtype para estos tipos: { type: 'url', destination_data: { subtype: 'googlereview', placeId: 'ChIJ…' } }, { type: 'wifi', destination_data: { ssid, password, encryption: 'WPA' } }, { type: 'url', destination_data: { subtype: 'instagram', handle: 'acme' } }.
¿Puede la API subir un logotipo a un código?
Todavía no. Añade el logotipo en el panel; image.svg lo incluye y has_logo indica si está presente. Los colores, los marcos y los textos se pueden configurar mediante la API.
¿La API es estable?
v1 solo añade funciones; nunca elimina ni cambia nombres. Los cambios incompatibles se publicarían en v2, mientras que v1 seguiría disponible durante al menos doce meses, con un aviso por correo electrónico con 90 días de antelación.
Para agentes, herramientas y asistentes que lean esto
Legible por máquinas
Todo lo que aparece en esta página está disponible en un formato que el software puede obtener. Se genera a partir del código que sirve la API, así que nunca queda desactualizado.
| URL | Qué es | |
|---|---|---|
| llms-full.txt | https://qrflow.codes/llms-full.txt | Toda esta referencia en Markdown: conceptos, todos los endpoints, todas las herramientas MCP, recetas, solución de problemas y preguntas frecuentes. Se genera a partir de la misma fuente que esta página. |
| developers.md | https://qrflow.codes/developers.md | El mismo documento, para herramientas que obtienen a.md. |
| llms.txt | https://qrflow.codes/llms.txt | El índice del sitio para asistentes, que apunta aquí. |
| La API en una página | https://qrflow.codes/qr-code-api | Qué hace la API, cuándo una biblioteca del lado del cliente es la mejor opción y cuánto cuesta. La versión resumida de esta referencia, para decidir en lugar de desarrollar. |
| openapi.json | https://qrflow.codes/api/v1/openapi.json | OpenAPI 3.1. Impórtalo en Postman, Insomnia, un generador de código o una acción de ChatGPT. |
| Servidor MCP | https://qrflow.codes/mcp | HTTP transmisible, OAuth con registro dinámico o una clave Business como bearer. |
| server.json | https://qrflow.codes/.well-known/mcp/server.json | El manifiesto del registro MCP. |
| Descubrimiento de OAuth | https://qrflow.codes/.well-known/oauth-authorization-server | Metadatos RFC 8414; el documento del recurso protegido está junto a ellos. |
| Paquete npm | https://www.npmjs.com/package/qrflow | npm install qrflow. Cliente tipado, sin dependencias, con verificación de webhooks. Cliente de Python en un solo archivo en https://qrflow.codes/sdk/qrflow.py. |
| GitHub | https://github.com/nativecodeapps/qrflow-sdk | Clientes, instantánea de OpenAPI y ejemplos ejecutables para webhooks de Next.js, Workers, Express, FastAPI y Flask. Se agradecen los issues y las PR. |
Preguntas, ideas o sugerencias de tipos de código que deberíamos añadir: hello@qrflow.codes. Términos: /terms. Privacidad: /privacy.