API de códigos QR: como integrar a geração na sua web ou app

A API do codigo-qr.es tem dois tiers.

Endpoint público (sem conta):

`POST /api/v1/qr/render` gera um QR estático e retorna a imagem em base64. Limite: 50 requisições por dia por IP.

Endpoints Pro (requerem API key):

| Método | Rota | Finalidade | |--------|------|------------| | `GET` | `/api/v1/qr` | Listar todos os seus QR | | `POST` | `/api/v1/qr` | Criar QR estático ou dinâmico | | `GET` | `/api/v1/qr/{id}` | Detalhes de um QR | | `PATCH` | `/api/v1/qr/{id}` | Alterar destino ou nome | | `DELETE` | `/api/v1/qr/{id}` | Excluir um QR | | `GET` | `/api/v1/qr/{id}/image` | Baixar imagem PNG ou SVG | | `GET` | `/api/v1/qr/{id}/stats` | Estatísticas de escaneamentos |

Todas as respostas Pro seguem `{ "data": {...}, "error": null }`. Se houver erro, `data` é null e `error` contém `code` e `message`.

Passo 1. Crie uma conta em codigo-qr.es.

Passo 2. Ative o plano Pro. A API completa é exclusiva Pro a €5,99/mês.

Passo 3. Vá para /panel/conta e clique em «Gerar API key». O token é exibido apenas uma vez. Salve-o em um gerenciador de senhas ou variável de ambiente.

Adicione este header a cada requisição:

```bash curl https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_seu_token" ```

Se a key não for válida ou o plano tiver expirado, a API retorna `401 UNAUTHORIZED` ou `403 PLAN_REQUIRED`. Você pode revogar a key a qualquer momento pelo painel; ela deixa de funcionar imediatamente.

O endpoint público é a forma mais rápida de testar a API ou gerar QR simples a partir de um script sem lidar com autenticação:

```bash curl -X POST https://codigo-qr.es/api/v1/qr/render \ -H "Content-Type: application/json" \ -d '{"value":"https://seudominio.com","format":"png","size":512}' ```

Parâmetros:

- `value` (obrigatório): o conteúdo do QR. Pode ser uma URL, texto, email ou dados de WiFi.
• `format`: `"png"` (padrão) ou `"svg"`
• `size`: `256`, `512` (padrão) ou `1024`

A resposta retorna a imagem em base64 dentro do envelope JSON:

```json { "data": { "image": "iVBORw0KGgo...", "format": "png", "size": 512 }, "error": null } ```

Se você exceder 50 requisições por dia a partir do mesmo IP, recebe `429 RATE_LIMITED` com o header `Retry-After` indicando quando o contador reinicia.

Um QR dinâmico codifica uma URL curta fixa (`/r/{slug}`), mas seu destino final pode ser alterado quando você quiser. O código impresso nunca muda.

Criar um QR dinâmico:

```bash curl -X POST https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_seu_token" \ -H "Content-Type: application/json" \ -d '{ "label": "Cardápio maio", "type": "url", "value": "https://seurestaurante.com/cardapio-maio", "is_dynamic": true, "tracking_mode": "redirect" }' ```

Mudar o destino sem reimprimir:

```bash curl -X PATCH https://codigo-qr.es/api/v1/qr/{id} \ -H "Authorization: Bearer cqr_seu_token" \ -H "Content-Type: application/json" \ -d '{"destination": "https://seurestaurante.com/cardapio-junho"}' ```

Baixar a imagem do QR:

```bash curl -o meu-qr.png \ "https://codigo-qr.es/api/v1/qr/{id}/image?format=png&size=1024" \ -H "Authorization: Bearer cqr_seu_token" ```

Ver estatísticas de escaneamentos:

```bash curl "https://codigo-qr.es/api/v1/qr/{id}/stats?period=30d" \ -H "Authorization: Bearer cqr_seu_token" ```

Resposta: ```json { "data": { "total": 312, "period": "30d", "by_day": [{"date": "2026-05-01", "count": 18}], "by_country": [{"country": "BR", "count": 280}] }, "error": null } ```

A API é útil quando o volume ou a automação tornam inviável gerar QR manualmente pelo painel.

E-commerce: QR em notas fiscais e faturas

O sistema ERP gera o PDF da nota fiscal. Com uma chamada a `POST /api/v1/qr`, ele obtém um QR que aponta para a URL de rastreamento do pedido. Se a URL mudar, `PATCH /api/v1/qr/{id}` atualiza o destino sem regenerar nem reimprimir nada.

Restaurantes: cardápio por mesa a partir do PDV

O sistema de caixa cria um QR por mesa ao abrir o turno. Ele aponta para o cardápio do dia, que o chef atualiza no CMS. O QR na mesa nunca muda, só o destino muda. Sem plastificar cardápios novos toda semana.

Eventos: ingressos personalizados em lote

Um sistema de venda de ingressos gera um QR único por ingresso com `POST /api/v1/qr` e o incorpora no PDF. Na entrada, o scanner verifica o QR lendo `GET /api/v1/qr/{id}` para confirmar se é válido.

Logística: pacotes com rastreamento

Cada pacote recebe um QR que aponta para sua página de rastreamento. O cliente escaneia a partir da embalagem e vê o status em tempo real. Os escaneamentos ficam registrados em `GET /api/v1/qr/{id}/stats`.

A API aplica limites de taxa para garantir disponibilidade.

Tier pública (`/api/v1/qr/render`):
• Limite: 50 requisições por dia por IP
• Janela: 24 horas
• Sem cadastro necessário

Tier Pro (endpoints com API key):
• Limite: 60 requisições por minuto por usuário
• Sem limite diário total

Ao exceder o limite, a API retorna `429 Too Many Requests` com estes headers:

``` X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1747612800 Retry-After: 43 ```

`X-RateLimit-Reset` é o timestamp Unix em que o contador reinicia. `Retry-After` são os segundos até esse momento.

Veja a documentação completa da API para todos os parâmetros e respostas de erro.