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

Criar passes individuais

Gere um único passe a partir de um modelo publicado com atributos do cliente e link/QR imediato de teste.

Neste guia

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

Foco ampliado da interface
Elementos-chave da interface

Criar cartão individual e Ações rápidas (Zoom)

Clique em «+ Create pass» no cabeçalho ou em «Create single pass» nas Ações rápidas para gerar um cartão de teste a partir do modelo publicado.

Visão geral

A emissão individual de passes permite aos operadores e às integrações de backend gerar um único cartão digital personalizado para carteira a partir de qualquer modelo PUBLISHED. Seja acionada manualmente na janela Criar passe do Painel ou programaticamente via API REST, a Passinstance atribui um serialNumber e um authenticationToken criptograficamente únicos, hidrata todos os campos dinâmicos {variable}, assina o pacote Apple .pkpass e o JWT da Google Wallet e devolve um URL inteligente de distribuição imediata (passAccessUrl).

Ações rápidas do modelo para criar um único passe
Ações rápidas do modelo para criar um único passe

Arquitetura do sistema: Emissão única de passe e upsert idempotente

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
EMISSÃO ÚNICA DE PASSE E UPSERT IDEMPOTENTE
ETAPA 01 PAINEL LATERAL / CRM / BACKEND POS
Emissão Padrão: POST/api/v1/passes (request payload)
Upsert Idempotente:POST/api/v1/passes/upsert-by-external-id
ETAPA 02 SERVIÇO DE EMISSÃO DE PASSES (Pass Issuance Engine)
1
Verifica se Template está PUBLISHED e no tenant (customerId)
2
Avalia chave composta (customerId, externalId) para desduplicação idempotente
3
Gera serialNumber único e authenticationToken hex de 32 bytes
4
Valida attributes structured JSON face ao esquema de Propriedades Personalizadas
5
Persiste linha Pass (status: ACTIVE) e inicializa registo pass mechanic
ETAPA 03 ASSINATURA NA CARTEIRA E EMPACOTAMENTO DE LIGAÇÃO INTELIGENTE
Gera ligação inteligente (passAccessUrl) e endpoint de código QR
Prepara stream Apple .pkpass assinado e Save JWT Google Wallet
Devolve API response (request payload) com 201 Created ou 200 OK

Emitir um único passe manualmente no painel

  1. 1
    Aceda à página de vista geral do seu modelo Publicado.
  2. 2
    Clique em Criar passe no cabeçalho superior (ou em Ações rápidas).
  3. 3
    Preencha todas as Propriedades Personalizadas Obrigatórias assinaladas no formulário (por exemplo: nome do cliente, e-mail/telefone se necessários para envios, contagem inicial de carimbos ou externalId).
  4. 4
    Submeta para gerar o passe imediatamente.
  5. 5
    Copie o URL de Download único (passAccessUrl), apresente o código QR de instalação para ler com um smartphone ou envie um e-mail de entrega diretamente a partir do painel de detalhes do passe.

Pré-requisitos: Publique o modelo (POST /api/v1/templates/:id/publish) com credenciais válidas de Apple Pass Type ID / Google Wallet antes de emitir passes ativos. Internamente, resolvePassCreationTemplateId resolve templateId para a revisão base PRODUCTION/PUBLISHED e rejeita modelos DELETING/DELETED (BadRequestException / NotFoundException).

Referência da API de emissão programática

1. Criar um novo passe (POST /api/v1/passes)

Cria um novo registo de passe via request payload, respeitando um cabeçalho HTTP opcional Idempotency-Key (idempotencyKey, máx. 128 carateres correspondentes a [A-Za-z0-9._:-]+, protegido por resumo SHA-256 do pedido) e parâmetros de consulta opcionais ?includePassSource=apple|google e ?pin=.

Parâmetros de pedido request payload

CampoTipoObrigatórioDescrição
templateIdstring (UUID)SimUUID do modelo (resolvido automaticamente para a linha base ativa PRODUCTION/PUBLISHED).
externalIdstringOpcionalIdentificador CRM/POS/encomenda único por tenant (máx. 255 carateres; unicidade garantida por passe ativo não eliminado via @@unique([customerId, externalId])).
serialNumberstringOpcionalNúmero de série único personalizado (gerado automaticamente se omitido).
barcodeValuestringOpcionalPayload explícito do código de barras. Predefine-se a partir da configuração do modelo ou de um valor gerado.
barcodeAltText / barcodeAlternativeTextstringOpcionalLegenda legível impressa abaixo do código de barras para introdução manual pelo operador de caixa.
attributesRecord<string, any>OpcionalDicionário structured JSON chave-valor correspondente às chaves das Propriedades Personalizadas do modelo.
expirationDatestringOpcionalData/hora de expiração (<= 10 anos no futuro, interpretada no fuso horário do espaço de trabalho).
validityAsOfDate / validAsOfDatestringOpcionalData/hora de início de validade (issuedDate).
enableDownloadUntilstringOpcionalData-limite de download ("YYYY-MM-DD HH:mm" ou carimbo temporal ISO).
sharingProhibitedbooleanOpcionalSubstitui a definição antipartilha do modelo (limitToOneActivePerPass).
validationPlacesstring[]OpcionalSubstituições de locais de validação permitidos quando ativadas no modelo.
skipDistributeOnCreatebooleanOpcionalSuprime envios automáticos pós-criação (e-mail/SMS) ao emitir via API.

Exemplo de pedido

POST /api/v1/passes?includePassSource=google Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "serialNumber": "PI-GOLD-2026-44910",
  "barcodeValue": "PI-GOLD-2026-44910",
  "barcodeAltText": "44910-GOLD",
  "expirationDate": "2027-12-31 23:59",
  "attributes": {
    "firstName": "Marcus",
    "lastName": "Vance",
    "email": "marcus.vance@example.com",
    "pointsBalance": 500,
    "memberTier": "Gold"
  }
}

Exemplo de resposta (API response envelope)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01j8k9m2n3p4q5r6",
    "templateId": "tmpl_01hxyz987654321",
    "customerId": "cust_ws_88219",
    "externalId": "crm_usr_44910",
    "bundleId": null,
    "idempotencyKey": "crm_usr_44910_v1",
    "serialNumber": "PI-GOLD-2026-44910",
    "authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
    "downloadCode": "dl_94f8a1",
    "barcodeValue": "PI-GOLD-2026-44910",
    "barcodeAltText": "44910-GOLD",
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "NONE",
    "appleArtifactStatus": "NOT_GENERATED",
    "googleArtifactStatus": "READY",
    "downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "pointsBalance": 500,
      "memberTier": "Gold"
    },
    "expirationDate": "2027-12-31T23:59:00.000Z",
    "createdAt": "2026-11-15T15:04:12.000Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Dica — Agrupamento multi-passe (bundleId): Se criar passes complementares para um agregado familiar, segmento de voo ou encomenda VIP de evento, associe-os a um pass bundle (/api/v1/bundles/upsert ou PassProject) para que Pass.bundleId agrupe até 10 passes numa ligação unificada .pkpasses / multi-cartão.

2. Upsert idempotente e pesquisa por ID externo (request payload)

Em integrações orientadas por webhooks (Shopify, HubSpot ou checkouts POS), novas tentativas de rede podem disparar repetidamente o mesmo pedido. A Passinstance disponibiliza endpoints externalId dedicados aos seus passes ativos do tenant (archivedAt: null):

  • POST /api/v1/passes/upsert-by-external-id: Cria um passe se nenhum passe ativo corresponder a externalId (action: "CREATED"), ou funde attributes, expirationDate, status (pass status) e changeMessage opcional (<=500 carateres) no passe existente (action: "UPDATED").
  • PUT /api/v1/passes/by-external-id/:externalId: Executa upsert usando o parâmetro de caminho :externalId (o externalId no corpo deve coincidir ou pode ser omitido).
  • GET /api/v1/passes/by-external-id/:externalId: Obtém diretamente o passe ativo por externalId sem armazenar UUIDs internos externamente.

Exemplo de pedido

POST /api/v1/passes/upsert-by-external-id Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "status": "ACTIVE",
  "changeMessage": "Tier updated to Platinum (%@ pts)",
  "attributes": {
    "pointsBalance": 750,
    "memberTier": "Platinum"
  }
}

Exemplo de resposta (200 OK)

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "pass_01j8k9m2n3p4q5r6",
      "externalId": "crm_usr_44910",
      "serialNumber": "PI-GOLD-2026-44910",
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

Para integração de elevado volume via CSV ou geração em lote por matriz, consulte Criação em massa de passes e 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.