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

Criação em massa de passes

Carregue ficheiros CSV em Operações em lote ou importação FTP/SFTP, mapeie colunas e acompanhe o progresso.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Painel de tarefas de importação em lote (Zoom)

Inicie uma «New import job» a partir da visão geral do modelo e acompanhe os processamentos CSV em execução, falhados e concluídos.

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.

Contadores de trabalhos de importação em lote e botão de nova importação
Contadores de trabalhos de importação em lote e botão de nova importação

Arquitetura do sistema: Emissão em lote por CSV e pipeline de workers de tarefas em segundo plano

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
EMISSÃO EM LOTE CSV E PIPELINE ASSÍNCRONO
ETAPA 01 CARREGAMENTO CSV NO PAINEL / API (Batch Jobs API)
1
GET/api/v1/batch-processing/templates/:templateId/sample-csv
2
POST/api/v1/batch-processing (Carregamento CSV UTF-8 Multipart)
3
POST/api/v1/batch-processing/templates/:templateId/field-mapping-recommendations
ETAPA 02 MAPEAMENTO DE ESQUEMA E VALIDAÇÃO PRÉVIA EM SIMULAÇÃO
4
PUT/api/v1/batch-processing/:id/field-mapping (Assoc. cabeçalhoschaves)
5
POST/api/v1/batch-processing/:id/validate
Verifica Propriedades Personalizadas obrigatórias, datas ISO, números e IDs
Reporta erros de sintaxe ou esquema linha a linha antes de gravar na BD
ETAPA 03 PIPELINE DE WORKERS ASSÍNCRONOS (cache em memória)
Processa blocos CSV validados em transações delimitadas
Gera registos Pass, serialNumber, authenticationToken e links dinâmicos
Compila relatório de resultados: GET/api/v1/batch-processing/:id/result.csv

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 Template de destino tem de estar no estado PUBLISHED.

2. O seu ficheiro CSV deve estar codificado em UTF-8, sem delimitadores malformados nem aspas sem escape.

3. Inclua as colunas email e/ou phone se 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. 1
    Modelo: Selecione o modelo de destino em estado PUBLISHED / PRODUCTION (ou abra Passes -> Importar diretamente a partir de um modelo).
  2. 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. 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) a externalId ou a chaves attributes.*.
  4. 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. 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.csv com todos os serialNumber, externalId, bundleId e 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):

EtapaMétodo HTTP e EndpointFinalidade
1. CSV de ExemploGET /api/v1/batch-processing/templates/:templateId/sample-csvTransfere um modelo dinâmico de cabeçalhos CSV UTF-8 adaptado às Propriedades Personalizadas do modelo.
2. Carregar CSVPOST /api/v1/batch-processingCarrega um ficheiro CSV multipart ou uma definição JSON de trabalho em lote (status: NEW / READY_TO_RUN).
3. Mapear Colunas AutomaticamentePOST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendationsAnalisa os cabeçalhos das colunas CSV e devolve sugestões de mapeamento de atributos com pontuação de confiança.
4. Guardar MapeamentoPUT /api/v1/batch-processing/:id/field-mappingPersiste no trabalho o dicionário confirmado de mapeamento de colunas CSV para atributos.
5. Validação em SimulaçãoPOST /api/v1/batch-processing/:id/validateExecuta uma validação não destrutiva sobre as linhas CSV e devolve avisos/erros ao nível da linha.
6. Iniciar WorkerPOST /api/v1/batch-processing/:id/startColoca em fila o trabalho de worker em segundo plano (status: RUNNING) para emitir passes assincronamente.
7. Exportar ResultadosGET /api/v1/batch-processing/:id/result.csvTransmite 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

JSON
{
  "csvHeaders": [
    "Customer_ID",
    "First_Name",
    "Last_Name",
    "Loyalty_Points",
    "Card_Expiry"
  ]
}

Resposta HTTP (200 OK)

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

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

JSON
{
  "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. 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. 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 coluna status (SUCCESS, SKIPPED ou FAILED) e de uma coluna errorMessage que explica a falha (por exemplo: "Missing required custom property: firstName", "Invalid ISO 8601 date format" ou "Duplicate externalId").
  3. 3
    Inspecionar Detalhes do Trabalho via API: Chame GET /api/v1/batch-processing/:id com a sua chave de API. A resposta JSON devolve o request payload, incluindo totalRows, processedRows, successfulRows, failedRows e o array errorDetails[] com os índices exatos das linhas e os códigos de erro de validação.
  4. 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. 1
    Desduplicação por ID Externo (duplicateStrategy): Se o seu modelo impõe unicidade do ID externo e definiu duplicateStrategy como SKIP, as linhas que partilham um externalId com 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, selecione duplicateStrategy: "UPSERT_BY_EXTERNAL_ID".
  2. 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. 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. 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 com PASS_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 .pkpass da 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. 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, 90 ou 365). Quando cada passe é criado via importação CSV, API ou formulário PassFlow, a Passinstance calcula automaticamente:

expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).

  1. 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 sistema expirationDate na etapa Mapear Campos.
  2. 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. 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. 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. 3
    Mapear Identificadores Históricos para externalId: Mapeie o número de cartão legado ou o UUID do cliente para o campo de sistema externalId da Passinstance. Isto assegura continuidade 1:1 e previne registos duplicados.
  4. 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_ID para que quaisquer registos pré-existentes sejam atualizados sem conflitos.
  5. 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. 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 por expirationDate < today.
  2. 2
    Selecionar Todos os Passes Correspondentes: Utilize a caixa de seleção da StickySelectionToolbar para 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. 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 como VOIDED, 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. 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 respetivo externalId para 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.

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.