QRFLOW.codes
oficialCrie códigos QR, redirecione códigos dinâmicos impressos, nomeie links no seu próprio domínio e leia análises de escaneamento.
O que você pode fazer com QRFLOW Codes MCP?
- Crie códigos QR dinâmicos — Peça ao assistente para criar um código
urlcomdestination_datae retornar oshort_urlpara impressão. - Redirecione um código impresso — Altere o destino para o qual um código dinâmico existente redireciona sem precisar reimprimir, já que a imagem contém o
short_url. - Pause ou expire um código — Defina
paused: trueou uma data de término em vez de excluir, para que um link impresso pare de redirecionar com segurança. - Consulte as análises de escaneamento — Consulte o total de
Scansacumulado ou uma análise por dia, país e dispositivo de um código. - Dê nomes aos links no seu próprio domínio — Defina um
slug, comomenu, e escolha um domínio de link para que o código seja impresso comogo.example.com/menu. - Crie códigos em massa — Gere milhares de códigos dinâmicos a partir de uma lista e associe os códigos retornados às linhas pelo rótulo.
Servidor MCP hospedado
npx add-mcp 'https://qrflow.codes/mcp'Instala no Claude Code, Codex, Cursor e outros
Documentação
QRFLOW.codes para desenvolvedores
Comece aqui
QRFLOW.codes cria códigos QR que você pode alterar depois de imprimir, no seu próprio domínio, com análises de escaneamentos, e permite que seu software e seu assistente de IA façam tudo isso por meio de uma única API.
Um código QR é a imagem de uma string. A maioria dos geradores coloca seu endereço web na imagem; se o endereço mudar, a impressão perde a validade. QRFLOW coloca um link curto na imagem (go.yourbrand.com/menu ou qrflow.codes/q/x7k2p9a) e redireciona para ele. Você pode alterar o destino quando quiser, e cada escaneamento é contabilizado. Isso é um código dinâmico, e é o que vale a pena ter em uma API.
A API faz exatamente o que o painel faz: criar códigos de qualquer tipo, apontá-los para um novo destino, nomear seus links, escolher com qual dos seus domínios eles serão impressos, consultar números de escaneamentos, criar milhares de uma vez e receber notificações quando algo acontecer (webhooks). As mesmas ferramentas são disponibilizadas como um servidor MCP, para que Claude, ChatGPT, Cursor e Claude Code possam controlar sua conta usando linguagem natural.
Acesso: a API REST aceita uma chave de API Business (US$ 29 por mês, criada na página Account) ou um token OAuth. O servidor MCP funciona em todos os planos por meio de autenticação OAuth; o que o assistente pode criar segue o plano, como em qualquer outro lugar.
Ainda está decidindo se deve usar? A página da API de códigos QR é um resumo: o que ela faz, o que uma biblioteca do lado do cliente faz melhor e quanto custa.
Se você é um assistente de IA ajudando alguém a criar algo com QRFLOW
Boas-vindas. Esta página foi escrita tanto para você quanto para a pessoa que está ajudando. Veja como é uma boa assistência:
- Confirme o plano da conta: as chaves de API exigem o plano Business. Se a pessoa não tiver esse plano, indique https://qrflow.codes/pricing e Account › API keys; não invente uma chave nem um plano gratuito que não existe.
- Mantenha a chave no servidor. Leia-a de uma variável de ambiente (QRFLOW_KEY) em um manipulador de rota, ação de servidor, função de borda ou backend. A API recusa intencionalmente origens de navegador (CORS), então não é possível chamá-la apenas com código de front-end.
- Crie códigos dinâmicos com type "url" e destination_data.url. Salve id e short_url retornados no banco de dados da pessoa. Imprima ou exiba short_url; o destino pode ser alterado depois com PATCH /codes/:id, e a impressão continua válida.
- Para exibir ou salvar a imagem: todo objeto Code tem png_download_url e svg_download_url, links assinados que funcionam por 24 horas sem cabeçalho (adequados para salvar uma única vez ou para uma prévia). Para algo permanente no aplicativo, faça proxy de GET /codes/:id/image.svg pelo servidor com a chave, ou codifique short_url com qualquer biblioteca de QR no cliente; o rastreamento continua funcionando porque o link passa pelo QRFLOW.
- Envie apenas os campos que mudam em PATCH. Nunca altere slug ou domain_id depois que algo for impresso; ambos alteram o link impresso.
- Prefira paused: true a DELETE quando já houver uma impressão. Excluir invalida o link.
- Para eventos, use webhooks (Account › Webhooks ou POST /webhooks) e verifique o cabeçalho X-QRFLOW-Signature com o corpo bruto da solicitação. Não faça polling de GET /codes em um loop.
- Se a pessoa quiser usar QRFLOW pelo chat em vez de pelo código, conecte o servidor MCP em https://qrflow.codes/mcp;; não é necessária nenhuma chave.
- Quando algo falhar, leia error e message no corpo JSON. A seção de solução de problemas abaixo relaciona cada código de erro a uma correção.
- A referência completa em Markdown está em https://qrflow.codes/llms-full.txt e o documento OpenAPI 3.1 está em https://qrflow.codes/api/v1/openapi.json.. Ambos são gerados a partir da mesma fonte que esta página.
Pessoas: este bloco é como garantimos que o assistente com quem você está trabalhando dê a versão segura de cada resposta. Ele também é um bom resumo.
De qual plano você precisa
A chave de API é a única coisa exclusiva do plano Business. Tudo o que um assistente faz pelo servidor MCP e tudo o que um aplicativo de terceiros faz por OAuth funciona em qualquer plano e simplesmente segue os recursos desse plano. Preços completos e uso justo: /pricing.
| Free | Premium $4 | Business $29 | |
|---|---|---|---|
| Chaves de API (REST do seu código) | Não | Não | Sim, até 10 chaves |
| Servidor MCP (Claude, ChatGPT, Cursor, Claude Code) | Sim, faça login | Sim | Sim, com login ou chave |
| OAuth para seu próprio aplicativo (usuários conectam o QRFLOW deles) | Sim | Sim | Sim |
| Códigos dinâmicos (alterar o destino depois de imprimir) | Um | Todos os códigos | Todos os códigos |
| Seu próprio domínio de link | Não | 1 domínio | 5 domínios, escolha por código |
| Nomes de link (go.brand.com/menu) | Não | Sim | Sim |
| Análises de escaneamentos | Não | Sim | Sim |
| Webhooks | Não | Não | Sim, até 10 |
| Criação em lote | Não | 500/mês, 500 por solicitação | 10.000/mês, 2.000 por solicitação |
| Códigos salvos (uso justo) | Alguns | 1.000 | 25.000 |
| Assentos de equipe | 1 | 1 | 5 |
| Preço | $0 | $4/mês | $29/mês |
Doze palavras que fazem todo o trabalho
Conceitos
Leia isto uma vez e todos os endpoints abaixo farão sentido.
Static code
O conteúdo está dentro da imagem. Códigos de Wi-Fi, cartão de contato (vCard) e texto simples são sempre estáticos, e no plano Free todos os códigos são estáticos. Um código estático não precisa de servidor, nunca expira e não pode ser alterado nem contabilizado.
Dynamic code
A imagem contém um link curto para o qual QRFLOW redireciona. Códigos url, phone, email, sms e location são dinâmicos nos planos Premium e Business. Você pode alterar o destino, pausar, definir uma expiração, renomear e contabilizar esses códigos sem mexer na impressão.
short_url
A string exata codificada em um código dinâmico e o que deve ser impresso. É https://qrflow.codes/q/<short_code> até você conectar um domínio; depois, é https://<your domain>/<slug or short_code>.. Todo objeto Code contém esse valor.
short_code
Sete caracteres aleatórios, exclusivos por código, atribuídos na criação e nunca alterados. É o caminho alternativo quando um código não tem nome de link.
slug (link name)
Um caminho legível no seu próprio domínio: go.example.com/menu. De 3 a 40 letras minúsculas, números e hífens, exclusivo na sua conta e disponível apenas com um domínio conectado. Defina-o antes de imprimir: alterá-lo muda o link impresso.
Link domain
Um nome de host que você possui (go.example.com), apontado para QRFLOW por um CNAME e verificado na página Account. O plano Premium inclui um; o Business inclui cinco e permite escolher por código com domain_id. O domínio ativo mais antigo é o padrão.
Kind, type and subtype
type é a codificação: url, text, wifi, vcard, email, phone, sms, location. Um tipo de uso é um nome mais amigável para o que as pessoas querem (instagram, googlereview, whatsapp, pdf, menu, appstore,...). A maioria dos tipos de uso são códigos url com destination_data.subtype definido. GET /catalog lista todos os tipos de uso e seus campos; kind em um Code informa qual é o tipo de uso.
destination_data
Os campos do tipo, como strings: { url } para um site, { ssid, password, encryption } para Wi-Fi, { placeId } para uma avaliação do Google, { handle } para Instagram. Em um código dinâmico, você pode substituí-los a qualquer momento.
Scans
Cada redirecionamento registra o tipo de dispositivo, país, cidade, referenciador, navegador, sistema operacional e idioma da própria solicitação, além de um hash diário unidirecional para contabilizar visitantes únicos. Nenhum cookie é definido e o endereço IP não é armazenado. scans em um Code é o total acumulado; GET /codes/:id/scans detalha esses dados.
Source
Todo código registra como foi criado: dashboard, api:<key name>, mcp, canva, app:<connected app> (por exemplo, app:Google Sheets) ou bulk, com o prefixo bulk: quando veio de uma solicitação em lote. Isso aparece no painel e nos payloads de webhook, para que você possa distinguir os códigos da sua integração dos criados manualmente.
Workspace
Um proprietário Business pode convidar até quatro colegas de equipe. As chaves e os webhooks pertencem à conta do proprietário; os códigos criados por qualquer pessoa no espaço de trabalho ficam visíveis para toda a equipe.
Cinco minutos
Início rápido
Obtenha uma chave
- No plano Business, abra Account › API keys.
- Dê a ela um nome relacionado à finalidade ("Shop backend", "Reporting") e escolha os escopos. Os escopos não podem ser alterados depois; crie uma nova chave se precisar de outros.
- Copie-a uma única vez. Ela se parece com
qrf_live_…. Coloque-a em uma variável de ambiente chamadaQRFLOW_KEY. - Envie-a como
Authorization: Bearer $QRFLOW_KEYem todas as solicitações. Essa é toda a autenticação.
As chaves são para servidores. Nunca coloque uma em uma página web, aplicativo móvel ou planilha compartilhada; revogue e gere outra se houver vazamento.
Os mesmos cinco passos em curl, TypeScript e Python. Cada exemplo cria um código dinâmico, baixa sua imagem, altera o destino e consulta os escaneamentos.
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
Autenticação
Chaves de API (Business)
Até 10 por conta, 600 solicitações por minuto cada, armazenadas com hash e exibidas uma única vez. Uma chave inclui os escopos com os quais foi criada:
| Escopo | Permite |
|---|---|
| profile | GET /me: plano, recursos, limites. Toda chave inclui esse escopo. |
| codes:read | Listar e consultar códigos, baixar imagens. |
| codes:write | Criar, alterar, tornar dinâmico, excluir e criar códigos em lote. |
| analytics:read | GET /codes/:id/scans. |
| domains:read | GET /domains (necessário para usar domain_id de forma adequada). |
| codes:read / codes:write | Também para produtos GS1: os endpoints /products compartilham os escopos de códigos, então uma chave que gerencia códigos também gerencia códigos de embalagem. |
| webhooks:manage | Listar, criar, testar e excluir webhooks. |
OAuth 2.0 (qualquer plano, para aplicativos e assistentes)
Quando os códigos devem pertencer às contas dos seus usuários, e não à sua, ou quando um assistente de chat é o cliente, use OAuth. Os clientes se registram; PKCE S256 é obrigatório para clientes públicos; os tokens podem ser vinculados ao servidor MCP com resource=. A receita de OAuth explica o processo.
| Endpoint | URL | Observações |
|---|---|---|
| Autorização | https://qrflow.codes/oauth/authorize | Envie o usuário para cá; ele faz login e clica em Allow. |
| Token | https://qrflow.codes/api/oauth/token | Concessões authorization_code e refresh_token. Os tokens de acesso duram 1 hora; os tokens de atualização, 90 dias. |
| Revogação | https://qrflow.codes/api/oauth/revoke | RFC 7009. Os usuários também podem desconectar em Account › Connected apps. |
| Registrar um cliente | https://qrflow.codes/api/oauth/register | Registro dinâmico RFC 7591, sem necessidade de conta. Clientes públicos recebem um client_id dyn_ e devem usar PKCE S256. |
| Descoberta | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414. O documento de recursos MCP está em /.well-known/oauth-protected-resource. |
Os tokens de acesso duram 1 hora; os tokens de atualização, 90 dias. Os usuários veem os aplicativos conectados em Account › Connected apps e podem desconectá-los a qualquer momento. Um token emitido para https://qrflow.codes/mcp é recusado em /api/v1, e vice-versa.
As coisas que as pessoas realmente pedem
Receitas de implementação
Cada receita é completa e foi copiada diretamente de código funcional. Escolha a que corresponde à sua stack; a estrutura é sempre a mesma: uma chamada do lado do servidor com a chave, salvar id e short_url, exibir a imagem.
- Next.js
- Exibir o QR sem fazer proxy
- Express ou qualquer servidor Node
- Cloudflare Workers, Vercel Edge, Deno Deploy, Supabase Edge Functions
- Python
- Um código QR por pedido, mesa, produto, ingresso ou evento
- Alterar o destino de um código impresso
- Imprimir códigos no seu próprio domínio
- Um gráfico de escaneamentos no seu próprio painel de administração
- Receber webhooks no Next.js e verificá-los
- Receber webhooks em Python
- Milhares de códigos a partir de um CSV
- Permitir que seus usuários conectem a própria conta QRFLOW (OAuth)
- Zapier, Make, n8n
Next.js: uma rota que cria um código e outra que o exibe
Quando usar: você tem um aplicativo Next.js (App Router) e quer um botão que crie um código QR e uma página que o exiba.
- Coloque sua chave em .env.local como QRFLOW_KEY. Nunca use o prefixo NEXT_PUBLIC_.
- Adicione um manipulador de rota POST que crie o código e retorne id e short_url.
- Adicione uma rota GET que faça proxy da imagem para que o navegador nunca veja a chave.
- Armazene id e short_url no seu próprio registro (pedido, mesa, produto, 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>
- Server Actions funcionam da mesma forma: chame fetch com a chave dentro da action.
- Para Pages Router, o mesmo código vai em pages/api/qr.ts com req/res.
Exiba o QR sem proxy: renderize short_url você mesmo
Quando: Você quer a imagem no navegador imediatamente e não precisa dos frames nem do logo do QRFLOW.
Qualquer biblioteca de QR funciona, porque o código É o link curto
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.
- Este é o caminho mais rápido para uma prévia. Para impressão, baixe /codes/:id/image.svg: ele inclui as cores, o frame, as legendas e o logo salvos, além de ser vetorial.
- Se você alterar slug ou domain_id depois, short_url muda; renderize novamente.
Express ou qualquer servidor Node
Quando: Um backend Node simples.
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
Quando: Um ambiente de execução que usa apenas fetch, sem recursos integrados do 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_...
- O pacote npm
qrflow\usa apenas fetch e WebCrypto, então funciona em todos eles sem alterações.
Python: FastAPI, Flask, Django, um script
Quando: Seu backend é em 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")
Um código QR por pedido, mesa, produto, ingresso ou evento
Quando: Cada linha de uma das suas tabelas precisa do próprio código, criado automaticamente.
- Adicione duas colunas à sua tabela: qrflow_code_id (uuid) e qr_short_url (text).
- Quando uma linha for criada, faça POST /codes com a URL pública da linha e um rótulo que a identifique ("Pedido 10432", "Mesa 7"). Salve id e short_url.
- Quando a página da linha mudar (novo domínio, novo caminho), faça PATCH destination_data. Os códigos impressos continuarão funcionando.
- Quando a linha for desativada, faça PATCH { paused: true } se algo tiver sido impresso; use DELETE somente se nada tiver sido impresso.
- Precisa de milhares de uma vez (um menu por mesa para 300 restaurantes)? Use POST /codes/bulk em lotes e associe os códigos retornados às suas linhas pelo rótulo ou pelo 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 });
- O uso justo permite 25,000 códigos salvos no Business; a API para no dobro desse limite. Se você precisa de um código por recibo para sempre, fale conosco primeiro: hello@qrflow.codes.
Altere o destino de um código impresso
Quando: Uma campanha terminou, uma página mudou, um PDF foi substituído ou uma temporada mudou.
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" } }'
Pause-o ou defina uma data de término
# 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" }'
- Somente códigos dinâmicos podem ser redirecionados; qualquer código estático retorna 400 not_dynamic. Códigos de Wi-Fi, vCard e texto simples contêm o conteúdo no padrão e nunca podem ser dinâmicos, então POST /codes/:id/dynamic os recusa com 400 not_dynamic_capable. Para códigos de url, telefone, email, sms e localização, o plano Free torna o primeiro dinâmico e os demais estáticos, e todos são dinâmicos em um plano pago; POST /codes/:id/dynamic converte um código estático enquanto a conta ainda tiver cota. Renderize e imprima novamente depois, porque a imagem muda.
- Um scanner vê o novo destino na próxima leitura. Não há cache pelo qual esperar.
Imprima códigos no seu próprio domínio
Quando: Você quer go.example.com/menu no código em vez de qrflow.codes/q/x7k2p9a.
- Na página Account, em Your own link domain, adicione go.example.com e crie o CNAME indicado no seu provedor de DNS. A verificação geralmente é concluída em minutos.
- A partir daí, o short_url de cada novo código dinâmico usará esse domínio. Os códigos existentes também mudam: a imagem deles codificava qrflow.codes/q/..., que continua redirecionando, então nada que já foi impresso deixa de funcionar.
- Dê nomes legíveis aos códigos com slug: PATCH { "slug": "menu" } cria go.example.com/menu. Faça isso antes de imprimir.
- No Business com vários domínios, GET /domains lista os domínios com seus ids; passe domain_id em POST ou PATCH para escolher um por código.
Dê um nome ao link e escolha um domínio
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
Um gráfico de leituras no seu próprio painel de administração
Quando: Você quer ver leituras por dia, país ou dispositivo junto dos seus próprios números.
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
- Uma solicitação cobre até 92 dias; faça um loop para períodos mais longos. As datas estão em UTC.
- Para obter números em tempo real sem polling, inscreva um webhook no evento de leitura: você recebe cada leitura com seus detalhes em lotes a cada poucos minutos.
Receba webhooks no Next.js e verifique-os
Quando: Você quer saber quando um código é lido ou alterado, no seu próprio banco de dados, quase em tempo real.
- Crie o webhook em Account › Webhooks ou com POST /webhooks. Copie o segredo (whsec_...) uma única vez para QRFLOW_WEBHOOK_SECRET.
- Leia o corpo bruto como texto antes de analisá-lo; a assinatura cobre os bytes exatos.
- Verifique e, em seguida, selecione o evento. Responda com 2xx rapidamente; faça o trabalho demorado depois de responder ou em uma fila.
- Pressione Test no webhook para receber um ping assinado e confirmar a configuração.
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 });
}
- Localmente, exponha seu servidor de desenvolvimento com um túnel (cloudflared tunnel --url http://localhost:3000, ou ngrok) e use essa URL https para o webhook durante o desenvolvimento.
- O pacote npm faz isso por você:
import { parseWebhook } from "qrflow"\verifica e analisa em uma única chamada (WebCrypto, então também funciona em Workers e Deno). O cliente Python inclui verify_webhook.
Receba webhooks em Python
Quando: Flask, FastAPI ou Django recebendo os mesmos 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
Milhares de códigos a partir de um CSV
Quando: Um código por SKU, assento, etiqueta de ativo ou mala direta.
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");
}
- O processamento em lote cria apenas códigos url dinâmicos, todos com as mesmas cores. Os códigos são retornados na ordem em que você os enviou, menos as linhas rejeitadas; em caso de dúvida, associe-os pelo rótulo.
- Os webhooks recebem um evento code.created por solicitação em lote, com codes[] em vez de um evento por código.
Permita que seus usuários conectem a própria conta QRFLOW (OAuth)
Quando: Você está criando um produto para outras pessoas e quer que os códigos sejam criados nas contas QRFLOW delas, não na sua.
- Registre um cliente uma vez: POST https://qrflow.codes/api/oauth/register com client_name e redirect_uris. Você receberá um client_id (e um client_secret para clientes confidenciais).
- Envie o usuário para /oauth/authorize com response_type=code, client_id, redirect_uri, scope, state e PKCE (code_challenge, code_challenge_method=S256).
- Troque o código em /api/oauth/token. Armazene o refresh token; os access tokens duram uma hora.
- Chame /api/v1 com Authorization: Bearer <access_token>. Tudo funciona exatamente como com uma chave, de acordo com o plano do usuário.
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
- Os escopos são os mesmos seis das chaves de API. Solicite apenas o mínimo necessário; a tela de consentimento os lista.
- Se seu app for um assistente de chat ou agente, adicione resource=https://qrflow.codes/mcp à solicitação de autorização e use o servidor MCP; o token ficará vinculado a ele.
Zapier, Make, n8n: sem código
Quando: Você quer que leituras ou novos códigos apareçam em uma planilha, canal do Slack ou CRM.
- Crie um gatilho de webhook de entrada (Zapier: Webhooks by Zapier › Catch Hook; Make: Custom webhook; n8n: Webhook node) e copie a URL https.
- Em Account › Webhooks, adicione essa URL e escolha os eventos. Pressione Test; o ping aparecerá na ferramenta e mostrará o formato do payload.
- Mapeie data.scans[] (para leitura) ou data.code (para code.*) para sua planilha, mensagem ou registro.
- Para criar códigos nessas ferramentas, use o módulo HTTP delas com POST /codes e o cabeçalho Authorization. Mantenha a chave no armazenamento de credenciais da ferramenta.
- No Zapier, agora há um app QRFLOW.codes: as etapas Create QR Code, Update QR Code e Find, além do gatilho instantâneo New Scan, não precisam de configuração de webhook nem de chave de API. Consulte QRFLOW com Zapier. As etapas abaixo são para Make, n8n e qualquer outra ferramenta.
- Essas ferramentas não conseguem verificar a assinatura. A URL fornecida é impossível de adivinhar, e essa é a proteção disponível; não a publique em lugar nenhum.
- Se a lista já estiver no Google Sheets, talvez você nem precise de um webhook: o complemento QRFLOW for Google Sheets cria um código por linha e grava o link curto e a contagem de leituras de volta na planilha, no Premium, sem chave de API. Consulte o complemento do Google Sheets.
Programação por vibe
Prompts para colar
Assistentes de programação criam a solução certa quando recebem as regras de antemão. Estes prompts incluem as regras. Cole um deles, preencha o trecho entre colchetes e o assistente lerá a referência em Markdown antes de escrever qualquer linha.
Adicione códigos QR ao meu app
Claude, ChatGPT, Cursor, Codex, Windsurf, Copilot Chat: cole no 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"].
Ensine seu repositório sobre o QRFLOW
Adicione a CLAUDE.md, AGENTS.md,.cursorrules ou.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.
No Lovable, Bolt, v0, Replit e outros criadores de apps
Criadores que priorizam o front-end e fornecem um backend (Supabase, funções 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
Um GPT personalizado que gerencia meus 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).
O que dizer depois de conectar o conector
Claude, ChatGPT, Claude Code com o servidor MCP do 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
Use com Claude, ChatGPT, Cursor e Claude Code
O QRFLOW é um servidor MCP em https://qrflow.codes/mcp. Conecte-o uma vez, entre na sua conta e diga coisas como "crie um código QR para a página do nosso menu de outono, chamado menu no meu domínio", "aponte o código do pôster do saguão para a nova página" ou "quantas leituras o folheto teve na semana passada, por país?". O assistente recebe as mesmas ferramentas oferecidas por esta API, sob as mesmas regras, e os códigos aparecem no seu painel com mcp como origem.
Não é desenvolvedor? A versão em linguagem simples, com as instruções exatas para cada assistente, está em Crie códigos QR com seu assistente de IA.
Avaliado de forma independente e verificado a cada hora pela Glama, além de listado no diretório awesome-remote-mcp-servers e no MCP Registry oficial como codes.qrflow/qrflow.
Conectar
Customize › Connectors › Add custom connector › cole o endereço ou pressione Connect na listagem do QRFLOW. O Claude abrirá uma tela de login do QRFLOW; pressione Allow. Funciona em todos os planos.
https://qrflow.codes/mcp
Settings › Security and login › ative Developer mode, depois Settings › Plugins › + › cole o endereço; entre na conta quando solicitado. Plus, Pro, Team, Enterprise e Edu.
https://qrflow.codes/mcp
Um comando e, em seguida, /mcp para entrar na conta. Adicione uma chave Business como cabeçalho para ignorar o login.
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, qualquer cliente MCP
Adicione um servidor HTTP no URL. O login OAuth acontece no navegador; ou passe um cabeçalho Authorization com uma chave.
{
"mcpServers": {
"qrflow": { "type": "http", "url": "https://qrflow.codes/mcp" }
}
}
Seu próprio agente (Anthropic ou OpenAI SDK)
Aponte o conector ou a ferramenta MCP para o URL com uma chave Business como bearer; não é necessário fluxo pelo navegador.
// Anthropic Messages API, MCP connector
mcp_servers: [{ type: "url", url: "https://qrflow.codes/mcp", name: "qrflow", authorization_token: process.env.QRFLOW_KEY }]
O que o assistente pode fazer
| Ferramenta | O que faz | Escopo |
|---|---|---|
| list_code_kinds | Todos os tipos de código, com seus campos e o plano necessário. O assistente chama esta ferramenta antes de criar algo incomum. | profile |
| list_domains | Seus domínios de link, o padrão e seus ids. | domains:read |
| get_qr_image | Uma imagem PNG que o assistente pode mostrar ou salvar, além do URL SVG para impressão. | codes:read |
| get_account | O plano, os recursos e os limites da conta. | profile |
Como ele se mantém seguro
- O assistente só mantém um token da sua conta, emitido depois que você pressionou Allow em uma página do QRFLOW. Desconecte-o a qualquer momento em Account › Connected apps.
- Os tokens são vinculados ao servidor MCP; não podem ser reutilizados na API REST.
- Toda gravação passa pela mesma validação do painel: destinos permitidos, verificações do plano e limites de uso justo.
- As ferramentas destrutivas se descrevem com cuidado:
delete_qr_codeinstrui o modelo a preferir pausar quando houver uma impressão. - Os documentos de descoberta estão em
/.well-known/oauth-authorization-servere/.well-known/oauth-protected-resource; o registro segue a RFC 7591; somente PKCE S256.
SDKs e a especificação OpenAPI
- TypeScript / JavaScript:
npm install qrflow(npm). Zero dependências, ESM e CommonJS, tipagem completa; funciona no Node 18+, Bun, Deno e Workers. Tenta novamente em caso de 429 e incluiverifyWebhook/parseWebhook. - Python 3.9+, apenas biblioteca padrão: qrflow.py.
- OpenAPI 3.1: /api/v1/openapi.json. Importe para o Postman ou Insomnia, gere um cliente em qualquer linguagem ou anexe a uma Action do ChatGPT.
- Ambos os clientes lançam um erro tipado (
QRFlowErrorcomstatus,code,message,retryAfter) e incluem um verificador de webhook. O código TypeScript em arquivo único continua em /sdk/qrflow.ts caso prefira incluí-lo diretamente no seu projeto.
| TypeScript | Python | Chamadas |
|---|---|---|
| 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) | O endereço da imagem (busque-o com a chave) |
| verifyWebhook(raw, header, secret) | verify_webhook(raw, header, secret) | Verificação de assinatura das entregas |
Referência dos endpoints
URL base https://qrflow.codes/api/v1. Corpos e respostas são JSON. As datas estão em ISO 8601 UTC. Envie apenas os campos alterados em PATCH.
GETprofile
Plano, sinalizadores de recursos e limites aplicáveis a esta conta, além dos escopos da chave.
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) e cerca de 50 subtipos (Instagram, avaliação do Google, Wi-Fi, loja de aplicativos…), cada um com os campos necessários e o plano exigido. Não precisa de chave.
curl https://qrflow.codes/api/v1/catalog
GETcodes:read
Do mais recente ao mais antigo.?limit= até 100,?q= pesquisa os rótulos.
curl "https://qrflow.codes/api/v1/codes?limit=20&q=menu" \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTcodes:write
As mesmas regras de Salvar no site: códigos de url, phone, email, sms e location são dinâmicos nos planos pagos; Wi-Fi, vCard e text incluem o conteúdo no padrão. Informe um id de subtipo em destination_data.subtype para criar, por exemplo, um código de avaliação do Google. O domain_id opcional escolhe qual dos seus domínios de link será usado no código (GET /domains lista os domínios).
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
O código com a contagem de leituras, o link curto e o endereço da imagem.
curl https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
PATCHcodes:write
Qualquer um destes campos: destination_data (somente códigos dinâmicos; a impressão continua válida), label, paused, expires_at (ISO ou null), slug (um nome de link no seu domínio), domain_id (qual dos seus domínios de link será usado neste código; null = padrão da conta), fg_color, bg_color, frame_style, frame_caption, frame_caption2. Envie apenas os campos que deseja alterar.
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
Excluído permanentemente, incluindo o histórico de leituras. O link impresso de um código dinâmico deixa de funcionar. Prefira paused: true se o código ainda estiver em circulação.
curl -X DELETE https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
POSTcodes:write
O padrão impresso muda (agora codifica o link curto), então gere a imagem novamente depois.
curl -X POST https://qrflow.codes/api/v1/codes/$ID/dynamic \
-H "Authorization: Bearer $QRFLOW_KEY"
GETcodes:read
SVG pronto para impressão, com moldura e cores.?size= define a largura da grade de módulos em px; o arquivo pode ser redimensionado sem perda de qualidade.
curl https://qrflow.codes/api/v1/codes/$ID/image.svg \
-H "Authorization: Bearer $QRFLOW_KEY" -o code.svg
GETanalytics:read
?from= e?to= (datas ISO, até 92 dias; o padrão são os últimos 30) e?group= day, device, country, city, browser, os ou referrer. Os mesmos números da página de análises.
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
Até 2.000 códigos de URL em uma chamada, todos dinâmicos. Conta para o mesmo limite mensal de operações em lote da página Bulk (10.000 no Business). Linhas que não forem endereços da web aparecem em rejected; as demais são criadas.
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
Os códigos usados em embalagens de varejo. Cada produto corresponde a um GTIN, ao endereço impresso na embalagem e aos links associados. Pesquise nomes e GTINs com?q=. Plano 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 e name são obrigatórios; brand e url são opcionais. O dígito verificador é validado antes de qualquer gravação, e os formatos de 8, 12, 13 e 14 dígitos são normalizados para 14. Um GTIN que você já possui retorna 409 em vez de criar um segundo produto.
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
Um GTIN pode levar a vários destinos ao mesmo tempo, cada um identificado pela sua finalidade. Um telefone recebe o destino padrão; um aplicativo que solicita um tipo recebe aquele destino. Idempotente: o mesmo link_type e batch substitui esse link em vez de adicionar outro, então um script noturno pode ser executado duas vezes. Informe batch para associar o link a um único lote, permitindo publicar um recall sem afetar o restante da produção.
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
Contagem por GTIN para os últimos?days= (de 1 a 365, padrão 30), detalhada por país, dispositivo, tipo de link e lote. went_nowhere conta as leituras sem destino encontrado e deve ser zero.
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
Seus domínios conectados, o status deles e qual deles é usado por padrão nos códigos dinâmicos (default_base). Informe o id de um domínio como domain_id em um código para usar outro domínio.
curl https://qrflow.codes/api/v1/domains \
-H "Authorization: Bearer $QRFLOW_KEY"
GETwebhooks:manage
Seus webhooks, com os eventos, o último status e a contagem de falhas.
curl https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTwebhooks:manage
url deve usar https em um host público; events pode ser qualquer combinação de scan, code.created, code.updated, code.deleted. O segredo de assinatura é retornado uma única 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
Envia um ping assinado agora e informa a resposta.
curl -X POST https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
DELETEwebhooks:manage
Interrompe todas as entregas, incluindo as novas tentativas na fila.
curl -X DELETE https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
GETpublic
IDs das molduras e o que cada uma exige (legenda, segunda linha), agrupados como no personalizador. Não precisa de chave.
curl https://qrflow.codes/api/v1/frames
O objeto Code
Todos os endpoints que interagem com um código retornam a mesma estrutura. Ignore os campos que você não conhece; novos campos são adicionados com o tempo.
| Campo | Tipo | Significado |
|---|---|---|
| id | uuid | ID estável. Use-o em todas as outras chamadas. |
| label | string | null | O nome no painel. Até 120 caracteres. Pesquisável com?q=. |
| kind | string | O ID do catálogo: url, wifi, instagram, googlereview,... kind_label é o nome legível. |
| type | string | A codificação: url, text, wifi, vcard, email, phone, sms, location. |
| destination_data | object | Os campos enviados (mais subtype para os tipos). destination é um resumo em uma linha. |
| dynamic | boolean | True quando as leituras passam pelo QRFLOW e o destino pode mudar. dynamic_capable indica se esse tipo pode ser dinâmico em um plano pago. |
| short_code | string | Sete caracteres, nunca muda. |
| short_url | string | O que imprimir para um código dinâmico. Inclui seu domínio e slug, se definidos. |
| domain_id | uuid | null | Qual domínio de link é usado neste código; null significa o padrão da conta. |
| fg_color, bg_color | hex | Cores dos módulos e do fundo. |
| has_logo | boolean | Um logotipo foi adicionado no painel; image.svg o inclui. |
| frame_style, frame_caption, frame_caption2 | string | null | ID da moldura e legendas, como no personalizador. |
| scans | integer | Contagem total de leituras. |
| created_at, updated_at | ISO 8601 | UTC. |
| manage_url | url | A página do código no painel, para um link 'Abrir no QRFLOW'. |
| image_url | url | GET /codes/:id/image.svg. Requer o cabeçalho Authorization; não é um URL de imagem público. |
| svg_download_url, png_download_url | url | O mesmo SVG (moldura, cores, logotipo) e um PNG simples, por meio de links assinados que funcionam por 24 horas sem cabeçalho: para <img> tags, scripts e assistentes que salvam um arquivo. download_expires_at informa quando expiram; qualquer leitura do código retorna links novos. |
Outras estruturas: 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, mais secret uma vez), Me (id, email, plan, paid, features, limits, auth, scopes) e Error (error, message). O documento OpenAPI tipa todas as propriedades.
Business
Webhooks
QRFLOW chama seu URL https quando algo acontece. Crie um em Conta › Webhooks ou com POST /webhooks; o segredo de assinatura é fornecido uma única vez. Até 10 por conta.
| Evento | Quando | data |
|---|---|---|
| scan | Agrupado: a cada poucos minutos, todas as novas leituras desde a última entrega, até 500 por chamada. | count, from, to, scans[] com code_id, label, short_code, slug, scanned_at, device, country, city, referrer, browser, os, language |
| code.created | Imediatamente pela API e pelos assistentes; em alguns minutos pelo painel. Uma solicitação em lote envia um evento com bulk: true e codes[]. | code, source |
| code.updated | Mesmo prazo. Abrange destino, rótulo, pausa, expiração, nome do link, domínio, cores, moldura e conversão para dinâmico. | code, changed[] (os nomes dos campos alterados) |
| code.deleted | Mesmo prazo. | code: { id, label, short_code, slug } |
| ping | Quando você clica em Testar. | webhook_id, message |
O que chega
Cada payload é { id, event, created_at, data }. id permanece estável nas novas tentativas de uma entrega, permitindo deduplicá-las com esse valor.
{
"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 a assinatura
X-QRFLOW-Signature: t=<unix seconds>,v1=<hex>. Calcule HMAC-SHA256 sobre ${t}.${rawBody} com seu segredo e compare com v1 em tempo constante; rejeite se t tiver mais de cinco minutos. Use os bytes brutos recebidos, nunca um objeto serializado novamente. Há receptores funcionais para Next.js e Python nas receitas, e ambos os SDKs incluem o auxiliar.
Regras de entrega
- Responda com qualquer status 2xx em até 8 segundos. Faça o trabalho depois de responder.
- Qualquer outra resposta será seguida de novas tentativas após 1, 5, 15, 60, 240 e 720 minutos.
- Vinte falhas consecutivas desativam o webhook e enviam um e-mail ao proprietário da conta. Reative-o depois de corrigir o receptor; as novas tentativas na fila serão retomadas.
- Os URLs devem usar https em um host público. localhost, intervalos privados e o próprio qrflow.codes são recusados. Use um túnel durante o desenvolvimento.
- Clique em Testar para receber um
pingassinado e ver o status respondido pelo seu servidor.
Erros
Todo erro é { "error": "<code>", "message": "<what to do>" } com o status abaixo. A mensagem é escrita para uma pessoa; mostre-a.
| Status | error | Significado |
|---|
Sintoma, causa, solução
Solução de problemas
401 invalid_token em todas as chamadas
Por quêO cabeçalho está incorreto ou a chave não está ativa.
SoluçãoEnvie exatamente Authorization: Bearer qrf_live_… (um espaço, não dois-pontos). Verifique se a chave não foi revogada em Conta › API keys. Se você a copiou de um chat ou documento, confira se há um ponto final ou aspas curvas.
401 em /api/v1 com um token que funciona no servidor MCP
Por quêOs tokens emitidos para https://qrflow.codes/mcp estão vinculados a ele.
SoluçãoUse uma chave de API para REST ou execute um segundo fluxo OAuth sem resource= para obter um token para a API REST.
402 upgrade_required ao criar uma chave ou um webhook
Por quêAmbos são recursos do Business.
SoluçãoFaça upgrade em /pricing ou use o servidor MCP, que funciona em todos os planos por meio do login.
402 em POST /codes de um aplicativo OAuth
Por quêO plano do usuário não inclui o que o aplicativo solicitou (um código dinâmico, um domínio).
SoluçãoLeia primeiro os recursos de GET /me e adapte-se: crie o código mesmo assim (ele será estático no Free) ou informe ao usuário o que o plano exige.
403 insufficient_scope
Por quêOs escopos são definidos quando uma chave é criada. CorrijaCrie uma nova chave com os escopos necessários e revogue a antiga. Para OAuth, solicite o escopo na requisição de autorização.
400 not_dynamic ao fazer PATCH destination_data
Por quêO código é estático: um tipo Wi-Fi/vCard/texto ou um código criado no plano Free depois que o único código dinâmico gratuito já foi usado.
CorreçãoPara url/phone/email/sms/location, faça POST /codes/:id/dynamic enquanto a conta tiver cota disponível; depois, baixe e imprima novamente (a imagem muda). Wi-Fi, vCard e texto nunca podem ser dinâmicos; crie um código url que abra uma página.
400 no_domain ao definir slug
Por quêOs nomes dos links ficam no seu domínio.
CorreçãoConecte e verifique um domínio primeiro na página Account. Em qrflow.codes/q, o caminho é sempre o short_code.
409 conflict em slug
Por quêOutro código seu já tem esse nome.
CorreçãoUse GET /codes?q= para encontrá-lo ou escolha outro nome. Os nomes são por conta, não globais.
Erro de CORS no console do navegador
Por quêA API só aceita chamadas de servidor para servidor (e do Canva). Isso é intencional: uma chave em uma página da web é uma chave exposta.
CorreçãoMova a chamada para um route handler, server action, edge function ou backend e faça a chamada a partir daí.
A imagem mostra uma marca QRFLOW
Por quêO código foi criado por alguém que não está conectado. A marca aparece apenas em downloads anônimos.
CorreçãoQualquer conta a remove, inclusive a gratuita. Imagens de códigos salvos nunca a exibem.
short_url ainda mostra qrflow.codes/q/… depois que adicionei meu domínio
Por quêO domínio ainda não foi verificado ou o CNAME está incorreto.
CorreçãoConfira o status na página Account ou use GET /domains (o status deve ser verified). Os códigos existentes mudam automaticamente quando isso acontecer.
image_url retorna 401 em uma tag <img>
Por quêÉ necessário o cabeçalho Authorization, que uma <img> não pode enviar.
CorreçãoUse svg_download_url ou png_download_url do mesmo objeto Code: links assinados que funcionam por 24 horas sem cabeçalho. Para algo permanente, faça proxy de image_url pelo seu servidor (consulte a receita para Next.js) ou codifique short_url você mesmo.
Preciso de um PNG, não de um SVG
Por quêO SVG inclui moldura e logotipo; o PNG é o código simples.
CorreçãoGET /codes/:id/image.png (com bearer ou o png_download_url assinado) retorna um PNG de 256 a 2048 px. Para um PNG com a moldura, converta o SVG com sharp ou resvg (sharp(svgBuffer).png().toBuffer()).
Meu assistente disse que o endpoint de imagem recusou a solicitação e desenhou o código por conta própria
Por quêEle buscou image_url, que exige um bearer.
CorreçãoAgora, todo código inclui png_download_url e svg_download_url, e get_qr_image os retorna; o assistente pode usar curl nesses links sem entrar na conta. Um código desenhado localmente que codifica o mesmo short_url ainda funciona e contabiliza as leituras, mas não tem moldura nem logotipo.
O webhook nunca chega
Por quêRegras da URL ou o receptor.
CorreçãoA URL deve usar https em um host público (sem localhost, IPs privados ou qrflow.codes). Pressione Test no webhook: o resultado mostra o status retornado pelo seu servidor. Os eventos de leitura são agrupados e podem levar até cerca de cinco minutos; os eventos code.* do painel também ficam na fila por alguns minutos, enquanto as gravações via API e MCP são entregues imediatamente.
A assinatura nunca é validada
Por quêVocê assinou um corpo serializado novamente.
CorreçãoValide usando os bytes brutos exatos que recebeu, antes de analisar o JSON. No Express, use express.raw({ type: 'application/json' }) nessa rota; no Next.js App Router, use await req.text(); no Flask, request.get_data(). Em seguida, calcule HMAC-SHA256 de ${t}.${raw}\.
O webhook foi desativado sozinho
Por quêVinte falhas consecutivas.
CorreçãoCorrija o receptor e ative-o novamente (Account › Webhooks ou exclua e recrie). Você recebeu um e-mail quando isso aconteceu. As tentativas pendentes serão retomadas.
Entregas duplicadas de webhook
Por quêUma resposta 2xx lenta (mais de 8 segundos) conta como falha e é repetida.
CorreçãoResponda primeiro e processe depois. Elimine duplicatas usando o id do payload, que permanece estável entre as tentativas.
429 rate_limited durante uma importação
Por quê600 requisições por minuto por chave.
CorreçãoUse POST /codes/bulk (2.000 códigos em uma requisição) em vez de um POST por código, ou aguarde o número de segundos indicado em Retry-After.
Excluí um código e o pôster impresso agora mostra 'Code not found'
Por quêA exclusão é permanente e invalida o link.
CorreçãoNão é possível desfazer. Da próxima vez, use PATCH { paused: true }; um código pausado mostra uma página amigável e pode ser reativado.
Minha chave parou de funcionar depois que mudei para um plano inferior
Por quêAs chaves continuam funcionando por 30 dias após a saída do Business e, depois, retornam 402.
CorreçãoAssine novamente; nada foi excluído e as mesmas chaves voltarão a funcionar.
Algo que não está na lista? hello@qrflow.codes, com a requisição exata e o erro JSON recebido. Contas Business têm prioridade.
Limites e uso justo
| Limite | |
|---|---|
| Requisições por minuto, por chave | 600. Acima disso, 429 com Retry-After. |
| Chaves por conta | 10 |
| Webhooks por conta | 10 |
| Códigos salvos (uso justo) | 1.000 Premium, 25.000 Business; a API para no dobro desse limite. |
| Lote | 500/mês (500 por requisição) Premium; 10.000/mês (2.000 por requisição) Business. |
| Domínios de link | 1 Premium, 5 Business |
| Leituras | Ilimitadas. No Premium, um e-mail de aviso ao atingir 100.000 leituras por código por mês; no Business, 1.000.000; nada é limitado. |
| Janela de análise de leituras | 92 dias por requisição |
| Tamanho da página de listagem | 100 (?limit=) |
| Label / captions / slug | 120 / 60 / 40 caracteres |
| Tempo limite e novas tentativas do webhook | 8 segundos; novas tentativas após 1, 5, 15, 60, 240 e 720 minutos; desativado após 20 falhas consecutivas. |
| Após sair do Business | Chaves e webhooks continuam funcionando por 30 dias e, depois, retornam 402. Nada é excluído. |
O uso justo corresponde ao que o plano foi precificado para atender. Nada é limitado ao atingir esse número; a API para no dobro dele e alguém envia um e-mail antes. Para volumes maiores: hello@qrflow.codes.
Segurança, para você e para quem faz a leitura
Como o QRFLOW protege sua conta
- As chaves são exibidas uma única vez e armazenadas como hashes SHA-256. Ninguém na QRFLOW pode recuperar uma chave; se você a perder, crie outra.
- Cada requisição é vinculada à conta à qual a chave pertence. Um id de código de outra conta retorna 404, nunca expõe dados.
- Os escopos são fixos por chave, então uma chave de um painel de relatórios não pode criar nem excluir códigos.
- 600 requisições por minuto por chave; acima disso, um 429 claro, sem deixar todo mundo mais lento.
- Os destinos são permitidos por lista: http, https, mailto, tel, sms, geo e uma lista curta de esquemas de aplicativos (whatsapp, tg, signal, spotify, lojas de aplicativos). javascript:, data: e file: são rejeitados na criação, para que uma integração comprometida não transforme seus códigos em um ataque.
- As URLs de webhook devem usar https em hosts públicos; a QRFLOW nunca chama redes privadas nem a si mesma. Cada entrega é assinada e cada payload tem um id estável.
- Clientes OAuth são registrados com PKCE S256 e os tokens são vinculados ao servidor para o qual foram emitidos; um token do servidor MCP não pode ser reutilizado na API REST.
- Qualquer pessoa pode revogar uma chave ou desconectar um aplicativo na página Account; o efeito é imediato.
O que fazer do seu lado
- Use variáveis de ambiente, nunca o código-fonte. Se uma chave aparecer no histórico do git, revogue-a.
- Somente no servidor. A API recusa origens de navegador, mas seus próprios endpoints que a encapsulam também precisam de autenticação; caso contrário, qualquer pessoa pode criar códigos na sua conta.
- Dê a cada integração sua própria chave, com os escopos necessários e um nome que identifique a integração. Assim, revogar uma chave afeta apenas uma coisa.
- Valide as assinaturas dos webhooks e rejeite timestamps com mais de cinco minutos.
- Se os dados dos seus usuários forem incluídos em labels ou destinos, lembre-se de que a QRFLOW os armazena; evite incluir dados pessoais em labels sempre que possível.
O que as leituras registram e o que não registram
- Cada redirecionamento armazena tipo de dispositivo, país, cidade, referenciador, navegador, sistema operacional e idioma, derivados da requisição, além de um hash unidirecional de código + dia + IP + user agent para que o proprietário possa contar visitantes únicos. Não é possível reverter o hash para obter um endereço.
- Nenhum cookie é definido para quem faz a leitura, e o endereço IP em si não é mantido junto à leitura. Bots conhecidos e rastreadores de pré-visualização de links são ignorados.
- Excluir um código exclui suas leituras. Excluir a conta exclui tudo.
- Texto completo: https://qrflow.codes/privacy e https://qrflow.codes/terms.
Versionamento e estabilidade
A API é versionada no caminho: /api/v1. Dentro da v1, adicionamos campos, endpoints, tipos e eventos; não removemos nem renomeamos nada, e seu código deve ignorar campos desconhecidos nas respostas.
Se alguma alteração precisar quebrar a v1, ela será lançada como /api/v2, e a v1 continuará funcionando por pelo menos doze meses. Os proprietários das chaves recebem um e-mail sobre descontinuações com 90 dias de antecedência.
O servidor MCP segue a mesma regra para suas ferramentas: apenas adicionamos argumentos, e cada ferramenta mantém seu nome.
O documento OpenAPI em /api/v1/openapi.json e o Markdown em /llms-full.txt são gerados a partir do código que atende à API, portanto descrevem o que está ativo hoje.
Perguntas frequentes de desenvolvedores
Preciso pagar para usar a API QRFLOW?
As chaves de API estão incluídas no plano Business, por US$ 29 por mês, com cobrança mensal. O servidor MCP (Claude, ChatGPT, Cursor, Claude Code) e o OAuth para seu próprio aplicativo funcionam em todos os planos por meio do login, e o que podem criar depende do plano. GET /catalog, GET /frames e /preview.svg não precisam de chave.
Posso gerar códigos QR gratuitamente pela API?
Não com uma chave. Para uma imagem estática simples, o gerador gratuito em qrflow.codes ou qualquer biblioteca QR de código aberto resolve. A API é para códigos dinâmicos, seu próprio domínio, análises, operações em lote e webhooks, recursos incluídos em uma conta paga.
Posso chamar a API pelo navegador?
Não. Ela recusa origens de navegador para que uma chave nunca acabe em uma página da web. Chame-a de um route handler, server action, edge function ou backend e faça a chamada a partir da sua página.
Quais formatos de imagem posso obter?
SVG com suas cores, moldura, legendas e logotipo (GET /codes/:id/image.svg, nominalmente de 256 a 4096 px) e um PNG simples (GET /codes/:id/image.png, de 256 a 2048 px). Ambos aceitam um bearer ou o svg_download_url / png_download_url assinado que todo objeto Code inclui; esses links funcionam por 24 horas sem cabeçalho. A ferramenta MCP get_qr_image retorna o PNG em linha e os dois links.
Posso alterar um código QR depois de impresso?
Sim, se for dinâmico (url, phone, email, sms, location em um plano pago). Use PATCH /codes/:id com um novo destination_data; a imagem não muda, mas a próxima leitura leva ao novo destino. Os códigos Wi-Fi, vCard e texto incluem o conteúdo na imagem e não podem ser alterados.
Qual é a diferença entre short_url e o destino?
short_url é o link dentro da imagem (go.example.com/menu). O destino é para onde esse link redireciona (https://example.com/menu-fall). Você imprime short_url uma vez e pode alterar o destino quantas vezes quiser.
Os códigos podem usar meu próprio domínio?
Sim. O Premium conecta 1 domínio e o Business, 5; você adiciona um CNAME e verifica o domínio na página Account. No Business, você escolhe um domínio por código com domain_id. Os nomes de link (slug) criam caminhos legíveis nele.
O que uma leitura registra sobre quem está lendo?
Tipo de dispositivo, país, cidade, referenciador, navegador, sistema operacional e idioma, obtidos da requisição, além de um hash diário unidirecional para contar visitantes únicos. Sem cookies, e o endereço IP não é armazenado. O suficiente para um gráfico, mas não para identificar alguém. Detalhes: https://qrflow.codes/privacy#scans
Existe um pacote npm ou PyPI?
npm: npm install qrflow\ (https://www.npmjs.com/package/qrflow), sem dependências, ESM e CommonJS, tipos TypeScript completos, compatível com Node 18+, Bun, Deno e Workers; encapsula todos os endpoints, repete requisições após 429 e inclui verifyWebhook/parseWebhook. Python: um cliente em arquivo único em https://qrflow.codes/sdk/qrflow.py (somente biblioteca padrão) com verify_webhook; um pacote PyPI será lançado em breve.
Funciona com Claude, ChatGPT, Cursor e Claude Code?
Sim. O QRFLOW é um servidor MCP em https://qrflow.codes/mcp. Adicione-o como conector, entre na conta uma vez e faça solicitações em linguagem natural. Onze ferramentas abrangem criação, edição, pausa, nomeação, operações em lote, análises, imagens e domínios.
Meus próprios usuários podem conectar suas contas QRFLOW ao meu aplicativo?
Sim, com OAuth 2.0. Registre um cliente em /api/oauth/register (não é necessária uma conta), envie os usuários para /oauth/authorize com PKCE e chame a API com o token deles. Os códigos ficam na conta deles, de acordo com o plano.
Como testo webhooks no localhost?
Exponha seu servidor de desenvolvimento com um túnel (cloudflared ou ngrok) e use o endereço https dele como URL do webhook. Em seguida, clique em Testar em Conta › Webhooks para receber um ping assinado. As URLs de webhook precisam ser públicas e usar https; endereços localhost e privados são recusados.
O que acontece com minha integração se eu cancelar o Business?
As chaves e os webhooks continuam funcionando por 30 dias e, depois, retornam 402. Os códigos, as digitalizações e os domínios permanecem na conta. Ao assinar novamente, tudo volta a funcionar com as mesmas chaves.
Como crio um código de avaliação do Google, Instagram, Wi-Fi ou PDF pela API?
GET /catalog lista todos os tipos e seus campos. Em seguida, faça POST /codes com o type e os campos do tipo, adicionando subtype para estes 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' } }.
A API pode enviar um logotipo para um código?
Ainda não. Adicione o logotipo no painel; image.svg o inclui e has_logo informa se ele está presente. As cores, as molduras e as legendas podem ser definidas pela API.
A API é estável?
A v1 só adiciona; nunca remove nem renomeia. Uma alteração incompatível seria lançada como v2, mantendo a v1 ativa por pelo menos doze meses e com aviso por e-mail com 90 dias de antecedência.
Para agentes, ferramentas e assistentes que estão lendo isto
Legível por máquina
Tudo nesta página existe em um formato que softwares podem buscar. Tudo é gerado a partir do código que serve a API, portanto nunca fica desatualizado.
| URL | O que é | |
|---|---|---|
| llms-full.txt | https://qrflow.codes/llms-full.txt | Esta referência completa em Markdown: conceitos, todos os endpoints, todas as ferramentas MCP, receitas, solução de problemas e perguntas frequentes. Gerada a partir da mesma fonte que esta página. |
| developers.md | https://qrflow.codes/developers.md | O mesmo documento, para ferramentas que buscam a.md. |
| llms.txt | https://qrflow.codes/llms.txt | O índice do site para assistentes, que aponta para cá. |
| A API em uma página | https://qrflow.codes/qr-code-api | O que a API faz, quando uma biblioteca do lado do cliente é a melhor opção e quanto custa. A versão resumida desta referência, para decidir em vez de implementar. |
| openapi.json | https://qrflow.codes/api/v1/openapi.json | OpenAPI 3.1. Importe para Postman, Insomnia, um gerador de código ou uma ChatGPT Action. |
| Servidor MCP | https://qrflow.codes/mcp | HTTP transmitível, OAuth com registro dinâmico ou uma chave Business como bearer. |
| server.json | https://qrflow.codes/.well-known/mcp/server.json | O manifesto do registro MCP. |
| Descoberta OAuth | https://qrflow.codes/.well-known/oauth-authorization-server | Metadados RFC 8414; o documento do recurso protegido fica ao lado. |
| Pacote npm | https://www.npmjs.com/package/qrflow | npm install qrflow. Cliente tipado, sem dependências, com verificação de webhook. Cliente Python em arquivo único em https://qrflow.codes/sdk/qrflow.py. |
| GitHub | https://github.com/nativecodeapps/qrflow-sdk | Clientes, snapshot do OpenAPI e exemplos executáveis para webhooks com Next.js, Workers, Express, FastAPI e Flask. Contribuições com issues e PRs são bem-vindas. |
Dúvidas, ideias ou sugestões de tipos de código que deveríamos adicionar: hello@qrflow.codes. Termos: /terms. Privacidade: /privacy.