Visão geral
Ao integrar centenas ou centenas de milhares de titulares de cartões em simultâneo, a Passinstance oferece um pipeline assíncrono e tolerante a falhas de ingestão em lote de CSV, suportado pela Batch Jobs API (/api/v1/batch-processing) e por filas de workers de tarefas em segundo plano suportadas por cache em memória. Os operadores podem carregar folhas de cálculo UTF-8 através do Painel (Operações em Massa -> Importar Passes), acionar Importações FTP/SFTP automatizadas ou orquestrar programaticamente o pipeline CSV de 6 etapas através da API REST.

Arquitetura do sistema: Emissão em lote por CSV e pipeline de workers de tarefas em segundo plano
Lista de verificação de pré-requisitos
Pré-requisitos: Antes de iniciar um trabalho de importação CSV em massa, verifique os seguintes requisitos:
1. O
Templatede destino tem de estar no estadoPUBLISHED.2. O seu ficheiro CSV deve estar codificado em UTF-8, sem delimitadores malformados nem aspas sem escape.
3. Inclua as colunas
phonese pretender enviar automaticamente Ligações de Transferência de Passes através de campanhas do Centro de Entrega após a geração.4. Configure a sua origem de ID Externo nas Definições do Modelo (
externalId) se pretender desduplicação idempotente entre importações repetidas.
Fluxo de trabalho passo a passo de importação CSV (Bulk Pass Wizard)
No Painel em Lote -> Processamento em Lote (/batch-processing), o assistente orienta os operadores por cinco etapas (Modelo -> Carregar CSV -> Mapear Campos -> Opções de envio (opcional) -> Processar):
-
1
Modelo: Selecione o modelo de destino em estado
PUBLISHED/PRODUCTION(ou abra Passes -> Importar diretamente a partir de um modelo). -
2
Carregar CSV: Arraste um ficheiro CSV UTF-8 ou transfira o CSV de Exemplo dinâmico (
GET /api/v1/batch-processing/templates/:templateId/sample-csv), pré-preenchido com cabeçalhos correspondentes às Propriedades Personalizadas do seu modelo e aos campos de sistema (externalId,expirationDate, etc.). -
3
Mapear Campos: Reveja as recomendações automáticas de mapeamento de colunas com pontuação de confiança (
POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations), associando cabeçalhos (por exemplo,Customer_ID,First_Name) aexternalIdou a chavesattributes.*. -
4
Opções de envio (quando ativadas): Escolha um modelo de entrega por E-mail/SMS caso os novos passes devam ser enviados automaticamente após a conclusão.
-
5
Processar: Valide e inicie o trabalho na fila de tarefas em segundo plano (estados do trabalho em lote:
NEW,READY_TO_RUN,INTEGRATION_MAPPING_COMPLETE,SENDOUT_PENDING,RUNNING,COMPLETED,COMPLETED_WITH_ERRORS,FAILED,CANCELLED,PAUSED) e, em seguida, transfira/result.csvcom todos osserialNumber,externalId,bundleIde ligações de transferência gerados.
Referência da API REST de processamento em lote (Batch Jobs API)
Todos os endpoints de trabalhos CSV em lote estão montados em /api/v1/batch-processing (suportando os tipos de trabalho CREATE_PASSES, UPDATE_PASSES, DELETE_PASSES, IMPORT_DATA, EXPORT_DATA, MIGRATION e as origens de dados CSV_UPLOAD, API, SEGMENT, QUERY, MANUAL):
| Etapa | Método HTTP e Endpoint | Finalidade |
|---|---|---|
| 1. CSV de Exemplo | GET /api/v1/batch-processing/templates/:templateId/sample-csv | Transfere um modelo dinâmico de cabeçalhos CSV UTF-8 adaptado às Propriedades Personalizadas do modelo. |
| 2. Carregar CSV | POST /api/v1/batch-processing | Carrega um ficheiro CSV multipart ou uma definição JSON de trabalho em lote (status: NEW / READY_TO_RUN). |
| 3. Mapear Colunas Automaticamente | POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations | Analisa os cabeçalhos das colunas CSV e devolve sugestões de mapeamento de atributos com pontuação de confiança. |
| 4. Guardar Mapeamento | PUT /api/v1/batch-processing/:id/field-mapping | Persiste no trabalho o dicionário confirmado de mapeamento de colunas CSV para atributos. |
| 5. Validação em Simulação | POST /api/v1/batch-processing/:id/validate | Executa uma validação não destrutiva sobre as linhas CSV e devolve avisos/erros ao nível da linha. |
| 6. Iniciar Worker | POST /api/v1/batch-processing/:id/start | Coloca em fila o trabalho de worker em segundo plano (status: RUNNING) para emitir passes assincronamente. |
| 7. Exportar Resultados | GET /api/v1/batch-processing/:id/result.csv | Transmite um relatório CSV acrescentando passId, serialNumber, ligações de transferência e estado de cada linha. |
Exemplo: Pedir recomendações de mapeamento de campos
POST /api/v1/batch-processing/templates/tmpl_01hxyz987654321/field-mapping-recommendations Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"csvHeaders": [
"Customer_ID",
"First_Name",
"Last_Name",
"Loyalty_Points",
"Card_Expiry"
]
}
Resposta HTTP (200 OK)
{
"success": true,
"data": {
"recommendations": [
{ "csvColumn": "Customer_ID", "targetField": "externalId", "confidence": 0.98, "matchType": "SYSTEM" },
{ "csvColumn": "First_Name", "targetField": "attributes.firstName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
{ "csvColumn": "Last_Name", "targetField": "attributes.lastName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
{ "csvColumn": "Loyalty_Points", "targetField": "attributes.pointsBalance", "confidence": 0.89, "matchType": "CUSTOM_PROPERTY" },
{ "csvColumn": "Card_Expiry", "targetField": "expirationDate", "confidence": 0.94, "matchType": "SYSTEM" }
]
},
"statusCode": 200
}
Exemplo: Confirmar o mapeamento de campos e validar o trabalho
PUT /api/v1/batch-processing/job_batch_77123/field-mapping Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"duplicateStrategy": "UPSERT_BY_EXTERNAL_ID",
"mappings": {
"Customer_ID": "externalId",
"First_Name": "attributes.firstName",
"Last_Name": "attributes.lastName",
"Loyalty_Points": "attributes.pointsBalance",
"Card_Expiry": "expirationDate"
}
}
Em seguida, valide e inicie o worker da fila de tarefas em segundo plano:
POST /api/v1/batch-processing/job_batch_77123/validate POST /api/v1/batch-processing/job_batch_77123/start
{
"success": true,
"data": {
"id": "job_batch_77123",
"status": "RUNNING",
"jobType": "CREATE_PASSES",
"dataSource": "CSV_UPLOAD",
"totalRows": 5000,
"processedRows": 0
},
"statusCode": 200
}
Resolução de problemas e perguntas frequentes
Como verifico quando um trabalho de processamento em massa falha?
Quando uma importação CSV assíncrona encontra um problema, inspecione o estado do trabalho e os registos através do Painel ou da API REST:
-
1
Painel de Trabalhos no Dashboard: Aceda a Lote -> Processamento em Lote (
/batch-processing). Os trabalhos concluídos com erros apresentam o indicador Concluído com erros (COMPLETED_WITH_ERRORS), enquanto os trabalhos interrompidos apresentam Falhado (FAILED). -
2
Transferir Registo de Erros: Clique no cartão do trabalho e selecione Transferir CSV de Erros ou consulte
GET /api/v1/batch-processing/:id/result.csv. A folha de cálculo resultante contém cada linha do CSV original acompanhada de uma colunastatus(SUCCESS,SKIPPEDouFAILED) e de uma colunaerrorMessageque explica a falha (por exemplo: "Missing required custom property: firstName", "Invalid ISO 8601 date format" ou "Duplicate externalId"). -
3
Inspecionar Detalhes do Trabalho via API: Chame
GET /api/v1/batch-processing/:idcom a sua chave de API. A resposta JSON devolve orequest payload, incluindototalRows,processedRows,successfulRows,failedRowse o arrayerrorDetails[]com os índices exatos das linhas e os códigos de erro de validação. -
4
Verificação de Validação Prévia: Antes de colocar em fila um trabalho com 100 mil linhas, chame sempre
POST /api/v1/batch-processing/:id/validate. Esta etapa de simulação verifica os mapeamentos de cabeçalhos e os esquemas de atributos sem criar registos na base de dados, reportando erros de sintaxe antes de os workers iniciarem.
Porque é que a minha execução em massa criou menos passes do que o número de linhas no ficheiro?
Se o seu CSV de entrada continha 5.000 linhas mas o trabalho reporta apenas 4.820 passes criados, verifique os seguintes comportamentos verificados da plataforma:
-
1
Desduplicação por ID Externo (
duplicateStrategy): Se o seu modelo impõe unicidade do ID externo e definiuduplicateStrategycomoSKIP, as linhas que partilham umexternalIdcom um passe ativo existente no seu espaço de trabalho (ou repetidas anteriormente no mesmo ficheiro CSV) são ignoradas para impedir emissões duplicadas. Para substituir passes existentes, selecioneduplicateStrategy: "UPSERT_BY_EXTERNAL_ID". -
2
Linhas Vazias ou Finais em Branco: Os editores de folhas de cálculo (Excel, Google Sheets) exportam frequentemente linhas finais em branco com vírgulas residuais. O analisador CSV da Passinstance descarta automaticamente linhas vazias sem incrementar o contador de passes gerados.
-
3
Rejeições na Pré-Validação de Atributos: As linhas com tipos de dados inválidos (como texto não numérico num atributo numérico, sintaxe de e-mail inválida ou datas impossíveis de analisar) falham a validação individual e são registadas no relatório de falhas sem interromper o trabalho completo.
-
4
Esgotamento da Quota de Passes Ativos (
PASS_LIMIT_REACHED): Se o seu espaço de trabalho atingir 100% do limite de passes ativos do seu plano de subscrição durante o processamento, as linhas subsequentes falharão comPASS_LIMIT_REACHED. Verifique em Definições da Empresa -> Utilização e Faturação a sua quota disponível.
É normal uma espera de várias horas no processamento em massa?
-
Velocidades Padrão de Processamento: As filas de workers de tarefas em segundo plano na Passinstance geram normalmente entre 500 e 2.000 passes por minuto, consoante as assinaturas criptográficas dinâmicas
.pkpassda Apple Wallet e as imagens de código de barras sejam geradas sincronamente ou adiadas para o momento da transferência. Um lote de 10.000 passes fica habitualmente concluído em 5 a 15 minutos. -
Quando Várias Horas É Normal:
- Volumes Massivos de Ingestão: Importações extremamente grandes (100.000 a mais de 500.000 passes) demoram várias horas para garantir que os pools de ligações à base de dados e as filas de cache em memória permaneçam estáveis sem limitar o seu espaço de trabalho. - Envios de Saída Imediatos: Se associou uma campanha de entrega por E-mail ou SMS ao trabalho em lote, os e-mails de saída são limitados de acordo com as quotas de taxa de envio da entrega gerida de e-mail (por exemplo, 14 a 50 e-mails/segundo) e os limites de ligação de servidores SMTP personalizados, protegendo a reputação do seu domínio.
-
Quando um Trabalho Está Parado ou Requer Ação:
- Se um trabalho permanecer em NEW ou READY_TO_RUN durante horas, o worker nunca foi iniciado. Clique em Iniciar Trabalho no Painel ou chame POST /api/v1/batch-processing/:id/start. - Se o estado do trabalho for PAUSED, retome a execução através de POST /api/v1/batch-processing/:id/resume.
Um passe pode expirar um número fixo de dias após a emissão?
Sim. A Passinstance suporta tanto a expiração numa data fixa de calendário como períodos dinâmicos de validade deslizante:
-
1
Duração Dinâmica Deslizante (
validityInDays): No Editor Visual, em Validade e Expiração, defina a Estratégia de Expiração como Duração Dinâmica e especifique o número de dias (por exemplo,30,90ou365). Quando cada passe é criado via importação CSV, API ou formulário PassFlow, a Passinstance calcula automaticamente:
expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).
-
2
Substituição de Expiração por Linha: Se clientes individuais tiverem datas de fim de contrato próprias, mapeie uma coluna CSV com carimbos temporais ISO 8601 (por exemplo,
2027-06-30T23:59:59Z) diretamente para o campo de sistemaexpirationDatena etapa Mapear Campos. -
3
Extensão Pós-Emissão: Pode prolongar ou modificar datas de expiração em milhares de passes ativos em qualquer momento utilizando Operações em massa.
Como migro dados de clientes existentes a partir de outro fornecedor de carteiras ou CRM?
Migrar de sistemas legados (como Airship, PassKit, Braze ou uma base de dados interna) para a Passinstance é um processo fluido:
-
1
Exportar Registos Legados: Exporte a sua base de dados de clientes existente para um ficheiro CSV UTF-8 incluindo nomes dos membros, dados de contacto, saldos de pontos, estado do nível e números de cartão históricos.
-
2
Configurar o Modelo de Destino: Na Passinstance, crie um modelo correspondente. Configure as suas propriedades personalizadas (por exemplo,
memberId,pointsBalance,tier) e a simbologia do código de barras (QR, Aztec, Code 128 ou PDF417). -
3
Mapear Identificadores Históricos para
externalId: Mapeie o número de cartão legado ou o UUID do cliente para o campo de sistemaexternalIdda Passinstance. Isto assegura continuidade 1:1 e previne registos duplicados. -
4
Executar a Ingestão em Lote CSV: Carregue o CSV utilizando o assistente de 5 etapas. Defina a estratégia de importação como
UPSERT_BY_EXTERNAL_IDpara que quaisquer registos pré-existentes sejam atualizados sem conflitos. -
5
Transição Transparente para o Titular do Cartão: Se a sua organização mantiver o mesmo Apple Pass Type Identifier e o mesmo certificado de assinatura, os clientes receberão passes atualizados sem precisarem de eliminar os passes existentes na carteira. Em alternativa, envie novas ligações inteligentes de transferência através do Centro de Entrega utilizando o marcador de posição
{passDownloadUrl}.
Como limpo passes depois de um evento terminar?
Após o encerramento de um concerto, jogo desportivo ou campanha sazonal, mantenha a organização do espaço de trabalho e liberte quota ativa:
-
1
Localizar a Coorte do Evento: No Painel em Passes (
/passes), filtre pelo modelo do evento ou utilize o Painel de Pesquisa Avançada para filtrar porexpirationDate < today. -
2
Selecionar Todos os Passes Correspondentes: Utilize a caixa de seleção da
StickySelectionToolbarpara selecionar a vista atual e clique na faixa de confirmação para selecionar todos os passes correspondentes ao filtro em todas as páginas. -
3
Executar Anulação / Desativação em Massa: Clique em Ações em massa -> Desativar / Anular (
POST /api/v1/batch-pass-operations/deactivate). Isto define o estado do passe comoVOIDED, apresenta uma faixa de código de barras invalidado no ecrã bloqueado e desativa o resgate no scanner, preservando simultaneamente o histórico de leituras e os dados de presenças para relatórios de conformidade. -
4
Eliminação Lógica (
DELETING->SOFT): Se pretender remover os passes do evento expirado da sua vista ativa no Painel, selecione Ações em massa -> Eliminar. Os passes com eliminação lógica não contam para os limites de passes ativos da sua subscrição e libertam o respetivoexternalIdpara utilização futura, mantendo-se acessíveis nas exportações históricas de auditoria.
Para operações em lote diretas com arrays JSON sem ficheiros CSV, consulte Operações em massa. Para distribuir passes recém-importados por e-mail, consulte Entrega por e-mail e SMS.
