Criar códigos QR pela API REST: guia com exemplos curl

Passo 1: Criar a chave

No painel, em Conta, na secção “Acesso para CLI, scripts e agentes”, crias uma chave. Para as primeiras tentativas basta “só leitura”. Escolhe uma validade curta, por exemplo 30 dias. A chave começa por sqr_live_ e só é mostrada uma vez. Guarda-a numa variável de ambiente, para não ficar no histórico da tua shell, por exemplo através do teu gestor de palavras-passe.

Passo 2: O primeiro pedido

A API está em https://sameqr.com/api/v1. A chave vai no cabeçalho Authorization, nunca no endereço:

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

O primeiro pedido mostra a tua conta, o teu plano e os teus limites, o segundo os teus códigos QR com identificador, nome, destino, etiquetas, número de leituras e a versão _rev.

Passo 3: Criar um código QR

Para criar precisas de uma segunda chave com “leitura + escrita”. Com uma chave de leitura, a API responde a pedidos que alteram dados com 403 e o código NUR_LESEN. Um novo código QR precisa, no mínimo, de um nome e de um destino:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Lê o novo código QR com o telemóvel antes de continuares. Para criar, o teu endereço de e-mail tem de estar confirmado, e o código QR conta para a quota do teu plano.

Passo 4: Alterar o destino

As alterações de destino têm uma proteção especial. Precisas de uma chave “total” e envias a versão atual do código QR no cabeçalho X-Confirm. A versão é devolvida pelo pedido de leitura:

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

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"}'

Só são alterados os campos enviados. Se a versão não coincidir, porque entretanto alguém alterou o código QR, nada é substituído. Pela API são permitidas no máximo 10 alterações de destino por hora e 30 por dia, no painel não existe este limite. No plano gratuito, o número de alterações de destino por código QR é limitado.

Passo 5: Compreender erros e limites

Os erros vêm sempre na mesma forma: um objeto error com status, code e message. Trata-os no teu programa, em vez de simplesmente continuares.

• 401: a chave falta, está errada, expirou ou foi revogada.
• 403: falta à chave o nível necessário, ou o teu plano não permite a ação.
• 400 com BESTAETIGUNG_FEHLT: para alterar o destino, passar a offline ou apagar falta o X-Confirm com a versão atual.
• 409: alguém alterou o código QR entretanto.
• 429: demasiados pedidos. Cada chave permite 120 por minuto, e por hora 60 no plano gratuito, 300 no Start, 1.000 no Pro e 5.000 no Agentur.

Todos os pedidos estão descritos em /api/v1/openapi.json, o guia está em sameqr.com/entwickler.

Conclusão: porquê o Same-QR

A API REST do Same-QR é organizada, bem documentada e está incluída em todos os planos. Faz tudo o que o painel faz, protege os códigos QR impressos de alterações acidentais de destino com confirmação e limites, permite chaves em três níveis e responde com erros que se compreendem.

Começa já: regista-te gratuitamente 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