Skip to content
Guia da Central de Ajuda · Gestão de passesFase de integração 3
3 min de leituraVerificado 2026-11-16

Ver e atualizar passes

Pesquise cartões com vistas guardadas e filtros E/OU, inspecione dispositivos registados e edite atributos.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface1 / 2
Elementos-chave da interface

Lista de passes emitidos e ações (Ampliado)

Acesse Passes para inspecionar testes, filtrar por ciclo ou instalação e abrir QR code, detalhes, edição ou push.

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.

Filtros de pesquisa de passes e telemetria por linha
Filtros de pesquisa de passes e telemetria por linha

Arquitetura do sistema: Consulta, alteração e troca de modelo de passes

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CONSULTA DE PASSES, PATCH E TROCA DE MODELO
ETAPA 01 CONSTRUTOR DE FILTROS DO PAINEL / API REST (/api/v1/passes)
Pesquisar/Filtrar: GET/api/v1/passes?templateId=...&status=ACTIVE&...
Atualização Parcial:PATCH/api/v1/passes/:id
Auditoria/Cronol.: GET/api/v1/passes/:id/history e /timeline
Trocar Modelo: POST/api/v1/passes/:id/switch-template/:targetTemplateId
ETAPA 02 MOTOR DE CONSULTA DATABASE E INDEXAÇÃO DE ATRIBUTOS
Índices relacionais em (customerId, templateId, status, externalId)
Filtragem structured JSON em submilissegundos via índice GIN attribute search index
Acrescenta registos imutáveis de diferenças em pass audit log e cronologia Scan
ETAPA 03 PROPAGAÇÃO PUSH PARA CARTEIRAS (WalletPropagationStatus)
Transita estado de propagação: PENDINGQUEUEDSUCCEEDED
Apple Wallet: Envia push de despertar APNs HTTP/2iOS obtém .pkpass
Google Wallet: Executa REST PATCH no recurso cloud walletobjects

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, idempotencyKey ou id do 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 Installed ou Removed entre registos de dispositivos Apple Wallet (iOS) e Google Wallet (Android).
  • Janelas de datas: Filtros por intervalo em createdAt, updatedAt, expirationDate e lastScannedAt.
  • Atributos personalizados structured JSON (attribute search index): Filtros de contenção e comparação de alta velocidade para qualquer chave dentro de pass.attributes (por exemplo, attributes.memberTier = "VIP" ou attributes.pointsBalance >= 1000).
Gaveta de filtros avançados com construtor de condições E/OU
Gaveta de filtros avançados com construtor de condições E/OU

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 a externalId sem armazenar UUIDs internos externamente)
Cabeçalhos
X-API-Key <API_KEY>

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

JSON
{
  "attributes": {
    "pointsBalance": 1450,
    "memberTier": "Platinum"
  },
  "barcodeAltText": "44910-PLATINUM",
  "expirationDate": "2028-12-31 23:59"
}

Resposta HTTP (200 OK)

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

EndpointEscopo e dados devolvidos
GET /api/v1/passes/:id/historyDevolve alterações cronológicas de campos e atributos (previousValue, newValue, changedBy, `source: 'API' \'SCANNER' \'DASHBOARD' \'WORKFLOW', timestamp`).
GET /api/v1/passes/:id/timelineDevolve 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

GET /api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
JSON
{
  "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

JSON
{
  "preserveAttributes": true,
  "attributeOverrides": {
    "vipLoungeAccess": "Unlimited"
  },
  "pushUpdateImmediately": true
}

Importante: Para mudar um passe para :targetTemplateId sem falhas em dispositivos Apple Wallet, tanto o modelo de origem como o modelo de destino têm de partilhar o mesmo Apple passTypeIdentifier (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.

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.