Abundera QR Pro API

Introduzione

L'API Abundera QR Pro ti permette di creare, modificare e analizzare QR code dinamici in modo programmatico, tutto ciò che uno sviluppatore vuole automatizzare dalla dashboard. Gestione team, fatturazione e flussi account restano nell'interfaccia dashboard; questa API è limitata alle operazioni sui codici.

URL di base: https://pro.qr.abundera.ai/api

Formato richiesta: JSON (Content-Type: application/json) on POST / PATCH / DELETE.

Formato risposta: JSON (application/json; charset=utf-8).

Disponibilità: L'accesso API è una funzionalità Business+. I piani Solo possono usare la dashboard ma non l'API.

Autenticazione

Ogni richiesta porta una chiave API come bearer token:

Authorization: Bearer abnd_qrpro_...

Crea e revoca le chiavi su /account/keys (livello Business, Team o Agency). Il token grezzo abnd_qrpro_... viene mostrato una sola volta alla creazione, conservalo immediatamente. Memorizziamo solo il suo hash SHA-256; non è possibile recuperare una chiave persa.

Le richieste non autenticate restituiscono 401 { "error": "not_signed_in" }. Le chiavi non valide o revocate restituiscono 401 { "error": "invalid_api_key" }.

Chiavi API are scoped to the user who created them. If that user is a member of a team, the endpoints below operate on the team's codes automatically (current-team context is stored on the user account and managed via the dashboard).

Limiti di frequenza

Applicati per chiave API. Ogni risposta include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (secondi Unix del prossimo reset della finestra).

Le richieste oltre il budget restituiscono 429 { "error": "rate_limited", "window": "day", "retry_at": 1234567890 } con un header Retry-After in secondi.

Le scansioni non sono soggette a limiti di frequenza, il percorso di redirect (aqr.net/{shortcode}) non richiede autenticazione né ha un budget per scansione. Ogni piano ha un limite mensile esplicito di scansioni (100k / 1M / 10M / 30M). Superato il limite il redirect continua a funzionare; ti inviamo un'email affinché tu possa decidere se aggiornare il piano o gestire un picco occasionale. Prevedi più di circa 10M di scansioni giornaliere? Scrivici per coordinare la capacità.

Errori

Ogni risposta di errore è JSON con un codice error leggibile dalla macchina e, dove rilevante, contesto aggiuntivo:

{ "error": "plan_limit", "plan": "business", "limit": 500, "current": 500 }

Codici

QR code dinamici: uno shortcode Base58 a 7 caratteri che reindirizza attraverso aqr.net/{shortcode}. Ogni codice include un QR statico di backup scaricabile dalla dashboard, se smetti di pagare, la versione statica continua a funzionare senza toccare il nostro redirect.

GET /api/codes

Elenca tutti i codici nel tuo scope corrente (personale o il team su cui stai operando). Restituisce un array con un riepilogo delle scansioni degli ultimi 30 giorni per codice.

$ curl -H "Authorization: Bearer abnd_qrpro_..." \
       https://pro.qr.abundera.ai/api/codes

{
  "codes": [
    { "id": "uuid", "shortcode": "aBc123x",
      "url": "https://example.com/landing",
      "label": "Campagna Q2", "tags": "q2,print",
      "status": "active", "scans_30d": 1245,
      "created_at": 1713288000, "updated_at": 1713370000 }
  ],
  "plan": "business",
  "plan_limit": 500,
  "scope": { "type": "user" }
}

POST /api/codes

Crea un nuovo codice dinamico. Il limite di codici attivi+in pausa del piano viene verificato prima dell'inserimento. Body minimo:

{ "url": "https://example.com/landing" }

Personalizzazione completa (tutto opzionale):

{ "url":          "https://example.com/landing",
  "label":        "Campagna primavera",
  "tags":         "q2,print",
  "qr_type":      "url",
  "style_json":   "{...}",
  "logo_key":     "instagram",
  "frame_style":  "scan-me",
  "frame_text":   "SCAN ME" }

Restituisce 201 + la riga creata incluso lo shortcode generato e lo short_url da stampare.

GET /api/codes/{id}

Recupera un singolo codice. 404 se non è nel tuo scope.

PATCH /api/codes/{id}

Aggiorna qualsiasi campo modificabile. L'uso più comune: cambiare l'URL di destinazione di un codice già stampato.

$ curl -X PATCH \
       -H "Authorization: Bearer abnd_qrpro_..." \
       -H "Content-Type: application/json" \
       -d '{"url":"https://example.com/new-landing"}' \
       https://pro.qr.abundera.ai/api/codes/uuid

Le modifiche si propagano al redirect in pochi secondi. Valori status validi per PATCH: "active", "paused". Per eliminare, usa DELETE.

DELETE /api/codes/{id}

Eliminazione logica. Transizione a status=grace con grace_until = now + 90 giorni. Il redirect continua a funzionare per tutta la finestra di grazia, questa è la promessa concreta di assenza di lock-in. Dopo 90 giorni il codice diventa expired e il redirect restituisce 410 Gone.

POST /api/codes/import

Creazione in blocco da un payload array (usato anche dal flusso "Salva su Pro" su qr.abundera.ai). Accetta un singolo payload o un array. Il limite del piano viene verificato una sola volta prima del batch.

Analytics

GET /api/codes/{id}/analytics

Parametri query:

• range=7d|30d|90d|1y|3y, limitato alla retention del piano (Solo 1y, Business 2y, Team/Agency 3y).
• granularity=day|hour, la granularità oraria è solo Team e Agency; finestra massima 7 giorni per granularità oraria.

{
  "range": "30d", "days": 30, "granularity": "day",
  "total": 4321,
  "timeseries": [
    { "bucket": "2026-04-01", "scans": 142 },
    { "bucket": "2026-04-02", "scans": 178 },
    ...
  ],
  "by_country": [
    { "key": "US", "total": 3012 },
    { "key": "CA", "total": 402 },
    { "key": "Other", "total": 108 }
  ],
  "by_device":  [
    { "key": "mobile",  "total": 3850 },
    { "key": "tablet",  "total": 312 },
    { "key": "desktop", "total": 159 }
  ]
}

Countries with fewer than 5 scans in the window are folded into "Other" for privacy (see Modello privacy).

Chiavi API

Crea e revoca le chiavi dalla pagina dashboard /account/keys. La gestione programmatica autonoma è in sola lettura tramite API, puoi elencare le tue chiavi e revocarle, ma la creazione di una nuova chiave richiede la dashboard (problema del pollo e dell'uovo: avresti bisogno di una chiave per crearne una).

GET /api/keys

List your Chiavi API. Never returns the raw token, only metadata.

{
  "keys": [
    { "id": "uuid", "label": "Server di produzione",
      "created_at": 1713288000, "last_used_at": 1713370000 }
  ],
  "allowed": true,
  "plan": "business"
}

DELETE /api/keys/{id}

Revoca. La chiave smette di funzionare immediatamente; qualsiasi richiesta che la usa restituisce 401 invalid_api_key da quel momento in poi.

Esportazione dati

GET /api/user/export

Scarica uno ZIP contenente il tuo dataset completo, codes.csv (ogni codice, inclusi grazia + scaduti), scans.csv (aggregato giornaliero) e un README.txt che spiega il formato. L'archivio viene emesso come application/zip; salvalo su file:

$ curl -H "Authorization: Bearer abnd_qrpro_..." \
       -o abundera-qr-export.zip \
       https://pro.qr.abundera.ai/api/user/export

Reimporta ovunque. Questa è la garanzia del formato portabile, nessun vendor lock-in è possibile se possiedi i tuoi dati.

Modello privacy

L'aggregato delle scansioni è l'intera storia della privacy. Cosa memorizziamo per ogni scansione sul percorso di redirect:

• code_id, quale dei tuoi codici è stato scansionato
• day_bucket, data UTC (YYYY-MM-DD). Nessuna precisione sub-giornaliera nell'aggregato restituito.
• country, ISO-3166-1 alpha-2 dall'header CF-IPCountry di Cloudflare. Nessuna città, nessuna regione, nessuna geo-IP lookup.
• device_type, mobile / tablet / desktop / unknown, classificato da una breve regex User-Agent. La stringa UA grezza viene scartata al momento della classificazione.
• scan_count, contatore aggregato, upsertato ad ogni hit.

Cosa non memorizziamo: indirizzi IP (hashati o meno), stringhe User-Agent grezze, geo a livello di città, timestamp sub-giornalieri, referer, cookie, pixel di retargeting o qualsiasi vettore identificativo individuale. Un rumore di fondo di 5 sopprime la re-identificazione di piccoli aggregati.

I livelli Team e Agency scrivono in aggiunta un aggregato orario parallelo con hour_bucket (YYYY-MM-DD-HH UTC). Stesso modello privacy, nessun timestamp più fine dell'ora, stesso rumore di fondo, stessa assenza di dati sui singoli utenti che scansionano.

Leggi la storia completa: /manifesto/ and /no-lock-in/ sul sito del free tool.