API de códigos QR

Crie códigos a partir do seu próprio backend, leia as respetivas leituras e receba um webhook no momento em que alguém ler um. Esta página não exige conta.

A API faz parte do plano Business. As chaves criam-se no painel, em API e webhooks, e são mostradas uma única vez — uma chave perdida é revogada e substituída, nunca recuperada.

URL base

https://enqre.com/api/v1

Autenticação

Cada pedido leva a chave como bearer token. Um pedido sem chave válida recebe 401; uma chave válida num plano sem API recebe 403.

curl https://enqre.com/api/v1/qrcodes \
  -H "Authorization: Bearer $ENQRE_API_KEY"

Endpoints

GET/api/v1/qrcodes?limit=50&cursor=<id>

Lista os seus códigos, dos mais recentes para os mais antigos. Paginação por cursor: passe o nextCursor devolvido para obter a página seguinte.

{
  "data": [
    {
      "id": "clx…", "name": "Table tent", "type": "URL",
      "slug": "a1b2c3", "destinationUrl": "https://example.com/menu",
      "scanCount": 128, "active": true, "createdAt": "2026-09-01T10:00:00.000Z",
      "shortUrl": "https://enqre.com/r/a1b2c3"
    }
  ],
  "nextCursor": "clx…"
}

POST/api/v1/qrcodes

Cria um código de URL dinâmico. A resposta traz o URL curto para imprimir.

{ "name": "Table tent", "url": "https://example.com/menu" }

201 Created
{
  "data": {
    "id": "clx…", "name": "Table tent", "slug": "a1b2c3",
    "destinationUrl": "https://example.com/menu",
    "shortUrl": "https://enqre.com/r/a1b2c3"
  }
}

GET/api/v1/qrcodes/{id}

Lê um código.

PATCH/api/v1/qrcodes/{id}

Altera um código — incluindo o destino. É esta a razão de ser de um código dinâmico: o exemplar impresso continua a funcionar e passa a apontar para outro sítio.

{ "url": "https://example.com/autumn-menu", "name": "Autumn menu", "active": true }

DELETE/api/v1/qrcodes/{id}

Elimina um código. Os exemplares impressos deixam de resolver, por isso não é esta a forma de pôr uma campanha em pausa — defina antes active como false.

GET/api/v1/qrcodes/{id}/scans

As últimas 1000 leituras de um código, das mais recentes para as mais antigas, e o total acumulado.

{
  "total": 128,
  "data": [
    { "createdAt": "2026-09-06T18:12:03.000Z", "device": "mobile", "os": "iOS", "browser": "Safari" }
  ]
}

Erros

Os erros vêm em JSON com um código estável, legível por máquina. Ramifique pelo código e não pela mensagem — as mensagens podem ser reescritas, os códigos não.

401	invalid_api_key	No key, a revoked key, or one that does not exist.
403	api_not_available_on_plan	The key is valid; the account is not on Business.
400	invalid_body	The JSON body failed validation.
402	plan_limit_reached	The account is at its dynamic-code limit.
404	not_found	No code with that id on this account.
429	rate_limited	More than 60 writes in a minute.

Limite de pedidos

60 escritas por minuto por conta, respondidas com 429 quando excedidas. As leituras não estão limitadas hoje; isso não é uma promessa sobre a qual construir.

Webhooks

Registe um URL em API e webhooks e cada leitura é enviada para lá à medida que acontece, para que o seu sistema saiba de uma leitura sem andar a perguntar.

POST your-endpoint
X-Enqre-Event: scan.created
X-Enqre-Signature: <hex hmac-sha256 of the raw body>
Content-Type: application/json

{
  "event": "scan.created",
  "qrCodeId": "clx…",
  "slug": "a1b2c3",
  "name": "Table tent",
  "device": "mobile",
  "os": "iOS",
  "browser": "Safari"
}

Verificar a assinatura

Calcule o HMAC-SHA256 do corpo do pedido em bruto com o segredo do seu webhook e compare-o com o cabeçalho. Rejeite tudo o que não coincidir — e compare em tempo constante.

import crypto from "node:crypto";

const raw = await req.text(); // the raw body, before JSON.parse
const expected = crypto
  .createHmac("sha256", process.env.ENQRE_WEBHOOK_SECRET)
  .update(raw)
  .digest("hex");

const given = req.headers.get("x-enqre-signature") ?? "";
const ok =
  given.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));

Coleção Postman

Todos os endpoints desta página, prontos a correr: importe a coleção, defina a variável apiKey e envie.

Transferir a coleção

O que a API ainda não faz

Os códigos criados através da API são códigos de URL com o design por omissão. Os outros dezasseis tipos, os campos de design e a importação em massa são, para já, exclusivos do painel. Tudo o que a API cria é um código normal: editável, mensurável e imprimível como qualquer outro.

Obter uma chave

A API, os webhooks, o GS1 Digital Link, o white-label e o domínio próprio estão no Business, por 39 € por mês.

Ver os planos