Skip to content
Guia da Central de Ajuda
4 min de leituraVerificado 2026-11-16

Cartões de colaborador e acesso

Emita credenciais para equipa, parceiros e visitantes com validade, verificação 2D e revogação instantânea.

Neste guia

Visão geral

As organizações utilizam a Passinstance para substituir cartões de plástico físicos e crachás por credenciais digitais seguras e personalizadas na Apple Wallet e Google Wallet. Colaboradores, prestadores externos, estudantes e visitantes acedem a edifícios de escritórios, campus partilhados e laboratórios restritos através de torniquetes de código de barras ótico 2D ou leitores NFC sem contacto.

Arquitetura no backend e esquema visual

Os passes de identidade são concebidos com metadados de colaborador de alta visibilidade e salvaguardas visuais antifalsificação:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
ACESSO E REVOGAÇÃO DE COLABORADORES
ATORES DE SISTEMA PARTICIPANTES
P1 Sistema RH / API REST
P2 API Principal Passinstance
P3 Leitor Porta / Scanner
P4 Passe na Carteira Móvel
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/passes
ETAPA 2 PEDIDO / AÇÃO Provisionar Passe e NFC
ETAPA 3 PEDIDO / AÇÃO Adicionar Carteira
›
(Foto ID + Biometria)
ETAPA 4 RESPOSTA Aproximar Leitor
ETAPA 5 RESPOSTA POST/api/v1/scans
›
(NFC ISO 14443 / QR)
›
(Verificar ACTIVE e turno)
ETAPA 6 PEDIDO / AÇÃO Acesso Permitido (200)
ETAPA 7 PEDIDO / AÇÃO POST/api/v1/passes/voiding/:id/void
ETAPA 8 PEDIDO / AÇÃO Push APNs Silencioso
›
(walletVoidStatus)
›
(Torniquete rejeita
›
leituras seguintes)

Layout visual e slots de ativos

  • Tipo de Passe (pass type): studentId, generic ou posterGeneric (a Apple Wallet e a Google Wallet apresentam-nos com proporções dedicadas a cartões de identificação).
  • Correlação HRIS e diretório (externalId): Guarde o ID de colaborador do seu diretório/RH em externalId (máx. 255 carateres, único entre passes ativos do tenant) para que webhooks automáticos de saída anulem ou atualizem passes via POST /api/v1/passes/upsert-by-external-id ou GET /api/v1/passes/by-external-id/:externalId.
  • Modelos Demo de Catálogo: student-id-card, daily-access-pass e conference-badge.
  • Identificação fotográfica: Carregue fotografias de retrato dos colaboradores no slot de ativos thumbnail (90x90 pt a @1x, 270x270 px a @3x). A Google Wallet apresenta-o como um avatar circular ou quadrado em destaque.
  • Identidade visual da organização: logo fixo e faixa strip com as cores da empresa ou campus.
  • Metadados dinâmicos do colaborador:

- primaryFields: Nome completo do colaborador ({fullName}). - secondaryFields: Cargo ({title}) e Departamento ({department}). - auxiliaryFields: ID de colaborador ({employeeId}) e Nível de autorização ({clearanceLevel}). - backFields: Protocolos de emergência do edifício, telefones de contacto de segurança e ligações para o suporte técnico de TI.

  • Animação dinâmica anticaptura de ecrã (addSecurityAnimation: true): Gera um perímetro visual animado e variável no tempo sobre o passe para impedir capturas de ecrã estáticas ou fraude com fotografias partilhadas.

Mecânicas de controlo de acessos e registo de assiduidade

Para assiduidade diária nas instalações, controlo de turnos ou gestão de subsídios de refeição, os passes de identidade podem associar mecânicas interativas:

  • Tipo de Mecânica: VALID_ONCE_PER_DAY.
  • Resolução de fuso horário (resolveCustomerTimeZone): O Pass Mechanics Engine resolve o fuso horário da localização do edifício do titular (ex.: Europe/London). Após leitura num torniquete de receção, leituras subsequentes no mesmo dia civil devolvem um aviso sem duplicar o registo de presença.
  • Modos de Leitura (ScanMode) e Resultados (scan status):

- CHECK_IN: Regista a hora de chegada à entrada do edifício (CHECK_IN_SUCCESS ou ALREADY_CHECKED_IN se já estiver no interior). - CHECK_OUT: Regista a saída no portão de saída (CHECK_OUT_SUCCESS ou ALREADY_CHECKED_OUT). - CHECK_IN_CHECK_OUT_TOGGLE: Alterna automaticamente o estado entre no interior e no exterior a cada leitura no leitor. - SAVE_ATTENDANCE: Regista eventos repetíveis de check-in sem alternar o estado de entrada.

Acesso NFC sem contacto às portas (Apple VAS e Google Smart Tap)

A Passinstance suporta transmissão física de credenciais sem contacto sobre a camada física ISO/IEC 14443 Tipo A/B:

Dicionário de configuração NFC do passe

Ao configurar o acesso sem contacto às portas, o esquema nfc é injetado no payload do passe:

JSON
{
  "nfc": {
    "message": "FACILITY_ACCESS_NODE_772",
    "encryptionPublicKey": "04a1b2c3d4e5f6...",
    "requiresAuthentication": true,
    "nfcFaceIdRequired": true,
    "nfcNoBarcode": false
  }
}
  • requiresAuthentication / nfcFaceIdRequired: Solicita ao utilizador verificação via Face ID, Touch ID ou código de acesso antes de transmitir o payload NFC para o terminal leitor da porta.
  • nfcNoBarcode: Oculta o código de barras ótico da face do passe quando implementa torniquetes seguros exclusivos de NFC.
  • Leitores de hardware compatíveis: Integra com leitores certified NFC, Identiv e HID emparelhados com a Passinstance através das configurações hardware reader / reader device.

API de desativação imediata e revogação

Quando um colaborador sai da organização ou um crachá temporário de prestador expira, o acesso deve ser revogado de imediato:

Endpoint de revogação

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

Resultado

  1. 1
    O status do passe transita para VOIDED, o lifecycleStatus (PassLifecycleStatus) transita para VOIDED e o endpoint devolve HTTP 204 No Content. Note que options.reason aceita VoidingReason (EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER).
  2. 2
    Todas as leituras subsequentes nos torniquetes ou controlos com scanner móvel são rejeitadas com a decisão ALREADY_VOIDED.
  3. 3
    A Passinstance atualiza walletVoidStatus (WalletPropagationStatus: NONE -> PENDING -> QUEUED -> SUCCEEDED) à medida que os workers em segundo plano enviam a atualização via APNs HTTP/2 e Google Wallet REST API.

Importante: O acesso sem contacto a portas na Apple Wallet requer um certificado comercial aprovado de Apple VAS (Value Added Services) obtido junto das Relações com Programadores da Apple. A leitura ótica por QR/Aztec funciona de imediato com câmaras padrão e hardware de códigos de barras 2D.

Saiba mais sobre as nossas Soluções de Acesso e Identidade.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.