Visão geral
Abra Passes no Painel (tanto no diretório global do espaço de trabalho como no separador Passes de um modelo específico) ou consulte /api/v1/passes para inspecionar, filtrar, auditar, atualizar e migrar registos de passes emitidos em tempo real. Cada alteração nos campos de um registo de passe ou na atribuição do modelo sincroniza automaticamente para os dispositivos Apple Wallet e Google Wallet registados.

Arquitetura do sistema: Consulta, alteração e troca de modelo de passes
1. Pesquisar e filtrar passes (GET /api/v1/passes)
No Painel, abra Filtros para combinar Grupos de Condições E / OU entre colunas de sistema e atributos structured JSON personalizados e guarde consultas frequentes como Vistas Guardadas:
-
Identidade e chaves:
serialNumber,externalId,bundleId,idempotencyKeyouiddo passe. -
Ciclo de vida e estado:
status(pass status),lifecycleStatus(PassLifecycleStatus),walletVoidStatus(WalletPropagationStatus) e prontidão dos artefactos (appleArtifactStatus,googleArtifactStatus). -
Estado de instalação na carteira:
Installed,Not InstalledouRemovedentre registos de dispositivos Apple Wallet (iOS) e Google Wallet (Android). -
Janelas de datas: Filtros por intervalo em
createdAt,updatedAt,expirationDateelastScannedAt. -
Atributos personalizados structured JSON (
attribute search index): Filtros de contenção e comparação de alta velocidade para qualquer chave dentro depass.attributes(por exemplo,attributes.memberTier = "VIP"ouattributes.pointsBalance >= 1000).

Exemplo: Consultar passes e pesquisar por ID externo
-
GET /api/v1/passes?templateId=tmpl_01hxyz987654321&status=ACTIVE&externalId=crm_usr_44910&page=1&limit=25 -
GET /api/v1/passes/by-external-id/crm_usr_44910(devolve diretamente o passe ativo não eliminado correspondente aexternalIdsem armazenar UUIDs internos externamente)
2. Atualizar um passe individual (PATCH /api/v1/passes/:id)
Atualizar um passe funde novos valores em attributes, ajusta expirationDate ou barcodeValue e coloca em fila uma atualização push imediata para todos os dispositivos onde o passe está instalado. Se um campo alterado tiver uma changeMessage contendo %@ configurada no modelo, a Apple Wallet apresenta um alerta nativo no ecrã bloqueado.
Pedido HTTP
PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"attributes": {
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"barcodeAltText": "44910-PLATINUM",
"expirationDate": "2028-12-31 23:59"
}
Resposta HTTP (200 OK)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"serialNumber": "PI-GOLD-2026-44910",
"externalId": "crm_usr_44910",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"updatedAt": "2026-11-15T17:30:00.000Z"
},
"statusCode": 200
}
3. Auditar histórico do passe e cronologia de eventos
A Passinstance mantém dois fluxos de auditoria complementares para cada registo de passe:
| Endpoint | Escopo e dados devolvidos | |||
|---|---|---|---|---|
GET /api/v1/passes/:id/history | Devolve alterações cronológicas de campos e atributos (previousValue, newValue, changedBy, `source: 'API' \ | 'SCANNER' \ | 'DASHBOARD' \ | 'WORKFLOW', timestamp`). |
GET /api/v1/passes/:id/timeline | Devolve o fluxo unificado de ciclo de vida e interação, combinando criação do passe, eventos de envio por e-mail/SMS, instalações Apple/Google nos dispositivos, validações em scanner, ajustes de saldo e notificações push. |
Exemplo: Obter cronologia do passe
/api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
{
"success": true,
"data": {
"passId": "pass_01j8k9m2n3p4q5r6",
"events": [
{
"eventId": "evt_03",
"type": "ATTRIBUTE_UPDATED",
"summary": "pointsBalance changed from 500 to 1450",
"actor": "api_key:pi_live_99a8",
"createdAt": "2026-11-15T17:30:00.000Z"
},
{
"eventId": "evt_02",
"type": "WALLET_INSTALLED",
"platform": "APPLE_WALLET",
"deviceLibraryIdentifier": "dlib_8841209a",
"createdAt": "2026-11-15T15:10:05.000Z"
},
{
"eventId": "evt_01",
"type": "PASS_CREATED",
"summary": "Pass issued via REST API",
"createdAt": "2026-11-15T15:04:12.000Z"
}
]
},
"statusCode": 200
}
4. Migração de modelo em direto (POST /api/v1/passes/:id/switch-template/:targetTemplateId)
Quando um cliente sobe para o design de um novo patamar ou transita entre programas sazonais, pode migrar um passe existente para um modelo PUBLISHED diferente sem alterar o id, serialNumber, authenticationToken nem os registos de dispositivos ativos do passe.
POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"preserveAttributes": true,
"attributeOverrides": {
"vipLoungeAccess": "Unlimited"
},
"pushUpdateImmediately": true
}
Importante: Para mudar um passe para
:targetTemplateIdsem falhas em dispositivos Apple Wallet, tanto o modelo de origem como o modelo de destino têm de partilhar o mesmo ApplepassTypeIdentifier(Certificado Pass Type ID). Se o modelo de destino utilizar um Pass Type ID diferente, o iOS trata-o como um cartão distinto em vez de uma substituição visual no local.
Para transições de estado e regras de anulação, consulte Ciclo de vida e estados do passe. Para atualizações em vários registos, consulte Operações em lote.
