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).

Arquitetura do sistema: Emissão única de passe e upsert idempotente
Emitir um único passe manualmente no painel
-
1
Aceda à página de vista geral do seu modelo Publicado.
-
2
Clique em Criar passe no cabeçalho superior (ou em Ações rápidas).
-
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
Submeta para gerar o passe imediatamente.
-
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,resolvePassCreationTemplateIdresolvetemplateIdpara a revisão basePRODUCTION/PUBLISHEDe rejeita modelosDELETING/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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
templateId | string (UUID) | Sim | UUID do modelo (resolvido automaticamente para a linha base ativa PRODUCTION/PUBLISHED). |
externalId | string | Opcional | Identificador CRM/POS/encomenda único por tenant (máx. 255 carateres; unicidade garantida por passe ativo não eliminado via @@unique([customerId, externalId])). |
serialNumber | string | Opcional | Número de série único personalizado (gerado automaticamente se omitido). |
barcodeValue | string | Opcional | Payload explícito do código de barras. Predefine-se a partir da configuração do modelo ou de um valor gerado. |
barcodeAltText / barcodeAlternativeText | string | Opcional | Legenda legível impressa abaixo do código de barras para introdução manual pelo operador de caixa. |
attributes | Record<string, any> | Opcional | Dicionário structured JSON chave-valor correspondente às chaves das Propriedades Personalizadas do modelo. |
expirationDate | string | Opcional | Data/hora de expiração (<= 10 anos no futuro, interpretada no fuso horário do espaço de trabalho). |
validityAsOfDate / validAsOfDate | string | Opcional | Data/hora de início de validade (issuedDate). |
enableDownloadUntil | string | Opcional | Data-limite de download ("YYYY-MM-DD HH:mm" ou carimbo temporal ISO). |
sharingProhibited | boolean | Opcional | Substitui a definição antipartilha do modelo (limitToOneActivePerPass). |
validationPlaces | string[] | Opcional | Substituições de locais de validação permitidos quando ativadas no modelo. |
skipDistributeOnCreate | boolean | Opcional | Suprime 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
{
"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)
{
"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 umpass bundle(/api/v1/bundles/upsertouPassProject) para quePass.bundleIdagrupe até10passes 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 aexternalId(action: "CREATED"), ou fundeattributes,expirationDate,status(pass status) echangeMessageopcional (<=500carateres) no passe existente (action: "UPDATED"). -
PUT /api/v1/passes/by-external-id/:externalId: Executa upsert usando o parâmetro de caminho:externalId(oexternalIdno corpo deve coincidir ou pode ser omitido). -
GET /api/v1/passes/by-external-id/:externalId: Obtém diretamente o passe ativo porexternalIdsem 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
{
"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)
{
"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.
