API de QR Codes

Visão Geral

A API de Codes é o coração do qr3.app. Com ela, você cria, atualiza e exclui QR codes dinâmicos e estáticos.

URL Base: https://qr3.app/v1/codes

Criar QR Code

`POST /v1/codes`

curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "Mein erster QR-Code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'Mein erster QR-Code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "Mein QR-Code" --tags marketing,q1

Resposta (HTTP 201):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "target_url": "https://example.com",
    "is_dynamic": true,
    "status": "live",
    "tags": ["marketing", "q1"],
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz123" }
}

Tipos de QR Code

Tipo	Descrição	Campos obrigatórios
`url`	URL do site (dinâmico ou estático)	`url`
`vcard`	Cartão de visitas (vCard 3.0)	`vcard_first_name` ou `vcard_last_name`
`wifi`	Configuração de Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Localização (geo:)	`location_lat`, `location_lng`

Testes A/B

Teste duas URLs de destino diferentes com redirecionamento ponderado:

{
  "type": "url",
  "url": "https://version-a.example.com",
  "ab_enabled": true,
  "ab_target_url_b": "https://version-b.example.com",
  "ab_weight_a": 50
}

Expiração (Expiry)

Os QR codes podem expirar automaticamente:

{
  "type": "url",
  "url": "https://aktionsseite.example.com",
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_after_expiry": "https://archiv.example.com"
}

Após a expiração, o usuário é redirecionado para redirect_after_expiry ou uma página 410 é exibida.

Criação em Lote

`POST /v1/codes/batch`

Cria até 1.000 QR codes em uma única requisição. Ideal para aplicações em massa.

curl -X POST https://qr3.app/v1/codes/batch \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "url", "url": "https://produkt-1.example.com", "tags": ["batch"] },
      { "type": "url", "url": "https://produkt-2.example.com", "tags": ["batch"] },
      { "type": "wifi", "wifi_ssid": "GastWLAN", "wifi_password": "geheim123" }
    ],
    "skip_url_scan": false
  }'

Resposta (HTTP 201):

{
  "data": {
    "created": [
      { "id": "qr_...", "short_code": "abc123", "redirect_url": "https://qr3.app/abc123" },
      { "id": "qr_...", "short_code": "def456", "redirect_url": "https://qr3.app/def456" },
      { "id": "qr_...", "short_code": "ghi789", "status": "live" }
    ],
    "total": 3,
    "failed": 0
  }
}

Lista de QR Codes

`GET /v1/codes`

curl https://qr3.app/v1/codes?status=live&limit=20 \
  -H "Authorization: Bearer qr3_sk_..."

Parâmetros de Query:

Parâmetro	Tipo	Padrão	Descrição
`cursor`	string	—	Cursor para paginação
`limit`	integer	20	Resultados por página (máx. 100)
`status`	string	—	Filtro: `live`, `paused`, `flagged`, `draft`

Obter QR Code

`GET /v1/codes/:id`

curl https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Atualizar QR Code

`PATCH /v1/codes/:id`

Os QR codes dinâmicos permitem alterar a URL de destino a qualquer momento — sem a necessidade de reimprimir o QR code.

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://neue-zielseite.example.com", "status": "live" }'

Landing Page & Links Externos

Para códigos url dinâmicos, você pode definir is_landing_page: true (na criação ou via PATCH). O escaneamento exibirá uma página hospedada pelo qr3 com os arquivos públicos e links externos do código, em vez de redirecionar. Os links externos são passados como uma array links :

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

0 a 20 links por código; label deve ter entre 1 e 100 caracteres; url deve ser http(s) (≤ 2048 caracteres).
Cada URL é verificada com o Google Web Risk — uma URL insegura retorna 422.
Se o Web Risk não estiver acessível no momento do salvamento, o link será aceito mesmo assim, mas marcado para nova verificação. Uma tarefa diária verifica novamente os links salvos (e reavalia periodicamente os links classificados como seguros) e pausa o código automaticamente se um link for posteriormente identificado como inseguro.
"links": [] exclui todos os links. Consulte o Guia de Landing Page.

Excluir QR Code

`DELETE /v1/codes/:id`

Exclusão lógica (Soft-Delete) — o QR code é arquivado, os dados de escaneamento são mantidos.

curl -X DELETE https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Baixar Imagens do QR

Todos os formatos de imagem são acessíveis publicamente — nenhuma autenticação é necessária.

Formato	URL	Uso
SVG (Vetor)	`/v1/codes/:code/qr.svg`	Web, Escalonamento, Digital
PNG (Raster)	`/v1/codes/:code/qr.png`	E-mail, Apresentações
PDF (Vetor)	`/v1/codes/:code/qr.pdf`	Padrão: quadrado (apenas o código); `?format=a4` para uma folha de impressão
EPS (Vetor)	`/v1/codes/:code/qr.eps`	Fluxos de trabalho de impressão profissional (Adobe, gráficas)

Opcional: ?size=N — Tamanho do módulo em pixels (2–20, padrão: 4) para SVG, PNG e EPS. O PDF utiliza um tamanho de módulo fixo.

Apenas PDF: ?format=a4|square — Formato da página (padrão: square — apenas código + zona de silêncio, sem espaço em branco A4; a4 para uma folha A4 pronta para impressão)

# SVG für Web
curl https://qr3.app/v1/codes/r7f3Kx/qr.svg

# PNG in hoher Auflösung
curl https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10 -o qr-hires.png

# Kompaktes PDF (nur der Code, Standard)
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr.pdf

# Druckfertiges A4-Blatt
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?format=a4" -o qr-a4.pdf

Comentários

Os comentários permitem ciclos de feedback entre agências e clientes.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

`PATCH /v1/codes/:id/comments/:commentId`

`DELETE /v1/codes/:id/comments/:commentId`

# Kommentar hinzufügen
curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/comments \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "QR-Code bitte auf grünen Hintergrund abstimmen.", "author_name": "Max Müller" }'

# Offene Kommentare auflisten
curl "https://qr3.app/v1/codes/qr_a1b2c3d4/comments?resolved=false" \
  -H "Authorization: Bearer qr3_sk_..."

# Kommentar als erledigt markieren
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4/comments/cmt_xyz \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'