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
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) enot_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"EpointsBalance < 500EexpirationDate < 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
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.
-
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/apnsmanté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ção | Endpoint da API | DTO e comportamento |
|---|---|---|
| Criação em lote | POST /api/v1/batch-pass-operations/create | request payload (passes[], máx. 1,000 itens). Emite novos passes com externalId e bundleId opcionais. |
| Atualização em lote | POST /api/v1/batch-pass-operations/update | request payload (operation: "update", passIds[], updateData, bundleOptions opcional). |
| Upsert em lote | POST /api/v1/batch-pass-operations/upsert | request payload (operation: "upsert", passData[]) indexado no tenant por (customerId, externalId). |
| Ativação em lote | POST /api/v1/batch-pass-operations/activate | request payload (operation: "activate", passIds[]) que transita passes para ACTIVE. |
| Desativação (Anulação) em lote | POST /api/v1/batch-pass-operations/deactivate | request payload (operation: "deactivate", passIds[]) que transita passes para SUSPENDED / INACTIVE e invalida códigos de barras. |
| Eliminação em lote | POST /api/v1/batch-pass-operations/delete | request payload (passIds[]) que transita passes por DELETING -> eliminação lógica (archivedAt: new Date()). |
| Agrupamento em lote | POST /api/v1/bundles/batch-create | Agrupa os IDs de passes selecionados em contentores pass bundle partilhados (Pass.bundleId, até 10 passes por pacote). |
Importante: Inspecione sempre
errorsewarningsemrequest payload. QuandovalidateBatchOperationdeteta linhas inválidas, o controlador devolvesuccess: falsecom diagnósticos detalhados de erro por item emerrors[].
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
{
"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)
{
"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
{
"operation": "update",
"passIds": [
"pass_01j8k9m2n3p4q5r6",
"pass_01j8k9m9z8y7x6w5"
],
"updateData": {
"expirationDate": "2028-03-31T23:59:59Z",
"attributes": {
"seasonalOffer": "2x Winter Bonus Points"
}
}
}
Resposta HTTP (200 OK)
{
"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": [...] }viarequest 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ção | Canónico / Alias | Exemplo de saída resolvida |
|---|---|---|
{passDownloadUrl} | Canónico | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{smartLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{downloadUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{walletDownloadUrl} | Alias dinâmico | Ligaçã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ável | Descriçã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
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
Estrutura Padrão de Erros: Os itens com falha são comunicados em
errors[]contendopassId, a mensagemerroreerrorCode:
{
"passId": "pass_01j8k9m2n3p4q5r6",
"error": "Attribute 'pointsBalance' must be a valid number",
"errorCode": "ATTR_VALIDATION"
}
-
3
Registo de Auditoria do Espaço de Trabalho: Cada operação em massa gera uma entrada no
pass audit loge 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.
