API de código QR: criar, alterar e analisar códigos QR automaticamente

Para que serve uma API de código QR

Uma API de código QR é uma interface de programação: em vez de clicares no navegador, o teu programa envia pedidos ao serviço de códigos QR e recebe respostas. Assim, os códigos QR nascem diretamente de uma loja online, de um sistema de gestão, de um script ou de uma folha de cálculo.

Compensa assim que o trabalho se repete: cem códigos QR para mesas ou produtos, relatórios mensais de leituras, a mudança de muitos destinos depois de um relançamento. E só funciona com códigos QR dinâmicos. Um código QR dinâmico do Same-QR contém um endereço curto e constante, o destino por trás fica connosco e pode ser alterado em qualquer altura, sem imprimir de novo.

O que a API do Same-QR cobre

A API REST está em https://sameqr.com/api/v1. Chama as mesmas funções do painel, com os mesmos limites de plano e as mesmas verificações:

• Listar, ler, criar, alterar e apagar códigos QR.
• As estatísticas de um código QR: leituras, data de criação, número de alterações de destino.
• Criar, alterar, publicar e tirar do ar páginas de convidados como ementa, lista de preços, horários, página de ligações, promoção, adega, e-label de vinho e contacto.
• Ler uma ementa a partir de até sete fotos ou de um PDF.
• Gerir etiquetas e projetos de clientes e ler os pedidos dos formulários de contacto.

Uma descrição legível por máquina de todos os pedidos está em /api/v1/openapi.json, e as instruções em sameqr.com/entwickler.

Chaves de API e permissões

Crias a chave no painel, em Conta, na secção “Acesso para CLI, scripts e agentes”. Escolhes um de três níveis, “só leitura”, “leitura + escrita” (criar, alterar nomes e textos) ou “total” (além disso, alterar destinos, tirar do ar, apagar), e uma validade de 30, 90, 180 ou 365 dias, se necessário também ilimitada. A chave começa por sqr_live_ e é mostrada exatamente uma vez. Do nosso lado só é guardada uma soma de verificação.

Uma chave que só pode ler recebe uma recusa clara em qualquer pedido que altere algo. Para relatórios e análises, é a escolha certa. Tudo o que muda para onde leva um código QR impresso tem proteção adicional: alterar destinos, tirar do ar e apagar exigem o nível “total” e uma confirmação com o estado lido antes, e através da API são permitidos no máximo 10 por hora e 30 por dia. No painel não existe este limite. Cada chave pode ser revogada em qualquer altura e deixa logo de ser válida.

Um fluxo típico

A chave pertence ao cabeçalho Authorization, nunca a um endereço. Guarda primeiro a chave como variável de ambiente. Assim listas os teus códigos QR e alteras o destino de um código QR:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

O valor para X-Confirm, o estado, é fornecido pelo pedido de leitura em /api/v1/qr/<id>. Só é alterado o que enviares. Quem quiser ter a certeza de que ninguém alterou entretanto o mesmo código QR envia o estado lido como _rev. Se algo mudou, nada é substituído, e a resposta contém o estado atual. Os erros chegam sempre no mesmo formato, com estado, código QR e uma mensagem compreensível.

Limites e boas práticas

Por chave são permitidos no máximo 120 pedidos por minuto. A isto acresce um limite por hora que depende do plano: 60 no plano gratuito, 300 no Start, 1.000 no Pro e 5.000 no Agentur. Os limites apanham erros, como um script num ciclo infinito, e não atrapalham a utilização honesta.

• Experimenta primeiro com uma chave de leitura e só depois escreve.
• Testa novos fluxos num único código QR e lê-o com o telemóvel.
• Evita apagar onde um novo destino chega. Os códigos QR apagados e as suas ligações curtas não voltam.
• Cria uma chave própria para cada programa e guarda-a num gestor de palavras-passe ou numa variável de ambiente.

Conclusão: porquê o Same-QR

O Same-QR não te dá a API como um extra caro, mas em todos os planos, com as mesmas funções do painel: códigos QR, estatísticas, ementas, páginas de convidados, etiquetas e projetos. A isto juntam-se permissões claras por chave, mensagens de erro honestas e uma verificação noturna de todos os destinos que te avisa por e-mail quando algum está inacessível.

Começa já: regista-te de graça em sameqr.com, 20 códigos QR dinâmicos são gratuitos para sempre. API, CLI e servidor MCP existem em todos os planos, a documentação está em sameqr.com/entwickler.

Perguntas frequentes