Emetti e aggiorna i pass Wallet dal tuo sistema.
Firmare i pass Apple, gestire gli oggetti Google e mantenere sincronizzata ogni modifica è un progetto a sé. L’API di Vuelvy permette al tuo team tecnico di integrare iscrizioni, emissione, aggiornamenti, eventi e utilizzi di un programma già pubblicato. Progettazione e pubblicazione del programma avvengono nel pannello.
Google shares your name, email and profile picture, if available, to verify your identity. This does not subscribe you to marketing. Privacy policy
La disponibilità di notifiche e aggiornamenti dipende dalle funzionalità e dalle regole di ciascuna piattaforma Wallet.
- 01Chiavi con permessi per operazione
- 02Idempotency-Key dove richiesta
- 03Emissione asincrona verificabile
- 04Documentazione in base al perimetro
Cosa puoi integrare
La Wallet API v1 copre l’operatività quotidiana di un programma pubblicato. Il design del pass e la pubblicazione delle versioni restano nel pannello di Vuelvy e non si gestiscono tramite API.
- Iscrizioni, profili e consensi
- Emissione, consultazione e aggiornamento dei pass
- QR code e link di iscrizione
- Eventi, punti, vantaggi e utilizzi
Un esempio minimo del contratto
Per emettere un pass, il tuo sistema invia una richiesta autenticata con la propria chiave e una chiave di idempotenza. L’emissione è asincrona: la risposta conferma che l’operazione è stata accettata, non che il cliente abbia già il pass nel suo Wallet.
- Richiesta: POST /api/wallet/v1/passes con Authorization: Bearer e l’intestazione Idempotency-Key.
- Corpo JSON: programId del programma pubblicato, subscriberId facoltativo e data con i dati del pass.
- Risposta 202: passId, state «pending» e operationIds per verificare lo stato dell’operazione.
- Ripetendo la stessa richiesta con la stessa chiave di idempotenza si ottiene 200, senza creare un altro pass.
Errori espliciti e nuovi tentativi sicuri
Ogni risposta indica se correggere la richiesta, verificare i permessi o riprovare. Le operazioni che richiedono Idempotency-Key, come l’emissione di un pass, possono essere ripetute dopo un’interruzione di rete senza duplicare l’operazione.
- 401 invalid_credentials: chiave assente, revocata o scaduta
- 403 forbidden: la chiave non ha quel permesso
- 400 idempotency_key_required: intestazione mancante in un’operazione che la richiede
- Limite di richieste per chiave
Apple e Google: un contratto comune senza falsa parità
L’API unifica la logica di business e Vuelvy genera la variante per ciascun fornitore. Apple e Google mantengono credenziali, campi, aggiornamenti e avvisi diversi; quando una funzionalità non esiste su una piattaforma, non viene simulata.
Come si ottengono accesso e documentazione
La documentazione tecnica non è pubblica e non esiste una specifica OpenAPI aperta. Se il tuo caso richiede un’integrazione, chiedi una valutazione del perimetro: verifichiamo quali operazioni ti servono, chi è responsabile dell’integrazione e quali dati vengono scambiati. Poi creiamo chiavi con i permessi minimi per la tua organizzazione e condividiamo la documentazione di quegli endpoint secondo l’accesso concordato. Ogni caso viene valutato singolarmente prima della sottoscrizione.
- Caso d’uso e operazioni necessarie
- Permessi minimi per chiave
- Dati personali e consensi verificati
- Piano di test prima di operare con clienti reali
FAQ
Domande frequenti
La documentazione dell’API è pubblica?
No. La documentazione degli endpoint viene condivisa quando si concorda il perimetro tecnico, insieme a chiavi con i permessi minimi per la tua organizzazione.
Posso emettere pass per più brand?
Sì, con chiavi separate: ogni chiave appartiene a un’organizzazione e opera solo su programmi, pass e dati di quell’organizzazione. Un’agenzia con più brand usa chiavi diverse per ogni organizzazione.
Cosa può automatizzare l’API di Wallet Marketing?
L’API collega iscrizioni, emissione dei pass, aggiornamenti, stati ed eventi dell’attività ad Apple Wallet e Google Wallet. Il perimetro è definito per caso d’uso, esponendo solo le operazioni necessarie.
Un’unica integrazione può supportare Apple Wallet e Google Wallet?
Vuelvy unifica la logica di business e adatta l’output a ciascun fornitore. Apple e Google mantengono modelli, credenziali e funzionalità differenti. L’integrazione evita di duplicare le operazioni comuni senza fingere che le piattaforme siano identiche.
Come sono protetti gli accessi all’API e ai dati?
Gli accessi sono autenticati, limitati per organizzazione e registrati per garantire tracciabilità. I dati di ogni brand restano separati; la gestione delle credenziali dei fornitori segue la modalità di emissione definita nel perimetro contrattuale.
L’API invia webhook al mio sistema?
L’integrazione è pensata perché il tuo sistema invii eventi e verifichi lo stato delle operazioni. Se il tuo caso richiede che Vuelvy notifichi un altro sistema, lo valutiamo durante l’analisi del perimetro prima di impegnarci. Le operazioni che richiedono Idempotency-Key possono essere ripetute senza duplicare l’operazione.
Parliamo del tuo caso
Wallet è adatto alla tua attività?
Raccontaci il tuo caso e ti contatteremo via email per valutare integrazioni, piano di avvio e prossimo passo. Senza presentazioni generiche e senza impegno.
Google shares your name, email and profile picture, if available, to verify your identity. This does not subscribe you to marketing. Privacy policy