Skip to content
Guia da Central de Ajuda · Início rápidoFase de integração 2
4 min de leituraVerificado 2026-11-16

Criar o seu primeiro cartão Wallet

Desenhe um modelo, atribua uma mecânica, ligue campos dinâmicos, publique em segurança e teste no seu telemóvel.

Neste guia

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

Foco ampliado da interface1 / 2
Elementos-chave da interface

Diretório de Templates e Barra de Adoção (Ampliado)

Filtre templates, monitore Instalados vs. Removidos por template e abra pré-visualizações, o Editor Visual ou emissão avulsa.

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.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CRIAÇÃO E INSTALAÇÃO DO PRIMEIRO PASSE
ETAPA 01
1
AUTORIA DO MODELO (POST/api/v1/templates)
Escolher pass type (storeCard, coupon, eventTicket, membership)
Configurar Cores (rgb(r,g,b) Apple, #RRGGBB Google) e Ativos
Associar pass mechanic (STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD)
ETAPA 02
2
VERIFICAÇÃO DE RISCO E PROMOÇÃO (POST/api/v1/templates/:id/publish)
Avaliar GET/api/v1/templates/:id/publish-risk-check
Promover revisão de rowKind = DRAFT para rowKind = PRODUCTION
ETAPA 03
3
EMISSÃO DO PASSE E INSTALAÇÃO (POST/api/v1/passes)
Cabeçalho opcional Idempotency-Key (idempotencyKey) e externalId
Hidratar structured JSON attributes (memberName, points, barcodeValue)
Entregar URL Inteligente (/p/:passId / /d/:slug)Instalar iOS/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. 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.

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

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

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

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

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

Lista de modelos e ações rápidas de criação
Lista de modelos e ações rápidas de criação

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

POST /api/v1/passes?includePassSource=google
Cabeçalhos
X-API-Key <API_KEY>
Content-Type application/json
Idempotency-Key order-94021-pass-init
JSON
{
  "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)

JSON
{
  "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. 1
    Chame POST /api/v1/onboarding/sample-pass ou clique em Experimentar Passe de Amostra no passo /onboarding/try-pass do assistente.
  2. 2
    O servidor cria um passe efémero e expõe o endpoint público de amostra:
GET /api/v1/onboarding/sample-pass/public/:sessionId
  1. 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.
  2. 4
    Abra o Scanner (/scanner) no Passinstance Dashboard ou emparelhe a app móvel Passinstance Scanner via POST /api/v1/scanner-keys/from-link e 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.

Documentação de produto e API relacionada

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.