Panoramica
Le organizzazioni utilizzano Passinstance per sostituire badge e tessere magnetiche in plastica con credenziali digitali sicure e personalizzate con il proprio brand in Apple Wallet e Google Wallet. Dipendenti, collaboratori esterni, studenti e visitatori accedono a sedi aziendali, campus di coworking e laboratori riservati tramite tornelli con lettura ottica 2D o lettori NFC contactless.
Architettura backend e schema visivo
I pass identificativi sono progettati con metadati del dipendente ben leggibili e protezioni visive anticontraffazione:
Layout visivo e slot risorse
-
Tipo di pass (pass type):
studentId,genericoppureposterGeneric(Apple Wallet e Google Wallet li mostrano con proporzioni dedicate alle carte d'identità). -
Correlazione HRIS e directory (
externalId): Memorizzi l'ID dipendente della directory aziendale o del sistema HR inexternalId(max 255 caratteri, univoco tra i pass attivi del tenant) così che i webhook automatici di offboarding possano annullare o aggiornare i pass tramitePOST /api/v1/passes/upsert-by-external-idoGET /api/v1/passes/by-external-id/:externalId. -
Modelli demo a catalogo:
student-id-card,daily-access-passeconference-badge. -
Identificazione fotografica: Carichi le foto ritratto del personale nello slot
thumbnail(90x90 pt a @1x, 270x270 px a @3x). Google Wallet le renderizza come avatar circolare o quadrato in evidenza. -
Branding aziendale: Banner fisso
logoestripcon i colori dell'azienda o del campus. -
Metadati dinamici del dipendente:
- primaryFields: Nome completo del dipendente ({fullName}). - secondaryFields: Ruolo ({title}) e Dipartimento ({department}). - auxiliaryFields: ID dipendente ({employeeId}) e Livello di autorizzazione ({clearanceLevel}). - backFields: Procedure d'emergenza dell'edificio, recapiti telefonici di sicurezza e link all'helpdesk IT.
-
Animazione dinamica anti-screenshot (
addSecurityAnimation: true): Genera un perimetro visivo animato variabile nel tempo sul pass per impedire l'uso di screenshot statici o foto condivise.
Meccaniche di controllo accessi e rilevazione presenze
Per la registrazione delle presenze quotidiane in sede, la gestione dei turni o il controllo dei buoni pasto, i pass identificativi possono collegare meccaniche interattive:
-
Tipo di meccanica:
VALID_ONCE_PER_DAY. -
Risoluzione del fuso orario (
resolveCustomerTimeZone):Pass Mechanics Enginerisolve il fuso orario della sede del titolare del pass (es.Europe/London). Dopo una scansione al tornello d'ingresso, ulteriori scansioni nello stesso giorno solare restituiscono un avviso senza registrare due volte la presenza. -
Modalità di scansione (
ScanMode) ed esiti (scan status):
- CHECK_IN: Registra l'orario di ingresso all'entrata (CHECK_IN_SUCCESS, oppure ALREADY_CHECKED_IN se già presente all'interno). - CHECK_OUT: Registra l'uscita al varco d'uscita (CHECK_OUT_SUCCESS, oppure ALREADY_CHECKED_OUT). - CHECK_IN_CHECK_OUT_TOGGLE: Alterna automaticamente lo stato tra presente in sede e fuori sede a ogni scansione al lettore. - SAVE_ATTENDANCE: Registra eventi ripetibili di ingresso senza commutare lo stato dentro/fuori.
Accesso varchi contactless NFC (Apple VAS e Google Smart Tap)
Passinstance supporta la trasmissione hardware contactless delle credenziali su livello fisico ISO/IEC 14443 Tipo A/B:
Dizionario di configurazione NFC del pass
Quando si configura l'accesso contactless alle porte, lo schema nfc viene inserito nel payload del pass:
{
"nfc": {
"message": "FACILITY_ACCESS_NODE_772",
"encryptionPublicKey": "04a1b2c3d4e5f6...",
"requiresAuthentication": true,
"nfcFaceIdRequired": true,
"nfcNoBarcode": false
}
}
-
requiresAuthentication/nfcFaceIdRequired: Richiede all'utente la verifica tramite Face ID, Touch ID o codice di sblocco prima che il payload NFC venga trasmesso al lettore della porta. -
nfcNoBarcode: Sopprime la visualizzazione del codice a barre ottico sul fronte del pass nei tornelli ad alta sicurezza esclusivamente NFC. -
Lettori hardware compatibili: Si integra con lettori certified NFC, Identiv e HID abbinati a Passinstance tramite le configurazioni
hardware reader/reader device.
API per offboarding e revoca istantanea
Quando un dipendente lascia l'organizzazione oppure un badge temporaneo da collaboratore scade, l'accesso deve essere revocato immediatamente:
Endpoint di revoca
/api/v1/passes/voiding/:id/void
{
"voided": true,
"options": {
"reason": "CANCELLED",
"customReason": "EMPLOYEE_OFFBOARDED",
"sendPushNotification": false
}
}
Risultato
-
1
Lo stato
statusdel pass transita aVOIDED,lifecycleStatus(PassLifecycleStatus) passa aVOIDEDe l'endpoint restituisce HTTP204 No Content. Nota:options.reasonaccettaVoidingReason(EXPIRED,CANCELLED,LOST,STOLEN,DUPLICATE,FRAUD,TECHNICAL_ISSUE,CUSTOMER_REQUEST,ADMIN_ACTION,SYSTEM_AUTO,OTHER). -
2
Tutte le scansioni successive ai tornelli o ai varchi con scanner mobile vengono rifiutate con decisione
ALREADY_VOIDED. -
3
Passinstance aggiorna
walletVoidStatus(WalletPropagationStatus:NONE->PENDING->QUEUED->SUCCEEDED) man mano che i worker in background inviano l'aggiornamento via Apple APNs HTTP/2 e Google Wallet REST API.
Importante: L'accesso contactless ai varchi tramite Apple Wallet richiede un certificato merchant Apple VAS (Value Added Services) approvato da Apple Developer Relations. La scansione ottica QR/Aztec funziona immediatamente su fotocamere standard e lettori hardware 2D.
Scopra di più sulle nostre Soluzioni di accesso e identità.
