Quickstart da API REST
- 1
Crie uma chave API
No painel: Definições → Chaves API → Nova chave. A chave em claro é mostrada uma única vez e nunca mais é armazenada — ficam apenas um hash HMAC-SHA-256 e um prefixo curto de apresentação. Formato: `qrs_live_<64 caracteres hex>`; guarde-a como `QCS_API_KEY`. Escolha os scopes na criação: `qrcodes:read`, `qrcodes:write`, `scans:read`, `conversions:write`. O formulário pré-seleciona os dois de leitura, o valor prudente para uma credencial que acaba num job de CI. O acesso à API é uma função do plano Business; uma chave num plano inferior autentica-se mas recebe 403 `plan_limit`. Cada chave está limitada a 300 pedidos por minuto.
- 2
Crie um código QR dinâmico
POST em `/api/v1/qrcodes` com o header `Authorization: Bearer $QCS_API_KEY` e o body `{"name": "Flyer primavera", "type": "url", "destination_url": "https://example.com/landing"}`. A resposta `{"data": {…}}` traz o id do código, o slug gerado e `scan_url` — o endereço rastreado `/q/{slug}` que o código impresso codifica. `status` aceita `draft`, `active` ou `paused`, e `campaign_id` liga o código a uma campanha existente. Se o workspace esgotou a quota de QR dinâmicos, a chamada responde 403 `plan_limit` com `details.limit` e `details.current` em vez de um erro genérico. Os tipos estáticos nunca consomem essa quota.
- 3
Leia os eventos de scan
GET `/api/v1/scans?qr_id={id}&days=30&per_page=50` devolve uma página de eventos de scan mais um bloco `pagination`. Cada evento leva `device_type`, `os`, `browser`, `country`, `region`, `city`, `language`, `referrer`, `is_bot`, `ab_variant` e o `destination` para onde o visitante foi enviado. `days` aceita de 1 a 365 e assume 30 por omissão. Não há endereços IP na resposta porque a plataforma não os armazena: à base de dados chega apenas um hash com chave. Omita `qr_id` para ler todos os scans do workspace.
- 4
Mude o destino
PATCH `/api/v1/qrcodes/{id}` com o body `{"destination_url": "https://example.com/new-destination"}`. O mesmo endpoint aceita `name`, `payload`, `campaign_id` e `status` com `draft`, `active`, `paused` ou `archived`; é preciso pelo menos um campo. Responde 200 com o registo atualizado. O código impresso resolve para o novo URL logo no scan seguinte — sem reimpressão, sem purga de cache. `DELETE /api/v1/qrcodes/{id}` responde 204 e retira o código.
- 5
Registe uma conversão no servidor
POST `/api/v1/conversions` com o body `{"event_name": "purchase", "external_id": "order-1042", "amount": 49.9, "currency": "EUR", "qr_slug": "flyer-primavera"}`. Um evento novo responde 201 `{"id": …, "created": true}`; repetir o mesmo `external_id` responde 200 `{"duplicate": true}`, pelo que um job que tenta de novo não conta a receita duas vezes. A atribuição aceita `qr_slug` ou o valor `session_ref` captado na landing page. A chamada exige o scope `conversions:write`.
- 6
Erros, e onde entra o plugin WordPress
Cada falha devolve `{"error": {"code": …, "message": …}}` com um código estável sobre o qual ramificar: `unauthorized`, `insufficient_scope`, `plan_limit`, `validation_error`, `not_found`, `rate_limited`. As falhas de validação acrescentam `details.issues` indexado por campo. O plugin WordPress é um conector, não uma segunda API: sincroniza para o mesmo workspace via `/api/v1/wp/*` com a sua chave de licença, pelo que os códigos criados no WordPress aparecem na mesma lista `GET /api/v1/qrcodes` que os criados aqui. Não precisa do plugin para usar a API, nem da API para usar o plugin.
Perguntas frequentes
O que é o QRCode Suite?
O QRCode Suite é uma plataforma QR independente: crie uma conta gratuita e gere códigos QR dinâmicos e personalizados no browser — sem precisar de WordPress. Os conectores levam os mesmos códigos ao WordPress e ao WooCommerce, onde os pedidos podem ser atribuídos a códigos QR específicos.
O QRCode Suite funciona sem WordPress?
Sim. O QRCode Suite é um SaaS independente: registe-se, crie códigos QR e acompanhe as leituras inteiramente em qrcode-suite.com. O plugin WordPress é um conector opcional que traz os seus códigos para o wp-admin e adiciona a atribuição de encomendas WooCommerce.
O QRCode Suite exige uma subscrição separada?
O plano Free está disponível sem custos — sem cartão de crédito. Os planos pagos (Pro 9 €, Business 29 €, Agency 79 € por mês) desbloqueiam códigos ilimitados, regras de redireccionamento e mais. Não existe taxa por leitura.
Que tipos de códigos QR suporta o QRCode Suite?
O QRCode Suite suporta 22 tipos de códigos QR: URL estático, URL dinâmico, Texto simples, Telefone, Email, Localização, Link Hub, SMS, WhatsApp, Wi-Fi, vCard, Perfil social, PDF, Descarga de ficheiro, Descarga de app, Cupão, Evento de calendário, Formulário de captação de leads, Recolha de avaliações, Pedido grossista, Recompensa de fidelidade e Payload personalizado.
Posso alterar o destino de um código QR depois de o imprimir?
Sim. Os códigos QR dinâmicos usam um URL de redireccionamento curto. Pode actualizar o destino a partir do seu painel a qualquer momento, sem gerar ou imprimir novamente o código.
Precisa de ajuda para começar?
Comece grátis ou consulte toda a documentação.