API: la guida

Autenticazione e limiti

Ogni richiesta a /api/v1/qrcodes porta la chiave come token Bearer. La chiave inizia con ogqr_ seguita da 64 caratteri esadecimali; i token di sessione del sito non sono accettati.

Authorization: Bearer $QRCODENOW_API_KEY

• Indirizzo base: https://qrcodenow.ai/api/v1.
• Ogni chiave può fare 60 richieste al minuto. Oltre rispondiamo 429 con Retry-After: 60.
• Puoi avere fino a 10 chiavi attive e revocarle quando vuoi dalle impostazioni; una chiave revocata smette subito di funzionare.
• Una chiave agisce come il tuo account: vede i tuoi QR e quelli condivisi con te, con lo stesso ruolo (chi è editor può modificare, solo il proprietario può eliminare).
• Se il piano non include più l'API o l'account viene disattivato, le chiavi rispondono 401.

Creare un QR dinamico

Un QR dinamico punta al nostro indirizzo di reindirizzamento: la destinazione si può cambiare dopo la stampa. Per un link basta il tipo 2 con target_url.

curl -X POST https://qrcodenow.ai/api/v1/qrcodes \
  -H "Authorization: Bearer $QRCODENOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idtype": 2, "title": "Volantino autunno", "target_url": "https://example.com/autunno"}'

Risposta 201 (abbreviata)

{
  "success": 1,
  "data": {
    "id": 128,
    "code": "k3x9q2m7ab",
    "idtype": 2,
    "is_dynamic": 1,
    "is_paused": 0,
    "title": "Volantino autunno",
    "target_url": "https://example.com/autunno",
    "qr_image_url": "https://…/i/k3x9q2m7ab.png",
    "scan_count": 0,
    "my_role": "owner"
  }
}

Conserva id per le chiamate successive e code per l'immagine. Il QR occupa un posto nella quota del piano come uno creato dalla dashboard: a quota piena la risposta è 403 con code: plan_qr_limit.

I tipi che codificano il contenuto nel QR stesso (vCard, WiFi, email…) leggono i campi da qr_payload, senza target_url:

{
  "idtype": 4,
  "title": "Biglietto da visita",
  "qr_payload": {
    "firstname": "Giulia",
    "lastname": "Bianchi",
    "phone": "+39 333 1234567",
    "email": "giulia@example.com"
  }
}

Elencare i QR

La lista è paginata: p è la pagina (da 1), c gli elementi per pagina (massimo 100), srt il campo di ordinamento (date_create, date_update, title, scan_count), o il verso (ASC o DESC) e s una ricerca su titolo e codice.

curl "https://qrcodenow.ai/api/v1/qrcodes?p=1&c=50&srt=scan_count&o=DESC" \
  -H "Authorization: Bearer $QRCODENOW_API_KEY"

La risposta contiene rows, total (tutti i risultati), count (quelli in questa pagina) e page. Il dettaglio di un singolo QR è GET /api/v1/qrcodes/{id}.

Cambiare la destinazione

Con PATCH cambi title e target_url. Il codice stampato non cambia: chi lo scansiona arriva subito alla nuova destinazione. Serve almeno il ruolo editor sul QR.

curl -X PATCH https://qrcodenow.ai/api/v1/qrcodes/128 \
  -H "Authorization: Bearer $QRCODENOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/inverno"}'

Scaricare l'immagine

Ogni QR ha un'immagine pubblica in qr_image_url, in PNG; cambiando l'estensione in .svg ottieni il vettoriale per la stampa. Non serve la chiave. Aggiungi ?download=1 per scaricarla come file.

curl -o qr.svg "https://…/i/k3x9q2m7ab.svg?download=1"

QR statico al volo

Per codificare un testo senza salvarlo nell'account usa POST /api/v1/qrcodes/static: risponde direttamente con il PNG e non occupa quota. Il testo può essere lungo fino a 1273 byte.

curl -X POST https://qrcodenow.ai/api/v1/qrcodes/static \
  -H "Authorization: Bearer $QRCODENOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Testo da codificare"}' \
  -o static-qr.png

Eliminare un QR

Solo il proprietario può eliminare un QR. La risposta è 204 senza corpo; da quel momento il codice stampato non reindirizza più.

curl -X DELETE https://qrcodenow.ai/api/v1/qrcodes/128 \
  -H "Authorization: Bearer $QRCODENOW_API_KEY"

Tipi di QR (idtype)

I tipi dinamici richiedono target_url. Gli altri sono diretti: il contenuto è dentro il QR e si passa in qr_payload.

Date degli eventi nel formato 2026-10-20T18:00. Le combinazioni di campi obbligatori sono verificate alla creazione: in caso di errore la risposta 422 dice quale campo manca.

Errori

Gli errori applicativi usano il formato qui sotto: error è un messaggio e code un identificatore. La validazione risponde 400 con error, message ed eventuali errors per campo; il 401 può non avere code e il 429 non ha corpo: leggi lo stato HTTP e Retry-After.

{ "success": 0, "error": "…", "code": "plan_qr_limit" }