Skip to content
Guida del Centro assistenza
4 min di letturaVerificato 2026-11-16

Badge aziendali e pass di accesso

Emetti credenziali per staff, collaboratori e visitatori con scadenza, controllo 2D e revoca immediata.

In questa guida

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:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ACCESSO DIPENDENTI E REVOCA
ATTORI DI SISTEMA COINVOLTI
P1 Sistema HR / REST API
P2 Passinstance Core API
P3 Lettore porta / Scanner
P4 Pass Wallet mobile
FASE 1 RICHIESTA / AZIONE POST/api/v1/passes
FASE 2 RICHIESTA / AZIONE Provisioning Pass e NFC
FASE 3 RICHIESTA / AZIONE Aggiungi al Wallet
›
(Foto ID + Biometria)
FASE 4 RISPOSTA Tocco sul lettore
FASE 5 RISPOSTA POST/api/v1/scans
›
(NFC ISO 14443 / QR)
›
(Verifica ACTIVE e turno)
FASE 6 RICHIESTA / AZIONE Accesso consentito (200)
FASE 7 RICHIESTA / AZIONE POST/api/v1/passes/voiding/:id/void
FASE 8 RICHIESTA / AZIONE Push APNs silenziosa
›
(walletVoidStatus)
›
(Il tornello rifiuta
›
scansioni future)

Layout visivo e slot risorse

  • Tipo di pass (pass type): studentId, generic oppure posterGeneric (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 in externalId (max 255 caratteri, univoco tra i pass attivi del tenant) così che i webhook automatici di offboarding possano annullare o aggiornare i pass tramite POST /api/v1/passes/upsert-by-external-id o GET /api/v1/passes/by-external-id/:externalId.
  • Modelli demo a catalogo: student-id-card, daily-access-pass e conference-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 logo e strip con 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 Engine risolve 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:

JSON
{
  "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

POST /api/v1/passes/voiding/:id/void
Header
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "EMPLOYEE_OFFBOARDED",
    "sendPushNotification": false
  }
}

Risultato

  1. 1
    Lo stato status del pass transita a VOIDED, lifecycleStatus (PassLifecycleStatus) passa a VOIDED e l'endpoint restituisce HTTP 204 No Content. Nota: options.reason accetta VoidingReason (EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER).
  2. 2
    Tutte le scansioni successive ai tornelli o ai varchi con scanner mobile vengono rifiutate con decisione ALREADY_VOIDED.
  3. 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à.

Documentazione prodotto e API correlata

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.