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

Operações em lote

Execute ações em massa sobre grupos filtrados: atualizações múltiplas, anulação, eliminação e exportações.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Aba Passes e Ações em Massa (Ampliado)

Após importar em lote, use Passes, filtros e o menu Bulk actions para revisar ou atualizar os cartões.

Visão geral

Assim que isolar uma coorte de passes pretendida no Painel utilizando os Filtros Rápidos ou o Painel de Filtros Avançados E/OU (StickySelectionToolbar), utilize o menu Ações em massa na barra de ferramentas de Passes — ou invoque a Batch Operations API (/api/v1/batch-pass-operations/*) através da API REST — para executar operações estruturadas em array sobre até 1.000 passes por chamada. Ao contrário dos carregamentos multipart de ficheiros CSV (/api/v1/batch-processing), /api/v1/batch-pass-operations/* processa diretamente payloads JSON e devolve errors e warnings por item em request payload.

Ao atualizar milhares ou dezenas de milhares de passes emitidos em simultâneo, a Passinstance desacopla as mutações na base de dados da entrega de notificações push às carteiras móveis. As alterações são persistidas imediatamente na base de dados, enquanto as atualizações são difundidas para dispositivos Apple Wallet através de ligações HTTP/2 APNs em pool com limitação de taxa e para dispositivos Google Wallet através de propagação instantânea da Issuer Class ou patches REST individuais no Pass Object.

Arquitetura do sistema: Operações em massa, limitação de filas e propagação para carteiras

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
OPERAÇÕES EM MASSA E PROPAGAÇÃO PARA CARTEIRAS
ETAPA 01 BARRA DE AÇÕES EM MASSA DO PAINEL / API (Batch Operations API)
Seleção de Coorte (StickySelectionToolbar / Painel de Filtros / IDs de Passes)
POST/api/v1/batch-pass-operations/update (operation: "update")
POST/api/v1/batch-pass-operations/upsert (Indexado por externalId)
POST/api/v1/batch-pass-operations/activate (operation: "activate")
POST/api/v1/batch-pass-operations/deactivate (operation: "deactivate")
POST/api/v1/batch-pass-operations/delete (request payload)
POST/api/v1/batch-pass-operations/validate (Verificação prévia payload)
ETAPA 02 MOTOR ISOLADO DE VALIDAÇÃO E EXECUÇÃO POR ITEM
Remove chaves protegidas do tenant (customerId, tenantId, createdBy)
Pré-valida atributos via preValidateAttributes (ignora obrigatórios em upd.)
Normaliza atributos via normalizeAttributes
Devolve request payload: { success, data, message, errors, warnings }
ETAPA 03A FILA DE WORKERS HTTP/2 APNs LIMITADA
fila de tarefas: push-notifications
Pool de ligações HTTP/2 persistentes
Limitação evita erros 429 da Apple
Push silencioso acorda o dispositivo
ETAPA 03B PROPAGAÇÃO DE CLASSE GOOGLE WALLET
Alteração modelo: PATCH Issuer Class
Sincronização instantânea Android
PATCH individual Pass Object para atributos dinâmicos por passe

Filtrar coortes de passes alvo

Antes de executar operações em massa, os administradores isolam exatamente a coorte de audiência a modificar:

Filtros rápidos e painel de filtros avançados E/OU

No Painel em Passes (/passes):

  • Filtro de Modelo: Limite as ações a um modelo de passe específico ou a um design de cartão de campanha.
  • Filtro de Estado: Filtre pelo estado do ciclo de vida (ACTIVE, INACTIVE, SUSPENDED, EXPIRED, VOIDED).
  • Filtro de Situação: Distinga entre active_only (instalado em pelo menos um dispositivo), inactive_only (desinstalado) e not_registered (ligações de transferência não reclamadas).
  • Painel de Pesquisa Avançada (Advanced Filter panel): Combine múltiplos atributos utilizando lógica E/OU (por exemplo, tier == "Gold" E pointsBalance < 500 E expirationDate < 2027-01-01).
  • Barra de Seleção Fixa (StickySelectionToolbar):

- Clique na caixa de seleção principal para selecionar a página atual (até 100 passes). - Clique na faixa de confirmação para selecionar todos os passes correspondentes em todas as páginas (por exemplo, "Selecionar todos os 4.850 passes correspondentes a este filtro").

Seleção de coortes via API

Através da API REST, obtenha os UUIDs dos passes pretendidos utilizando POST /api/v1/passes/query-builder ou POST /api/v1/passes/search e, em seguida, envie os IDs resultantes para /batch-pass-operations/*.


Atualizar milhares de passes emitidos

Atualizar grandes frotas de passes emitidos exige equilibrar o débito de escrita na base de dados com os limites rigorosos de ligação das gateways de notificações push das carteiras móveis.

Operações diretas em array vs. ingestão em lote por CSV

A Passinstance disponibiliza duas vias distintas para atualizações em massa consoante o volume:

  1. 1
    Operações Diretas em Array JSON (POST /api/v1/batch-pass-operations/update):

- Ideal para até 1.000 passes por pedido HTTP. - Aceita um array de passIds e um único dicionário updateData. - Resposta HTTP síncrona devolvendo o estado individual, erros e avisos para cada passe.

  1. 2
    Pipeline Assíncrono em Lote por CSV (/api/v1/batch-processing):

- Ideal para 1.000 a mais de 100.000 passes. - Carregue um ficheiro CSV contendo identificadores únicos (externalId ou serialNumber) e os atributos modificados. - Defina a operação como UPDATE_PASSES ou UPSERT. - As filas de workers de tarefas em segundo plano processam linhas de forma assíncrona em transações delimitadas de 50 linhas na base de dados, com acompanhamento do progresso em tempo real e registos de resultados transferíveis (result.csv).

Limitação HTTP/2 APNs e pool de ligações da Apple Wallet

Ao atualizar passes da Apple Wallet, a Passinstance envia notificações push que instruem os dispositivos iOS a acordar silenciosamente e a obter o pacote .pkpass atualizado a partir da API da Passinstance:

  • Notificações Push Silenciosas: As notificações de passes são enviadas com content-available: 1. Não apresentam janelas intrusivas no ecrã bloqueado, salvo quando estejam configuradas mensagens localizadas de alteração de campo (por exemplo, "A sua porta mudou para B12").
  • Fluxos Persistentes HTTP/2: O serviço @passinstance/apns mantém ligações HTTP/2 persistentes em pool com os servidores push da Apple (api.push.apple.com:443). Em vez de encerrar e recriar handshakes TLS para cada destinatário, os fluxos são multiplexados pelas ligações ativas.
  • Limitação Adaptativa de Taxa e Controlo de Filas:

- As notificações de saída passam pelas filas de tarefas em segundo plano (push-notifications, individual-push-notifications, silent-push-notifications). - O Notification Rate Limiter e a Notification Deduplication monitorizam o fluxo de respostas da Apple. - Se o APNs devolver 429 TooManyRequests ou contrapressão ao nível da ligação, os workers reduzem a concorrência e aplicam backoff exponencial, evitando a invalidação de tokens e o bloqueio de IPs.

Atualizações de Classe vs. PATCH de Objeto na Google Wallet

A Google Wallet utiliza uma arquitetura hierárquica que separa a Pass Class (a definição principal do modelo) do Pass Object (a instância individual do titular do cartão):

  • Atualizações Visuais e de Campos ao Nível do Modelo (Issuer Class):

Quando uma alteração global é publicada num modelo (por exemplo, alterar o logótipo do cabeçalho, a cor de fundo ou os termos do programa) e abrange todos os cartões sem texto personalizado (!hasPersonalizedMessage), a Passinstance invoca Google Wallet class sync em template.service.ts. Isto envia um único REST PATCH para a API da Google Wallet para atualizar a Issuer Class. Como cada passe Google Wallet emitido referencia esta Class principal, os servidores cloud da Google propagam imediatamente a atualização para todos os passes Android ativos em simultâneo, sem gerar milhares de pedidos individuais à API.

  • Atualizações de Atributos Específicos do Titular (Pass Object):

Quando os atributos individuais variam consoante o passe (como saldos de pontos individuais, subidas de nível ou nomes personalizados), a Passinstance executa chamadas HTTP PATCH individuais sobre o Google Wallet Pass Object específico (POST /batch-pass-operations/update).

Regras de validação e segurança de atributos

O serviço de atualização em lote (batch-pass-operations.service.ts) impõe integridade de dados rigorosa:

  • Isolamento de Tenant: Campos protegidos (customerId, tenantId, createdBy, templateId) são removidos automaticamente dos payloads recebidos. As atualizações não podem alterar a titularidade do passe nem reatribuir modelos principais.
  • Validação Parcial de Atributos (preValidateAttributes): Ao atualizar passes existentes (isUpdate = true), as verificações de atributos obrigatórios são ignoradas. Pode atualizar uma única propriedade personalizada (por exemplo, pointsBalance) sem reenviar os restantes campos inalterados.
  • Normalização de Atributos: Os espaços nas strings são aparados, os números são convertidos para float/int e as datas são normalizadas para ISO-8601 UTC.

Operações em massa suportadas no Painel e na API

OperaçãoEndpoint da APIDTO e comportamento
Criação em lotePOST /api/v1/batch-pass-operations/createrequest payload (passes[], máx. 1,000 itens). Emite novos passes com externalId e bundleId opcionais.
Atualização em lotePOST /api/v1/batch-pass-operations/updaterequest payload (operation: "update", passIds[], updateData, bundleOptions opcional).
Upsert em lotePOST /api/v1/batch-pass-operations/upsertrequest payload (operation: "upsert", passData[]) indexado no tenant por (customerId, externalId).
Ativação em lotePOST /api/v1/batch-pass-operations/activaterequest payload (operation: "activate", passIds[]) que transita passes para ACTIVE.
Desativação (Anulação) em lotePOST /api/v1/batch-pass-operations/deactivaterequest payload (operation: "deactivate", passIds[]) que transita passes para SUSPENDED / INACTIVE e invalida códigos de barras.
Eliminação em lotePOST /api/v1/batch-pass-operations/deleterequest payload (passIds[]) que transita passes por DELETING -> eliminação lógica (archivedAt: new Date()).
Agrupamento em lotePOST /api/v1/bundles/batch-createAgrupa os IDs de passes selecionados em contentores pass bundle partilhados (Pass.bundleId, até 10 passes por pacote).

Importante: Inspecione sempre errors e warnings em request payload. Quando validateBatchOperation deteta linhas inválidas, o controlador devolve success: false com diagnósticos detalhados de erro por item em errors[].


Referência programática de operações em lote sobre passes (request payload)

1. Upsert de passes em lote (POST /api/v1/batch-pass-operations/upsert)

Ideal para sincronizações de CRM ou recálculos de níveis de fidelização indexados por externalId:

Pedido HTTP

POST /api/v1/batch-pass-operations/upsert Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "operation": "upsert",
  "passData": [
    {
      "templateId": "tmpl_01hxyz987654321",
      "externalId": "crm_usr_44910",
      "attributes": {
        "firstName": "Marcus",
        "lastName": "Vance",
        "pointsBalance": 1800,
        "memberTier": "Platinum"
      }
    },
    {
      "templateId": "tmpl_01hxyz987654321",
      "externalId": "crm_usr_44911",
      "attributes": {
        "firstName": "Hannah",
        "lastName": "Abbott",
        "pointsBalance": 250,
        "memberTier": "Silver"
      }
    }
  ]
}

Resposta HTTP (200 OK)

JSON
{
  "success": true,
  "data": [
    {
      "id": "pass_01j8k9m2n3p4q5r6",
      "externalId": "crm_usr_44910",
      "serialNumber": "PI-GOLD-2026-44910",
      "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6"
    },
    {
      "id": "pass_01j8k9m9z8y7x6w5",
      "externalId": "crm_usr_44911",
      "serialNumber": "PI-GOLD-2026-44911",
      "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m9z8y7x6w5"
    }
  ],
  "message": "Successfully upserted 2 passes",
  "errors": [],
  "warnings": []
}

2. Atualização de passes em lote (POST /api/v1/batch-pass-operations/update)

Aplica alterações aos passIds selecionados com um objeto updateData partilhado e bundleOptions opcional:

POST /api/v1/batch-pass-operations/update Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "operation": "update",
  "passIds": [
    "pass_01j8k9m2n3p4q5r6",
    "pass_01j8k9m9z8y7x6w5"
  ],
  "updateData": {
    "expirationDate": "2028-03-31T23:59:59Z",
    "attributes": {
      "seasonalOffer": "2x Winter Bonus Points"
    }
  }
}

Resposta HTTP (200 OK)

JSON
{
  "success": true,
  "data": [
    {
      "id": "pass_01j8k9m2n3p4q5r6",
      "status": "ACTIVE",
      "updatedAt": "2026-11-16T12:00:00.000Z"
    },
    {
      "id": "pass_01j8k9m9z8y7x6w5",
      "status": "ACTIVE",
      "updatedAt": "2026-11-16T12:00:00.000Z"
    }
  ],
  "message": "Successfully updated 2 passes",
  "errors": [],
  "warnings": []
}

3. Ativar, desativar ou eliminar passes em lote

  • Ativar: POST /api/v1/batch-pass-operations/activate ({ "operation": "activate", "passIds": [...] })
  • Desativar: POST /api/v1/batch-pass-operations/deactivate ({ "operation": "deactivate", "passIds": [...] })
  • Eliminar: POST /api/v1/batch-pass-operations/delete ({ "passIds": [...] } via request payload)

Integração de entrega: Que marcador de posição insere a ligação do passe? ({passDownloadUrl})

Que marcador de posição insere a ligação do passe?

Ao dar seguimento a operações em massa com notificações automáticas por e-mail ou SMS, a Passinstance disponibiliza um motor flexível de substituição de marcadores de posição (pass-url-placeholder.util.ts). O token canónico do marcador de posição é {passDownloadUrl}.

Marcador de posição canónico e aliases suportados

O marcador de posição oficial e canónico é {passDownloadUrl}. A Passinstance suporta também aliases retrocompatíveis:

Token de marcador de posiçãoCanónico / AliasExemplo de saída resolvida
{passDownloadUrl}Canónicohttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{smartLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{downloadUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{walletDownloadUrl}Alias dinâmicoLigação sensível ao contexto que redireciona conforme o SO do cliente

Flexibilidade de formatação: A Passinstance normaliza automaticamente a sintaxe de chavetas duplas {{passDownloadUrl}}, snake_case {pass_download_url} e PascalCase {PassDownloadUrl} para o token canónico.

Botões diretos de carteira e indicadores condicionais

Para modelos de e-mail HTML responsivos, pode construir botões diretos de carteira de toque único em vez de depender exclusivamente da página intermédia do PassFlow:

VariávelDescrição
{appleWalletUrl}Fluxo binário direto de transferência .pkpass que aciona a instalação nativa da Apple Wallet no iOS Safari.
{googleWalletUrl}Ligação direta Adicionar à Carteira da Google Wallet (https://pay.google.com/gp/v/save/...).
{samsungWalletUrl}Ligação direta para guardar na Samsung Wallet.
{walletButtonText}Rótulo de botão sensível ao contexto ("Add to Apple Wallet", "Save to Google Wallet" ou "Download my pass").
{showAppleWalletButton}Indicador booleano (true/false) que sinaliza se os ativos da Apple Wallet estão configurados.
{showGoogleWalletButton}Indicador booleano que sinaliza se a integração com a Google Wallet está ativa.

Falhas parciais, tratamento de erros e registo de auditoria

Ao invocar operações em lote, os pedidos não falham na totalidade se um subconjunto de itens contiver erros:

  1. 1
    Isolamento de Falhas por Item: Em updateBatchPasses, cada passe é processado num bloco try-catch isolado. Uma falha na linha 42 (por exemplo, formato de data inválido) não impede que as linhas 1–41 ou 43–100 sejam concluídas com sucesso.
  2. 2
    Estrutura Padrão de Erros: Os itens com falha são comunicados em errors[] contendo passId, a mensagem error e errorCode:
JSON
{
     "passId": "pass_01j8k9m2n3p4q5r6",
     "error": "Attribute 'pointsBalance' must be a valid number",
     "errorCode": "ATTR_VALIDATION"
   }
  1. 3
    Registo de Auditoria do Espaço de Trabalho: Cada operação em massa gera uma entrada no pass audit log e no registo de auditoria do espaço de trabalho (GET /api/v1/audit-log/export.csv), registando o ID do ator, o endereço IP, o tipo de operação, o número de itens afetados e o carimbo temporal.

Para importações em lote baseadas em ficheiros CSV, consulte Criação de passes em massa. Para anulação massiva em todo um modelo, consulte Ciclo de vida e estados dos passes.

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.