Visão geral
Criar o primeiro passe digital envolve configurar um Template visual reutilizável, associar mecânicas de negócio interativas, efetuar uma verificação de risco pré-publicação e emitir um registo concreto Pass instalável em dispositivos iOS e Android.
Marcos de criação passo a passo
Siga este fluxo no Passinstance Dashboard (Modelos -> Criar Modelo em /templates/new) ou através da API para Programadores:
-
1
Selecionar geometria de layout (pass type): Escolha um dos formatos de passe suportados:
- storeCard: Cartões de fidelização, cartões de carimbos e cartões-presente. - coupon: Vales promocionais de utilização única e cupões de desconto. - eventTicket / boardingPass: Concertos, desporto, festivais, conferências ou cartões de embarque aéreos/ferroviários. - membership / generic / posterGeneric / studentId / businessCard: Cartões de clube, cartões poster WWDC, identificações de colaborador/estudante e cartões de visita digitais.
-
2
Identidade visual, cores e ativos:
- Formatação de cores: A Apple Wallet exige estritamente strings rgb(r, g, b) (sem canais alfa). A Google Wallet aceita hex #RRGGBB. O seletor de cores do painel converte automaticamente e alerta para baixo contraste WCAG. - Slots de ativos (image asset slot): Carregue imagens de alta resolução nos 13 slots suportados (logo, primaryLogo, secondaryLogo, icon, googlePayLogo, strip, background, thumbnail, artwork, venueMap, footer, androidBackground, androidLogo).
-
3
Associar uma mecânica interativa de passe:
- Escolha um motor de regras (mechanic type): STAMP_CARD_ADD, STAMP_CARD_DEDUCT, LOYALTY_PROGRAM, PREPAID_CARD, VALID_ONCE_PER_DAY ou RENEW_EXPIRATION.
-
4
Definir zonas de campos dinâmicos (field placement type):
- Coloque campos em HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO ou FOOTER. - Utilize tokens dinâmicos entre chavetas como {memberName}, {pointsBalance} ou {expirationDate}. - Adicione strings changeMessage Apple contendo %@ (por exemplo, "Points updated: %@") para despoletar notificações push nativas no ecrã bloqueado do iOS.
-
5
Análise de risco pré-publicação e publicação:
- O painel avalia GET /api/v1/templates/:id/publish-risk-check para detetar alterações críticas que possam substituir campos de passes ativos. - Clique em Guardar e Publicar (POST /api/v1/templates/:id/publish) para promover a revisão DRAFT para a linha base PRODUCTION.
-
6
Gerar e instalar um passe de teste:
- Clique em Criar Passe na vista geral do modelo (/templates/:id/overview) ou envie um pedido REST para POST /api/v1/passes. A criação do passe chama automaticamente resolvePassCreationTemplateId para associar o novo passe à linha base canónica do modelo.

Geração e verificação programática de passes
Os programadores podem dispensar o painel e emitir passes digitais personalizados diretamente a partir de sistemas backend ou CRMs usando POST /api/v1/passes (request payload). Inclua Idempotency-Key para repetições seguras e externalId para correlação CRM, e opcionalmente passe ?includePassSource=apple|google para receber artefactos fonte de carteira diretamente na resposta:
Pedido HTTP
/api/v1/passes?includePassSource=google
{
"templateId": "tmpl_9a8b7c6d5e4f",
"externalId": "cust_100248",
"attributes": {
"memberName": "Elena Rostova",
"memberNumber": "MB-94021",
"points": "150"
},
"barcodeValue": "PI-MB-94021-SECURE",
"barcodeAltText": "MB-94021",
"expirationDate": "2027-12-31 23:59"
}
Resposta HTTP (201 Created)
{
"success": true,
"data": {
"id": "pass_1a2b3c4d5e6f",
"templateId": "tmpl_9a8b7c6d5e4f",
"serialNumber": "PI-789042-XY",
"externalId": "cust_100248",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "NONE",
"appleArtifactStatus": "NOT_GENERATED",
"googleArtifactStatus": "READY",
"downloadUrl": "https://app.passinstance.com/d/elena-rostova-94021",
"passAccessUrl": "https://app.passinstance.com/p/pass_1a2b3c4d5e6f",
"passSource": {
"platform": "google",
"saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"createdAt": "2026-11-15T12:00:00Z"
},
"description": "Pass created successfully",
"errors": [],
"statusCode": 201
}
Testes com passe de amostra em sandbox
Durante a avaliação e os testes iniciais, pode gerar um passe de amostra instantâneo sem preencher registos completos de clientes:
-
1
Chame
POST /api/v1/onboarding/sample-passou clique em Experimentar Passe de Amostra no passo/onboarding/try-passdo assistente. -
2
O servidor cria um passe efémero e expõe o endpoint público de amostra:
/api/v1/onboarding/sample-pass/public/:sessionId
-
3
Leia o código QR apresentado com a câmara de um iPhone para iniciar a instalação nativa na Apple Wallet, ou abra a ligação em Android para testar a Google Wallet.
-
4
Abra o Scanner (
/scanner) noPassinstance Dashboardou emparelhe a app móvel Passinstance Scanner viaPOST /api/v1/scanner-keys/from-linke leia o passe instalado para testar eventos de leitura em direto e notificações push instantâneas.
Importante: Teste sempre o seu modelo recém-publicado tanto em dispositivos iOS (Apple Wallet) como Android (Google Wallet) para verificar o contraste das cores, o truncamento de texto nos campos e a fiabilidade da leitura do código de barras antes de lançar campanhas de distribuição para clientes.
Pronto para começar? Inicie a Fase 2: Desenhar o seu passe ou explore Criar passes Wallet com IA.
