API per QR code

Crea codici dal tuo backend, leggi le loro scansioni e ricevi un webhook nell’istante in cui qualcuno scansiona. Questa pagina non richiede alcun account.

L’API fa parte del piano Business. Le chiavi si creano nella dashboard, in «API e webhook», e si vedono una volta sola: una chiave persa si revoca e si sostituisce, non si recupera.

URL di base

https://enqre.com/api/v1

Autenticazione

Ogni richiesta porta la chiave come bearer token. Senza chiave valida: 401. Con chiave valida su un piano senza API: 403.

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

Endpoint

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

Elenca i tuoi codici, dal più recente. Paginazione a cursore: rimanda il nextCursor ricevuto per la pagina successiva.

{
  "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

Crea un codice URL dinamico. La risposta contiene l’URL breve da stampare.

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

Legge un codice.

PATCH/api/v1/qrcodes/{id}

Modifica un codice, destinazione compresa. È tutto il senso di un codice dinamico: la copia stampata continua a funzionare e punta altrove.

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

DELETE/api/v1/qrcodes/{id}

Elimina un codice. Le copie stampate smettono di risolvere: per mettere in pausa una campagna imposta invece active a false.

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

Le ultime 1.000 scansioni di un codice, dalla più recente, più il totale complessivo.

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

Errori

Gli errori sono JSON con un codice stabile leggibile da una macchina. Ramifica sul codice, non sul messaggio: i messaggi possono essere riscritti, i codici no.

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 di frequenza

60 scritture al minuto per account, oltre le quali arriva un 429. Le letture oggi non sono limitate, e non è una promessa su cui costruire.

Webhook

Registra un URL in «API e webhook» e ogni scansione viene inviata lì all’istante: il tuo sistema lo sa senza interrogare nulla.

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

Verifica la firma

Calcola l’HMAC-SHA256 del corpo grezzo della richiesta con il tuo secret del webhook e confrontalo con l’header. Rifiuta ciò che non coincide, e confronta a tempo costante.

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));

Collection Postman

Tutti gli endpoint di questa pagina, pronti da eseguire: importa la collection, imposta la variabile apiKey, invia.

Scarica la collection

Cosa l’API non fa ancora

I codici creati via API sono codici URL con il design predefinito. Gli altri sedici tipi, i campi di design e l’import massivo restano per ora nella dashboard. Quello che l’API crea è un codice del tutto normale: modificabile, misurabile e stampabile come gli altri.

Ottieni una chiave

API, webhook, GS1 Digital Link, white-label e dominio proprio sono nel piano Business, 39 € al mese.

Vedi i piani