QR for Agent

Servidor MCP de QR code dinâmico para agentes de IA — criar, atualizar, rastrear QR codes

Documentação

QR for Agent

API QR-as-a-Service construída para agentes de IA. Crie, atualize e acompanhe QR codes dinâmicos programaticamente via REST API ou MCP (37 ferramentas).

QR codes apontam para URLs curtas (/r/:shortId) que você pode redirecionar a qualquer momento — a imagem do QR nunca muda, mas a leitura leva ao novo destino. Multi-tenant por design, com análises completas de leituras.

API ao vivo: api.qrforagent.com | Site: qrforagent.com | MCP: qr-for-agent

Recursos

QR codes dinâmicos — altere a URL de destino sem regenerar a imagem
11 tipos de QR — URL, vCard, WiFi, E-mail, SMS, Telefone, Evento, Texto, Localização, Redes Sociais, App Store
Estilo personalizado — formatos de pontos (quadrado, arredondado, pontos, arredondado-clássico), estilos de cantos, cores, gradientes, incorporação de logotipo, molduras com texto de CTA
SVG & PNG — saída vetorial e bitmap
Análises enriquecidas — tipo de dispositivo, navegador, SO, país, cidade, referenciador, leituras por dia
Webhooks em tempo real — payloads assinados com HMAC-SHA256 com registro de entrega
Rastreamento UTM — anexa automaticamente parâmetros UTM às URLs de redirecionamento
Suporte a GTM — página intermediária com snippets do Google Tag Manager
Redirecionamentos condicionais — roteie por dispositivo, SO, país, idioma, intervalo de tempo ou divisão A/B
Domínios personalizados — usuários Pro personalizam URLs curtas com seu próprio domínio (qr.yourbrand.com/r/abc123)
Expiração e agendamento — expire QR codes automaticamente ou agende trocas de URL
Rastreamento de conversões — pixel de rastreamento + API para eventos pós-leitura (compras, inscrições) com análises de ROI
Molduras e modelos — molduras decorativas ao redor dos QR codes (banner_top, banner_bottom, arredondado) com texto de CTA
Operações em lote — crie, atualize ou exclua até 50 QR codes por solicitação, ou até 500 via upload de CSV (Pro)
Multi-tenant — cada chave de API vê apenas seus próprios dados
Servidor MCP — qr-for-agent com 37 ferramentas para Claude Desktop, Cursor, etc.
Cotas baseadas em plano — Gratuito (10 QR, 1K leituras/mês) e Pro ($19/mês, ilimitado)
Registro self-service — POST /api/register com e-mail, sem cartão de crédito
Integração Stripe — checkout, portal de cobrança, gerenciamento de plano orientado por webhook
Documentação OpenAPI — Swagger UI em /documentation
Detectável por IA — /.well-known/ai-plugin.json e /.well-known/mcp.json
Código aberto — licença MIT, hospedável via Docker

Início Rápido

git clone https://github.com/benswel/qr-for-agent-api.git
cd qr-for-agent-api
npm install
npm run dev

Na primeira inicialização, uma chave de API é gerada automaticamente e exibida no console.

curl -X POST http://localhost:3100/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY_HERE" \
  -d '{"target_url": "https://example.com", "label": "My first QR"}'

Endpoints da API

Gerenciamento de QR Codes (`X-API-Key` obrigatório)

Método	Caminho	Descrição
`POST`	`/api/qr`	Criar um QR code (11 tipos, estilo personalizado)
`GET`	`/api/qr`	Listar todos os QR codes (paginado)
`GET`	`/api/qr/:shortId`	Obter detalhes do QR code
`PATCH`	`/api/qr/:shortId`	Atualizar URL de destino, rótulo, UTM, GTM, regras de redirecionamento
`DELETE`	`/api/qr/:shortId`	Excluir QR code e suas análises
`GET`	`/api/qr/:shortId/image`	Baixar imagem do QR (regenerada com o estilo armazenado)
`POST`	`/api/qr/bulk`	Criar até 50 QR codes (tudo ou nada)
`PATCH`	`/api/qr/bulk`	Atualizar até 50 QR codes (sucesso parcial)
`DELETE`	`/api/qr/bulk`	Excluir até 50 QR codes (sucesso parcial)
`POST`	`/api/qr/bulk/csv`	Criar até 500 QR codes a partir de CSV (somente Pro)

Análises (`X-API-Key` obrigatório)

Método	Caminho	Descrição
`GET`	`/api/analytics/:shortId`	Estatísticas de leitura com detalhamentos por dispositivo, navegador, SO, país, cidade + conversões

Conversões (`X-API-Key` obrigatório)

Método	Caminho	Descrição
`POST`	`/api/conversions`	Registrar um evento de conversão para um QR code que você possui
`GET`	`/api/conversions/:shortId`	Obter estatísticas de conversão (totais, por_evento, por_dia, recentes)

Webhooks (`X-API-Key` obrigatório)

Método	Caminho	Descrição
`POST`	`/api/webhooks`	Registrar endpoint de webhook (retorna segredo HMAC)
`GET`	`/api/webhooks`	Listar todos os webhooks
`DELETE`	`/api/webhooks/:id`	Excluir um webhook

Domínio Personalizado (`X-API-Key` obrigatório, somente Pro)

Método	Caminho	Descrição
`GET`	`/api/domain`	Obter domínio personalizado atual e status de DNS
`PUT`	`/api/domain`	Definir domínio personalizado
`DELETE`	`/api/domain`	Remover domínio personalizado

Conta (`X-API-Key` obrigatório)

Método	Caminho	Descrição
`GET`	`/api/usage`	Uso atual e cota
`POST`	`/api/stripe/checkout`	Criar sessão de checkout Stripe (upgrade para Pro)
`POST`	`/api/stripe/portal`	Abrir portal de cobrança Stripe

Público (sem autenticação)

Método	Caminho	Descrição
`POST`	`/api/register`	Registro self-service de chave de API (com limite de taxa)
`GET`	`/r/:shortId`	Redirecionar para URL de destino (registra leitura)
`GET`	`/t/:shortId`	Pixel de rastreamento de conversão (retorna GIF 1×1)
`GET`	`/i/:shortId`	Servir imagem QR (com cache)
`GET`	`/health`	Verificação de saúde
`GET`	`/documentation`	Swagger UI
`GET`	`/.well-known/ai-plugin.json`	Manifesto de plugin de IA
`GET`	`/.well-known/mcp.json`	Manifesto de descoberta MCP

Admin (cabeçalho `X-Admin-Secret` obrigatório)

Método	Caminho	Descrição
`GET`	`/api/admin/keys`	Listar todas as chaves de API registradas
`GET`	`/api/admin/stats`	Métricas do painel

Autenticação

Todos os endpoints /api/* exigem um cabeçalho X-API-Key.

Formato: qr_ + string aleatória de 32 caracteres
Gerado automaticamente: na primeira inicialização se nenhuma chave existir
Multi-tenant: cada chave vê apenas seus próprios QR codes
Criar uma chave: npm run key:create "my-label"
Listar chaves: npm run key:list

Endpoints públicos (/r/*, /i/*, /health, /documentation, /.well-known/*) não exigem autenticação.

Servidor MCP

Publicado como qr-for-agent no npm. 37 ferramentas para agentes de IA gerenciarem QR codes nativamente.

npx qr-for-agent

Claude Desktop / Cursor

Adicione à sua configuração MCP (claude_desktop_config.json ou .cursor/mcp.json):

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://api.qrforagent.com"
      }
    }
  }
}

Ferramentas Disponíveis (37)

Ferramenta	Descrição
`create_qr_code`	Criar um QR code de URL com estilo personalizado opcional
`get_qr_code`	Obter detalhes do QR code por ID curto
`update_qr_destination`	Alterar para onde um QR code redireciona
`list_qr_codes`	Listar todos os QR codes com paginação
`delete_qr_code`	Excluir um QR code e suas análises
`get_qr_analytics`	Obter estatísticas de leitura e detalhamentos
`bulk_create_qr_codes`	Criar até 50 QR codes de uma vez
`bulk_update_qr_codes`	Atualizar até 50 QR codes de uma vez
`bulk_delete_qr_codes`	Excluir até 50 QR codes de uma vez
`create_vcard_qr`	Criar um QR code de contato vCard
`create_wifi_qr`	Criar um QR code de credenciais WiFi
`create_email_qr`	Criar um QR code de e-mail (mailto:)
`create_sms_qr`	Criar um QR code de SMS
`create_phone_qr`	Criar um QR code de chamada telefônica
`create_event_qr`	Criar um QR code de evento de calendário
`create_text_qr`	Criar um QR code de texto simples
`create_location_qr`	Criar um QR code de geolocalização
`create_social_qr`	Criar um QR code de links de redes sociais
`create_app_store_qr`	Criar um QR code inteligente de redirecionamento para app store
`update_vcard_qr`	Atualizar um QR code vCard
`update_wifi_qr`	Atualizar um QR code WiFi
`update_social_qr`	Atualizar um QR code de redes sociais
`update_app_store_qr`	Atualizar um QR code de app store
`create_webhook`	Registrar um endpoint de webhook
`list_webhooks`	Listar todos os webhooks registrados
`delete_webhook`	Excluir um webhook
`register`	Registrar-se para obter uma chave de API
`get_usage`	Obter uso atual e cota
`upgrade_to_pro`	Criar uma sessão de checkout Stripe
`manage_billing`	Abrir portal de cobrança Stripe
`set_utm_params`	Definir parâmetros de rastreamento UTM em um QR code
`set_redirect_rules`	Definir regras de redirecionamento condicional em um QR code
`set_custom_domain`	Definir ou remover domínio personalizado (Pro)
`get_custom_domain`	Obter domínio personalizado atual e status de DNS
`bulk_create_from_csv`	Criar até 500 QR codes a partir de dados CSV (Pro)
`record_conversion`	Registrar um evento de conversão pós-leitura
`get_conversions`	Obter estatísticas de conversão para um QR code

Configuração

Copie .env.example para .env e edite:

Variável	Padrão	Descrição
`PORT`	`3100`	Porta HTTP
`HOST`	`0.0.0.0`	Endereço de vinculação
`BASE_URL`	`http://localhost:3100`	URL pública (usada em URLs curtas)
`DATABASE_URL`	`./data/qr-agent.db`	Caminho do arquivo SQLite
`SHORT_ID_LENGTH`	`8`	Comprimento dos IDs curtos gerados
`ADMIN_SECRET`	(nenhum)	Segredo para endpoints de admin (cabeçalho `X-Admin-Secret`)
`STRIPE_SECRET_KEY`	(nenhum)	Chave secreta da API Stripe
`STRIPE_WEBHOOK_SECRET`	(nenhum)	Segredo de assinatura de webhook Stripe
`STRIPE_PRICE_ID`	(nenhum)	ID de preço Stripe para o plano Pro

Banco de Dados

SQLite com Drizzle ORM. Seis tabelas:

api_keys — armazenamento de chaves com rótulo, e-mail, plano (gratuito/pro), IDs Stripe, domínio personalizado
qr_codes — metadados do QR, URLs de destino, tipo/type_data, opções de estilo, UTM, GTM, regras de redirecionamento, expiração/agendamento
scan_events — rastreamento de leituras: timestamp, user-agent, referenciador, IP, dispositivo, navegador, SO, país, cidade
webhooks — endpoints de webhook por chave de API, segredo HMAC, eventos inscritos
webhook_deliveries — registro de entrega: status, código de resposta, mensagens de erro
conversion_events — rastreamento de conversões: nome do evento, valor, metadados, referenciador, IP, timestamp

npm run db:generate   # Generate migration from schema changes
npm run db:migrate    # Apply pending migrations
npm run db:studio     # Open Drizzle Studio (web UI)

As migrações são executadas automaticamente na inicialização do servidor.

Implantação

Docker

docker compose up -d

O banco de dados é persistido em um volume Docker.

Railway

O projeto inclui railway.toml e um Dockerfile multi-estágio. Conecte seu repositório GitHub ao Railway — ele compila e implanta automaticamente com verificações de saúde em /health.

Testes

195 testes de integração cobrindo todos os endpoints, autenticação, isolamento multi-tenant, tipos de QR, webhooks, operações em lote, domínios personalizados, molduras, conversões, upload de CSV e análises.

npm test           # Run all tests
npm run test:watch # Watch mode

Scripts

Script	Descrição
`npm run dev`	Iniciar servidor de desenvolvimento com recarga automática
`npm run build`	Compilar TypeScript
`npm start`	Executar servidor de produção
`npm test`	Executar suíte de testes
`npm run test:watch`	Testes em modo de observação
`npm run key:create`	Criar chave de API
`npm run key:list`	Listar chaves de API
`npm run db:generate`	Gerar migração
`npm run db:migrate`	Executar migrações
`npm run db:studio`	Abrir Drizzle Studio

Licença

MIT

QR for Agent

Documentação

QR for Agent

Recursos

Início Rápido

Endpoints da API

Gerenciamento de QR Codes (X-API-Key obrigatório)

Análises (X-API-Key obrigatório)

Conversões (X-API-Key obrigatório)

Webhooks (X-API-Key obrigatório)

Domínio Personalizado (X-API-Key obrigatório, somente Pro)

Conta (X-API-Key obrigatório)

Público (sem autenticação)

Admin (cabeçalho X-Admin-Secret obrigatório)

Autenticação

Servidor MCP

Claude Desktop / Cursor

Ferramentas Disponíveis (37)

Configuração

Banco de Dados

Implantação

Docker

Railway

Testes

Scripts

Licença

Gerenciamento de QR Codes (`X-API-Key` obrigatório)

Análises (`X-API-Key` obrigatório)

Conversões (`X-API-Key` obrigatório)

Webhooks (`X-API-Key` obrigatório)

Domínio Personalizado (`X-API-Key` obrigatório, somente Pro)

Conta (`X-API-Key` obrigatório)

Admin (cabeçalho `X-Admin-Secret` obrigatório)