La REST API di Passinstance è organizzata in controller di dominio modulari esposti principalmente sotto /api/v1 (con mount dedicati privi di prefisso per POS /v1/pos/*, Pull Webhook /webhook-payload, Webhook in ingresso da provider terzi /webhooks/*, probe di stato /health/* e Smart Link /s/:token e /d/:slug). Ogni endpoint utilizza verbi HTTP standard (GET, POST, PUT, PATCH, DELETE), impone l'isolamento multi-tenant del workspace a partire dalla credenziale API e restituisce un payload JSON deterministico (API response (T) sulle API del workspace).
Prerequisiti: Generi una chiave API del workspace (pi_live_... o pi_test_...) con gli API_KEY_SCOPE_VALUES richiesti (passes, templates, scans, webhooks, analytics o *) su /settings/workspace/developer/api-credentials prima di richiamare le route /api/v1/*. La documentazione OpenAPI interattiva è disponibile su GET /api/public/docs e /docs.
Ciclo di vita di richieste e risposte
FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CICLO DI VITA DELLE RICHIESTE REST API E DELL'ENVELOPE
ATTORI DI SISTEMA COINVOLTI
P1Integrazione esterna
P2Passinstance /api/v1/*
P3Provider Wallet e DB
FASE 1RICHIESTA / AZIONEPOST/api/v1/passes
FASE 2RICHIESTA / AZIONEValida DTO e ambito tenant
FASE 3RICHIESTA / AZIONEFirma .pkpass (bundleId)
›
idempotencyKey
›
e genera JWT Google Wallet
FASE 4RISPOSTA201 Created
›
API response (request payload)
FASE 5RICHIESTA / AZIONEPATCH/api/v1/passes/:id
FASE 6RICHIESTA / AZIONEEsegue commit aggiornamento
FASE 7RISPOSTA200 OK
›
7. Accoda push APNs e Google→
[ FLUSSO ARCHITETTURALE: CICLO DI VITA DELLE RICHIESTE REST API E DELL'ENVELOPE ]
Integrazione esterna Passinstance /api/v1/* Provider Wallet e DB
| | |
|-- 1. POST /api/v1/passes --------->| |
| Header: x-api-key: pi_live_.. |-- 2. Valida DTO e ambito tenant |
| Body: externalId, |-- 3. Firma .pkpass (bundleId) |
| idempotencyKey | e genera JWT Google Wallet -->|
|<-- 4. 201 Created -----------------| |
| API response (request payload) | |
| | |
|-- 5. PATCH /api/v1/passes/:id ---->| |
| Body: { attributes: {...} } |-- 6. Esegue commit aggiornamento ->|
|<-- 7. 200 OK ----------------------|-- 7. Accoda push APNs e Google --->|
Catalogo degli endpoint REST per dominio
1. Pass, upsert e operazioni batch
Verbo
Percorso
Descrizione
POST
/api/v1/passes
Emette un'istanza pass (request payload: templateId, externalId opzionale, idempotencyKey, attributes) firmata con il certificato del modello (bundleId = Apple passTypeIdentifier).
POST
/api/v1/passes/upsert-by-external-id
Crea o aggiorna in modo idempotente un pass identificato dalla coppia (templateId, externalId) (request payload).
GET
/api/v1/passes
Elenca le istanze pass con paginazione, filtro per stato (pass status) e query di ricerca.
GET
/api/v1/passes/:id
Recupera tutti i dettagli, gli attributi dinamici, externalId, serialNumber e lo stato di registrazione.
PATCH / PUT
/api/v1/passes/:id
Aggiorna campi dinamici, livello o data di scadenza e invia aggiornamenti live ai Wallet installati.
POST
/api/v1/passes/voiding/:id/void
Annulla un pass (request payload + VoidingReason) e invia un aggiornamento push silenzioso voided: true.
DELETE
/api/v1/passes/:id
Elimina logicamente un pass e revoca le installazioni Wallet attive.
POST
/api/v1/passes/export
Esporta i record pass filtrati come job di download CSV UTF-8 o JSON.
POST
/api/v1/batch-pass-operations/create
Esegue la creazione massiva sincrona/accodata di pass tramite Batch Operations API (disponibili anche /update, /upsert, /activate, /deactivate, /delete).
POST
/api/v1/batch-processing
Invia un grande job asincrono CSV/JSON tracciato tramite Batch Processing API.
2. Modelli e meccaniche
Verbo
Percorso
Descrizione
GET
/api/v1/templates
Elenca i modelli di pass del workspace, i tipi di pass (PassKind), i binding ai certificati bundleId e gli stati di pubblicazione.
GET
/api/v1/templates/:id
Restituisce lo schema del modello, la configurazione del layout visivo e le meccaniche attive.
POST
/api/v1/templates/:id/publish
Pubblica le modifiche in bozza (request payload) e invia aggiornamenti push in batch (esegua prima GET .../publish-risk-check).
GET
/api/v1/templates/:templateId/attributes
Elenca chiavi e tipi dei campi dinamici richiesti all'emissione dei pass (supporta OAuth templates:read).
POST
/api/v1/mechanics/redeem
Riscatta un premio fedeltà o tessera a timbri sbloccato (request payload: UUID passId, mechanicId).