Skip to content
Guida del Centro assistenza · API per sviluppatori
6 min di letturaVerificato 2026-11-16

Riferimento API

Esplora tutti gli endpoint REST per Pass, Modelli, Scanner, Consegna, Webhook e Operazioni batch.

In questa guida

Panoramica

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
P1 Integrazione esterna
P2 Passinstance /api/v1/*
P3 Provider Wallet e DB
FASE 1 RICHIESTA / AZIONE POST/api/v1/passes
FASE 2 RICHIESTA / AZIONE Valida DTO e ambito tenant
FASE 3 RICHIESTA / AZIONE Firma .pkpass (bundleId)
›
idempotencyKey
›
e genera JWT Google Wallet
FASE 4 RISPOSTA 201 Created
›
API response (request payload)
FASE 5 RICHIESTA / AZIONE PATCH/api/v1/passes/:id
FASE 6 RICHIESTA / AZIONE Esegue commit aggiornamento
FASE 7 RISPOSTA 200 OK
›
7. Accoda push APNs e Google

Catalogo degli endpoint REST per dominio

1. Pass, upsert e operazioni batch

VerboPercorsoDescrizione
POST/api/v1/passesEmette 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-idCrea o aggiorna in modo idempotente un pass identificato dalla coppia (templateId, externalId) (request payload).
GET/api/v1/passesElenca le istanze pass con paginazione, filtro per stato (pass status) e query di ricerca.
GET/api/v1/passes/:idRecupera tutti i dettagli, gli attributi dinamici, externalId, serialNumber e lo stato di registrazione.
PATCH / PUT/api/v1/passes/:idAggiorna campi dinamici, livello o data di scadenza e invia aggiornamenti live ai Wallet installati.
POST/api/v1/passes/voiding/:id/voidAnnulla un pass (request payload + VoidingReason) e invia un aggiornamento push silenzioso voided: true.
DELETE/api/v1/passes/:idElimina logicamente un pass e revoca le installazioni Wallet attive.
POST/api/v1/passes/exportEsporta i record pass filtrati come job di download CSV UTF-8 o JSON.
POST/api/v1/batch-pass-operations/createEsegue la creazione massiva sincrona/accodata di pass tramite Batch Operations API (disponibili anche /update, /upsert, /activate, /deactivate, /delete).
POST/api/v1/batch-processingInvia un grande job asincrono CSV/JSON tracciato tramite Batch Processing API.

2. Modelli e meccaniche

VerboPercorsoDescrizione
GET/api/v1/templatesElenca 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/:idRestituisce lo schema del modello, la configurazione del layout visivo e le meccaniche attive.
POST/api/v1/templates/:id/publishPubblica le modifiche in bozza (request payload) e invia aggiornamenti push in batch (esegua prima GET .../publish-risk-check).
GET/api/v1/templates/:templateId/attributesElenca chiavi e tipi dei campi dinamici richiesti all'emissione dei pass (supporta OAuth templates:read).
POST/api/v1/mechanics/redeemRiscatta un premio fedeltà o tessera a timbri sbloccato (request payload: UUID passId, mechanicId).
GET/api/v1/mechanics/:mechanicId/passes/:passId/ledgerRestituisce il mastro transazioni per la meccanica prepagata o fedeltà di un pass (GET /api/v1/balance-changes per il feed del tenant).

3. Scansioni, dispositivi e validazione POS

VerboPercorsoDescrizione
POST/api/v1/scansValuta una scansione barcode/NFC rispetto alla pipeline a 14 regole Validation Rules Engine (ScanMode e scan status).
POST/api/v1/scans/prepareEmette un scan nonce crittografico a breve durata per la protezione anti-replay.
GET/api/v1/scans/passRicerca pass in sola lettura tramite ?barcode=... (o parametro di percorso GET /api/v1/scans/pass/:barcodeValue).
POST/api/v1/scans/pass/:passId/useEsegue direttamente un'azione request payload (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET).
GET/api/v1/scans/result/:scanIdRecupera il record di audit e il ruleTrace di una scansione completata.
GET/api/v1/scans/offline-datasetSnapshot dei pass paginato con cursore (offline scan dataset) per scanner portatili offline.
POST/v1/pos/redeemEndpoint POS privo di prefisso che esegue comandi atomici PosOperation (DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, CUSTOM).
POST/api/v1/reader/redeemElabora i riscatti di lettori NFC hardware autenticati tramite X-Reader-Secret (POST /api/v1/reader/validate per la validazione in ingresso).

4. Notifiche push, webhook e workflow

VerboPercorsoDescrizione
POST/api/v1/push-notifications/templates/:id/sendInvia una notifica immediata a tutti i dispositivi registrati per un modello (request payload su /passes/:id/schedule).
POST/api/v1/push-notifications/segmentationIndirizza un segmento filtrato di pass (request payload) con aggiornamenti push localizzati.
POST/api/v1/push-notifications/batchInvia notifiche batch su elenchi di pass o caricamenti CSV (request payload).
GET / POST/api/v1/webhooksRecupera la panoramica webhook o gestisce gli endpoint HTTPS push in uscita (/api/v1/webhooks/subscriptions).
GET/webhook-payloadPull API priva di prefisso (supportato anche GET /api/v3/webhook-payload) che interroga gli eventi non confermati per riceventi dietro firewall.
POST/webhook-payload/acknowledgeConferma di lettura priva di prefisso ({ upTo, webhookId }, oppure POST /api/v3/webhook-payload/acknowledge).
GET / POST/api/v1/workflowsElenca o crea workflow automatizzati basati su eventi (Workflow Engine API, insieme a /api/v1/automations).

5. Analytics, fatturazione e governance privacy

VerboPercorsoDescrizione
GET/api/v1/analyticsReport telemetrico multiserie (passes, registrations, walletAppsShare; veda /api/v1/analytics/passes/overview).
GET/api/v1/analytics/wallet-installationsMatrice di installazione Apple Wallet vs. Google Wallet a livello dispositivo e pass (request payload).
GET/api/v1/billing/subscriptionRestituisce piano di abbonamento attivo, ciclo di fatturazione e stato di rinnovo.
GET/api/v1/billing/invoices/:id/downloadTrasmette in streaming la fattura fiscale in PDF (application/pdf).
POST/api/v1/customer/:customerId/privacy-settings/data-subject-exportGenera un archivio dei dati personali conforme al GDPR per un titolare del pass.

Envelope standard API response (T) e codici di stato

Envelope di successo (200 OK / 201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01hxyz8821",
    "templateId": "tmpl_vip_member",
    "serialNumber": "PI-VIP-8821",
    "externalId": "crm_cust_44910",
    "bundleId": "pass.com.passinstance.vip",
    "status": "ACTIVE",
    "passAccessUrl": "https://api.passinstance.com/s/vip-8821-x9a2"
  },
  "meta": {
    "requestId": "req_99481a2b7c",
    "timestamp": "2026-11-16T10:10:00.000Z"
  }
}

Codici di stato HTTP standard

Codice di statoSignificatoRisoluzione
200 OK / 201 CreatedRichiesta riuscita in modo sincrono.Legga il payload di risultato dentro data.
400 Bad RequestValidazione DTO non superata o vincolo di dominio violato.Ispezioni errorCode, messageKey e l'array details.
401 UnauthorizedChiave API o token Bearer mancante, scaduto o non valido.Verifichi l'header x-api-key o Authorization (e la corrispondenza workspace pi_test_ vs pi_live_).
403 ForbiddenLa chiave è valida ma non possiede l'ambito richiesto (es. 'passes') o l'accesso al tenant.Verifichi gli ambiti assegnati tramite GET /api/v1/api-keys.
404 Not FoundL'ID della risorsa di destinazione non esiste nel workspace autenticato.Verifichi UUID / serialNumber / externalId e ambiente del workspace.
409 ConflictexternalId o serialNumber duplicato oppure collisione concorrente di idempotenza.Utilizzi /api/v1/passes/upsert-by-external-id o fornisca una idempotencyKey univoca.
429 Too Many RequestsSuperato il limite di raffica al secondo o la quota di rate limit.Rispetti gli header di risposta Retry-After e RateLimit-Reset.

Consulti le definizioni complete degli schemi nell'Hub Documentazione Sviluppatori e in Panoramica API e autenticazione.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.