Desenvolvedores
Referência de API e integrações
Tudo o que você precisa para chamar a API Business, gerenciar chaves e receber webhooks.
Autenticação
A API Business autentica cada requisição com uma chave de API. Envie-a no cabeçalho X-Api-Key ou como token Bearer no cabeçalho Authorization.
As chaves têm o prefixo qrg_ e são exibidas apenas uma vez, no momento da criação. Guarde-as em local seguro: não é possível recuperar uma chave depois.
Requisições sem uma chave válida retornam 401. Uma chave sem a permissão necessária recebe 403 com o erro insufficient_scope. Recursos fora do seu espaço de trabalho retornam 404, como se não existissem.
URL base
Todos os endpoints da API Business ficam sob o prefixo /v1.
Por exemplo, liste seus códigos QR em https://qr-global.com/api/v1/qr-codes.
- URL base resolvida
- https://qr-global.com
Endpoints
Todos os endpoints ficam sob /api/v1 e exigem uma chave com a permissão indicada.
| Método | Caminho | Permissão | O que faz |
|---|---|---|---|
| GET | /qr-codes | qr:read | Listar códigos QR (filtros: type, search, folder_id, tag, archived) |
| POST | /qr-codes | qr:write | Criar um código QR |
| POST | /qr-codes/bulk | qr:write | Criar até 100 códigos QR de uma vez |
| GET | /qr-codes/{id} | qr:read | Obter um código QR |
| PUT | /qr-codes/{id} | qr:write | Atualizar um código QR, sua pasta e suas etiquetas |
| DELETE | /qr-codes/{id} | qr:write | Excluir um código QR |
| GET | /qr-codes/{id}/image | qr:read | Renderizar a imagem (PNG ou SVG) |
| GET | /qr-codes/{id}/stats | analytics:read | Estatísticas de leituras |
| GET | /qr-codes/{id}/scans | analytics:read | Registro de leituras |
| GET | /folders | qr:read | Listar pastas |
| GET | /tags | qr:read | Listar etiquetas |
| GET | /webhooks | webhooks:manage | Listar inscrições em webhooks |
| POST | /webhooks | webhooks:manage | Inscrever-se em eventos |
| DELETE | /webhooks/{id} | webhooks:manage | Cancelar inscrição |
Uma descrição legível por máquina (OpenAPI 3.1) para Postman, geradores de código e ferramentas no-code: Baixar openapi.json
Chaves de API
Crie e revogue chaves na página Chaves de API do seu painel.
Cada chave pertence ao seu espaço de trabalho e herda o limite de requisições do seu plano.
A revogação de uma chave entra em vigor imediatamente.
Permissões (scopes)
Ao criar uma chave, dê a ela acesso total ou apenas as permissões de que a integração precisa. Uma chave sem uma permissão recebe 403 com o erro insufficient_scope e required_scope na resposta.
qr:read— Ler códigos QR- Listar e ver códigos QR, suas imagens, pastas e etiquetas.
qr:write— Gerenciar códigos QR- Criar códigos QR (também em massa), editar, mover entre pastas, etiquetar e excluir.
analytics:read— Ler análises- Estatísticas de leituras e o registro de leituras de cada código QR.
webhooks:manage— Gerenciar webhooks- Inscrever endpoints em eventos e cancelar as inscrições (Zapier, Make).
Chaves criadas antes da introdução das permissões mantêm o acesso total. O acesso total também abrange as permissões adicionadas depois.
Exemplos
Comandos curl prontos para copiar e colar. Substitua YOUR_API_KEY por uma chave da página Chaves de API.
Listar códigos QR
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
Criar um código QR
Envie o tipo de QR e o conteúdo; o servidor gera e armazena o código.
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"url","content":"https://example.com","display_name":"Example link"}'Renderizar uma imagem
Obtenha um arquivo PNG ou SVG pronto — passe ?format=png
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.png # SVG (vector, no size limit on scale): curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.svg
Exemplo de payload de webhook
{
"event": "qr.scan.created",
"timestamp": "2026-04-03T12:00:00+00:00",
"data": {
"qr_code_id": 7,
"qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
"type": "url",
"scan_id": 42,
"country": "UA",
"device_type": "mobile",
"scanned_at": "2026-04-03T12:00:00+00:00"
}
}Análise de leituras
GET /qr-codes/{id}/stats retorna totais, visitantes únicos, principais países, dispositivos, navegadores e leituras por dia. GET /qr-codes/{id}/scans retorna o registro de leituras, das mais recentes para as mais antigas, 50 por página (per_page até 100).
Ambos aceitam from e to (uma data como 2026-10-01 ou um timestamp completo) e timezone (UTC por padrão). Uma data sem hora abrange o dia inteiro nesse fuso horário.
Só fica disponível o período de histórico do seu plano: leituras mais antigas são excluídas. Endereços IP e user agents dos visitantes nunca são retornados.
Estatísticas de leituras de um período
curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Registro de leituras, segunda página
curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Pastas e etiquetas
GET /folders e GET /tags listam as pastas e etiquetas do seu espaço de trabalho. Envie folder_id e tags (slugs das etiquetas) ao criar ou atualizar um código QR: folder_id null tira o código da pasta, e tags substitui o conjunto inteiro.
Filtre a lista de códigos QR com ?folder_id= ou ?tag=.
Mover um código QR para uma pasta e etiquetá-lo
curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 4,
"tags": [
"campaign",
"priority"
]
}'Criação em massa
POST /qr-codes/bulk cria até 100 códigos QR em uma única requisição. Exige um plano com criação em massa, como a importação CSV no painel, e respeita o seu limite de códigos QR ativos.
Cada item é processado separadamente: a resposta lista cada item com o status created (e o novo código) ou failed (com error e errors). Não reenvie o lote inteiro, apenas os itens com falha.
Criar dois códigos QR
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"codes": [
{
"type": "url",
"content": "https://example.com/spring",
"display_name": "Spring flyer",
"tags": [
"campaign"
]
},
{
"type": "url",
"content": "https://example.com/menu",
"display_name": "Table menu",
"folder_id": 4
}
]
}'Inscrições em webhooks (REST hooks)
Zapier, Make e os seus próprios serviços podem se inscrever em eventos pela API: POST /webhooks com url e events, e DELETE /webhooks/{id} para cancelar a inscrição. São os mesmos endpoints que você vê na página Webhooks.
A resposta ao POST contém secret, exibido apenas uma vez: use-o para verificar o cabeçalho X-Webhook-Signature. Se você não enviar o seu próprio secret (16 caracteres ou mais), nós geramos um.
Eventos: qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. A inscrição exige um plano com webhooks; o cancelamento sempre funciona. Um espaço de trabalho pode ter até 25 endpoints.
Inscrever-se nas leituras
curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"qr.scan.created"
]
}'Cancelar inscrição
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Webhooks
Os webhooks enviam eventos para o seu endpoint assim que eles acontecem, sem que você precise fazer polling.
Configure os endpoints na página Webhooks do seu painel.
Cada entrega é assinada e, em caso de falha, repetida com backoff exponencial.
O evento scan é disparado quando alguém escaneia um dos seus códigos QR.
Inspecione as tentativas de entrega, os payloads e as respostas no registro de entregas.
Retorne um status 2xx para confirmar a entrega; qualquer outro status é tratado como falha.
Rastreamento de conversões
As conversões mostram ao teste A/B qual destino traz pedidos ou cadastros, não só leituras. Com a otimização automática ativada, o tráfego passa para a variante que converte melhor.
Adicione o script à página que o visitante vê após converter: confirmação do pedido, página de agradecimento ou de sucesso. Funciona em qualquer domínio e não exige chave de API.
Snippet
<script src="https://qr-global.com/c.js" async></script>
- Cada leitura adiciona à URL de destino um parâmetro assinado qrg_v, para vincular a conversão ao código QR e à variante.
- O script guarda o token em um cookie próprio por 30 dias, então a conversão conta mesmo que o visitante navegue antes por outras páginas.
- Cada leitura conta uma vez: recarregar a página de agradecimento não soma conversões.
- Funciona com códigos QR que redirecionam para uma página http(s).
Exportações
Exporte seus códigos QR, leituras, localizações e atividades em CSV na página Exportações.
As exportações usam a sessão do seu painel, não uma chave de API — abra-as com a sessão iniciada.
Dicas e erros comuns
- 401 Unauthorized — a chave de API está ausente ou é inválida. Verifique o cabeçalho X-Api-Key.
- 403 Forbidden — a chave não tem a permissão necessária (insufficient_scope) ou o seu plano não inclui o recurso (api_access_required, bulk_not_available, webhooks_not_available).
- 404 Not Found — o recurso não existe ou pertence a outro espaço de trabalho.
- 429 Too Many Requests — você atingiu o limite por minuto do seu plano. Aguarde o número de segundos indicado no cabeçalho Retry-After.
- Alguns recursos (como webhooks) dependem do seu plano. Faça upgrade se um endpoint retornar um erro de recurso.
- Ainda não há entregas de webhook? Escaneie um dos seus códigos QR para gerar uma.
- Entregas de webhook com falha são repetidas automaticamente; você também pode reenviá-las manualmente pelo registro de entregas.
- Os membros da equipe atuam dentro do seu espaço de trabalho; chaves e dados ficam vinculados ao proprietário do espaço.