Documentazione

1. Chiavi API

Una chiave API autentica ogni richiesta che fai all'API di Pinbloom. Puoi creare due tipi di chiave, e ogni endpoint accetta solo uno dei due:

• Sandbox — pensata per lo sviluppo. Ogni endpoint simula i processi reali senza salvare nulla e senza consumare quote dal tuo piano.
• Live — genera QR code veri, ognuno conteggiato nella quota mensile del tuo piano.

Una chiave sandbox funziona solo sugli endpoint sandbox, una chiave live solo su quello di produzione — usare quella sbagliata dà un 401.

Il tuo piano permette un numero limitato di chiavi per ciascun tipo — il conteggio sopra la tabella ("x/y usate") mostra quante te ne restano; elimina quelle che non usi più per liberare uno slot.

Authorization: Bearer qrv_live_xxxxxxxxxxxxxxxx

2. Generare un QR code

POST /api/qr/generate — richiede una chiave live. Salva il QR code, ne genera l'immagine, e consuma 1 dalla tua quota mensile. Ogni campo nel corpo della richiesta è opzionale:

curl -X POST https://pinbloom.eu/api/qr/generate \
  -H "Authorization: Bearer qrv_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "tag": "promo-2026",
        "displayFields": [{ "label": "Posti", "value": "4" }],
        "expires_at": "2026-12-31T23:59:59Z"
      }'

Risposta (201):

{
  "uuid": "019f2b3c-4a11-7c3e-9c2a-1b8e6f0a2d4c",
  "tag": "promo-2026",
  "expiresAt": "2026-12-31T23:59:59+00:00",
  "format": "qrcode",
  "shortCode": null,
  "qrImage": "PHN2ZyB4bWxucz0i...",
  "imageUrl": "https://pinbloom.eu/c/k7Qm2...png"
}

qrImage è il QR code stesso — un'immagine SVG, codificata in base64. Decodificala per ottenere il file immagine vero e proprio.

imageUrl è l'indirizzo pubblico di un PNG del codice: mettilo in un <img> delle email che mandi ai tuoi clienti o nella pagina dell'ordine. I programmi di posta non mostrano gli SVG, e Gmail blocca le immagini in base64 dentro l'email. L'indirizzo non richiede la chiave API, non scade e funziona anche dopo l'uso o la revoca del codice. Alcuni programmi di posta, per esempio Outlook desktop, bloccano le immagini esterne finché il lettore non le permette: metti nell'email anche il codice in testo, o un link al biglietto.

Nessun QR code rimasto sul tuo piano? Ricevi un 422 invece, e non viene creato né dedotto nulla.

Abbonamento terminato? Ricevi un 403: dopo la scadenza non si generano nuovi codici, né qui né in sandbox, anche con crediti extra. I codici già creati restano validi per 6 mesi.

Codici a barre

Con "format": "barcode" il campo qrImage contiene un Code128 invece di un QR. Resta un SVG codificato in base64.

Per il resto non cambia niente. tag, metadata e displayFields si comportano allo stesso modo, i webhook arrivano identici, e all'ingresso la validazione funziona senza che tu debba fare nulla di diverso.

L'unica differenza nella risposta è shortCode: il numero di 14 cifre che il codice a barre contiene, nel caso ti serva stamparlo in chiaro sotto all'immagine. Con un QR è null.

Più codici in una chiamata

POST /api/qr/generate-batch — richiede una chiave live. Il corpo ha un solo campo, codes: un array in cui ogni elemento ha gli stessi campi di /api/qr/generate. Così ogni biglietto di un ordine può avere il suo tag, i suoi displayFields e le sue date. La risposta (201) è { "codes": [ … ] }, nello stesso ordine della richiesta, con gli stessi campi di /api/qr/generate.

Tutto o niente. Se la quota non basta per tutti i codici, o un elemento non è valido, non viene creato nessun codice e ricevi un 422. L'errore di un elemento indica la sua posizione, per esempio codes.2.expires_at. Un ordine non resta mai con metà dei biglietti.

curl -X POST https://pinbloom.eu/api/qr/generate-batch \
  -H "Authorization: Bearer qrv_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
        "codes": [
          { "tag": "order-1042", "displayFields": [{ "label": "Posto", "value": "A1" }] },
          { "tag": "order-1042", "displayFields": [{ "label": "Posto", "value": "A2" }] }
        ]
      }'

Ripetere una chiamata senza creare doppioni

3. Gestire i codici

Tre endpoint, con una chiave live, per i codici creati via API dall'account della chiave, con qualunque sua chiave live. I codici delle raccolte sono a parte: con questi endpoint rispondono 404, come un codice che non esiste.

Leggere lo stato

GET /api/qr/{uuid} — la consultazione funziona sempre, anche dopo la fine dell'abbonamento. Risposta (200):

{
  "uuid": "019f2b3c-4a11-7c3e-9c2a-1b8e6f0a2d4c",
  "status": "unused",
  "tag": "promo-2026",
  "format": "qrcode",
  "shortCode": null,
  "usedAt": null,
  "revokedAt": null,
  "startsAt": null,
  "expiresAt": "2026-12-31T23:59:59+00:00"
}

Revocare e ripristinare

curl -X POST https://pinbloom.eu/api/qr/019f2b3c-4a11-7c3e-9c2a-1b8e6f0a2d4c/revoke \
  -H "Authorization: Bearer qrv_live_xxxxxxxxxxxxxxxx"

POST /api/qr/{uuid}/revoke revoca un codice non usato: da quel momento non passa più la validazione. POST /api/qr/{uuid}/restore riporta un codice revocato a non usato. Tutti e due rispondono (200) con lo stato del codice, come la lettura.

Revocare un codice già revocato, o ripristinare un codice non revocato, non cambia niente e risponde 200: puoi ripetere la chiamata senza problemi. Un codice usato non si può né revocare né ripristinare: 409.

Abbonamento terminato? Nei 6 mesi in cui i codici restano validi puoi ancora revocare. Il ripristino richiede un abbonamento attivo: 403.

4. Testare senza andare in produzione

Generare un codice di prova

POST /api/sandbox/qr/generate richiede una chiave sandbox e non consuma quota. Non legge il corpo della richiesta: crea sempre un QR code, mai un codice a barre, e risponde solo con uuid e qrImage. Per provare i campi, il formato e la risposta completa dell'endpoint live usa POST /api/sandbox/qr/generate-batch, anche con un solo codice.

curl -X POST https://pinbloom.eu/api/sandbox/qr/generate \
  -H "Authorization: Bearer qrv_sandbox_xxxxxxxxxxxxxxxx"

Un QR code generato così esiste solo nella risposta che ricevi. Non può essere "scansionato" dall'app operatore.

POST /api/sandbox/qr/generate-batch fa lo stesso per più codici: stesso corpo, stesso limite di 100 codici, stessi campi nella risposta. Non salva niente, quindi imageUrl è null.

Simulare una scansione

POST /api/sandbox/simulate — per testare in sandbox i dati ricevuti tramite webhook devi usare questo endpoint:

curl -X POST https://pinbloom.eu/api/sandbox/simulate \
  -H "Authorization: Bearer qrv_sandbox_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "qr_code": "abc123", "simulate": "valid" }'

Ogni esito tranne not_found fa partire l'evento corrispondente (sezione 5) verso i webhook registrati su questa chiave sandbox e iscritti a quell'evento. La consegna è identica a quella di produzione: stessa firma, stessi cinque tentativi. È l'unico modo per collaudare un'integrazione webhook prima di andare live.

5. Webhook

Disponibile sui piani Pro e Business. Un webhook notifica un tuo server ogni volta che un QR cambia stato (solo QR generati tramite API, no eventi). Una stessa API key può avere più webhook (es. uno per lo staging, uno per un tunnel ngrok locale mentre sviluppi l'integrazione), e ognuno è iscritto in modo indipendente solo agli eventi che ti interessano.

Usa quel secret nel tuo progetto per verificare che una richiesta arrivi davvero da Pinbloom (vedi paragrafo "Verificare che una richiesta sia autentica").

Un webhook riceve solo gli eventi a cui è iscritto — li scegli quando lo crei, oppure li cambi in seguito dallo stesso pannello. Ogni evento ha la stessa struttura:

{
  "event": "qr.used",
  "data": {
    "uuid": "019f...",
    "tag": "promo-2026",
    "metadata": { "campaign": "estate" },
    "usedAt": "2026-08-10T14:30:00+00:00",
    "revokedAt": null,
    "startsAt": null,
    "expiresAt": null,
    "scannedAt": "2026-08-10T14:30:00+00:00",
    "offline": false
  }
}

scannedAt è il momento della scansione. offline è true quando l'app dell'operatore era senza rete: la notifica parte quando la scansione arriva al server, quindi anche molto dopo scannedAt.

$atteso = hash_hmac('sha256', $corpoRichiesta, $secretSalvato);

if (! hash_equals($atteso, $request->header('X-Pinbloom-Signature'))) {
    abort(401); // non autentico, scarta
}
// verificato — puoi fidarti del contenuto