API per codici QR e webhook

Che cosa fanno l'API e i webhook

L'API REST si trova sotto il percorso /api/v1 e risponde in JSON. Può elencare i codici con una ricerca, un filtro per tag e pagine fino a cento elementi, leggere un codice, crearlo, modificarlo ed eliminarlo, restituire un SVG semplice di un codice e riassumere le scansioni degli ultimi trenta giorni. Una chiave è un token bearer che inizia con qrk_ e appartiene a un solo workspace, quindi una richiesta può agire solo sui codici di quel workspace.

Un webhook è un indirizzo HTTPS che registri insieme agli eventi che vuoi ricevere. L'app invia un messaggio JSON per ogni evento: un codice viene creato, modificato o eliminato, viene registrata una scansione di una persona oppure viene inviata una risposta a un modulo della landing page. Un'azione di test invia un evento ping, così puoi verificare il tuo ricevitore prima che arrivi il traffico reale. Ogni consegna è firmata con HMAC-SHA256 usando il segreto del webhook, sul timestamp e sul corpo.

L'API è pensata per chi costruisce integrazioni e non cambia l'aspetto dei codici. L'SVG è in bianco e nero semplice, senza logo, forme o colori, perché le immagini con stile si creano nell'editor. L'API richiede il piano Team. Le chiavi sopravvivono a un downgrade, ma smettono di funzionare finché il workspace non torna a un piano che include l'API.

Come iniziare a usare l'API

1. 01

   Crea una chiave come proprietario

   Apri la pagina API come proprietario, dai alla chiave un nome come il server che la userà e creala. Il token completo compare una sola volta, quindi copialo subito nel tuo gestore di segreti. Dopo, la pagina mostra solo il nome, il prefisso, la data di creazione e l'ultimo utilizzo.

2. 02

   Invia la chiave con ogni richiesta

   Invia il token in un'intestazione Authorization, con la parola Bearer, uno spazio e il token. Chiama per prima cosa la verifica dell'account: la risposta indica il workspace, la chiave e i crediti rimasti, e conferma che la configurazione funziona. Una chiave mancante o errata riceve una risposta non autorizzata.

3. 03

   Crea, aggiorna e leggi i codici

   Invia il nome, il tipo (il predefinito è un link web), il contenuto e i campi facoltativi: dynamic, slug, expiry, password, un dominio verificato, tags e style. Creare un codice costa un credito, mentre leggere e aggiornare sono gratuiti. Una richiesta che non supera la validazione restituisce i motivi, e il credito torna disponibile.

Dove si inserisce l'API

• Biglietteria e prenotazioni

  Quando un sistema di prenotazione conferma un posto, crea un codice dinamico per quel biglietto e invia al cliente il link breve e l'SVG. L'email o il pass nel wallet riporta lo stesso codice, e nessuno lo copia a mano.

• Scorte e tag dei beni

  Un sistema di magazzino può creare un codice per ogni articolo, con il numero dell'articolo come tag. Ogni scansione viene registrata, e il sistema può leggere il riepilogo di trenta giorni di un articolo per vedere quali tag sono stati controllati di recente.

• Menu del ristorante da un foglio di calcolo

  Uno script può leggere un foglio di calcolo con i link dei menu e aggiornare il contenuto di ogni codice dinamico tramite l'API. I codici stampati restano gli stessi, e l'aggiornamento vale dalla scansione successiva.

• Moduli di check-in e feedback per eventi

  Un team eventi può pubblicare una landing page con un modulo e ricevere un webhook per ogni risposta. Un sistema separato reagisce all'evento, così nessuno deve interrogare periodicamente le risposte.

• Monitoraggio e avvisi

  Un ricevitore di webhook può salvare gli eventi di scansione per paese e dispositivo, e generare un avviso quando un codice smette di essere scansionato. Il tuo sistema decide cosa conta come problema, perché l'app invia gli eventi senza giudicarli.

Consigli per un'integrazione affidabile

Conserva la chiave come una password

Le chiavi vengono mostrate una sola volta e conservate solo come digest, quindi l'app non può mostrarle di nuovo. Se una chiave viene compromessa, revocala dalla pagina API e creane una nuova. La revoca blocca subito ogni richiesta che usa il vecchio token.

Rispetta il limite di frequenza e i crediti

Ogni chiave può inviare 120 richieste al minuto. Una richiesta oltre questo limite riceve una risposta di troppe richieste. Quando i crediti finiscono, la creazione di un codice restituisce una risposta di pagamento richiesto, il cui codice di errore indica che non ci sono crediti. L'app non permette ancora di acquistarne altri, quindi pianifica le importazioni in batch in base al saldo.

Verifica firme e timestamp

Calcola l'HMAC-SHA256 del timestamp, di un punto e del corpo grezzo della richiesta con il tuo segreto, e confrontalo con l'intestazione della firma. Rifiuta i timestamp troppo vecchi, così una richiesta catturata non può essere riprodotta, e usa l'identificativo della consegna per ignorare un invio ripetuto.

Usa un endpoint che controlli tu

Gli indirizzi dei webhook devono usare HTTPS, non possono contenere credenziali e devono risolversi in indirizzi pubblici. Gli host locali e le reti private vengono rifiutati, e i reindirizzamenti non vengono seguiti. Una consegna fallita viene ritentata fino a cinque volte, con attese crescenti.

Domande su API e webhook