Crie integrações em grande escala para Apple Wallet (.pkpass) e Google Wallet. Emita, atualize, valide e transmita notificações em tempo real através de APIs REST prontas para produção.
A API da Passinstance permite que desenvolvedores emitam, distribuam, atualizem e validem passes digitais dinamicamente para Apple Wallet (iOS) e Google Wallet (Android). Todas as requisições à API devem usar HTTPS e retornam um envelope de resposta de API padronizado com códigos de status legíveis por máquina.
URL base de Produção
Ativo
https://api.passinstance.com/api/v1
URL base do Sandbox Staging
https://staging-api.passinstance.com/api/v1
Formato de requisição e respostaapplication/json (UTF-8) com envelope de resposta padrão
Fuso horário do servidorEurope/Berlin (timestamps ISO 8601)
Segurança
Autenticação — Chaves de API e autorização
Use X-API-Key: <key> ou Authorization: ApiKey <key> nos endpoints compatíveis com chaves API. Bearer é reservado a JWTs de acesso. Mantenha as credenciais no servidor.
Invariante de segurança:Apenas servidor-para-servidor. Nunca incorpore chaves secretas no frontend.
Início rápido
Início rápido — Primeira requisição à API
Crie seu primeiro passe utilizável em menos de 5 minutos. Defina o cabeçalho com sua chave de API, chame POST /api/v1/passes com um templateId válido e entregue a passAccessUrl retornada ao usuário final.
Passo 1: Definir chave
export PASSINSTANCE_API_KEY="pi_test_..."
Passo 2: Emitir passe
POST /api/v1/passes com templateId e serialNumber
Passo 3: Obter URL
Extrair response.data.passAccessUrl do retorno 201 Created
Passo 4: Distribuir
Enviar URL por SMS/e-mail; o usuário toca em "Adicionar ao Apple/Google Wallet"
Recursos
Coleção Postman — Importar e testar requisições da API
Importe a especificação OpenAPI 3.0 do Passinstance (/api/docs/openapi.json) diretamente no Postman, Insomnia ou Bruno para testar endpoints, inspecionar esquemas e gerar clientes HTTP tipados.
Clique em Import no Postman, Insomnia ou Bruno e cole /api/docs/openapi.json para carregar todas as rotas
3. Configurar ambiente
Defina baseUrl = https://api.passinstance.com e PASSINSTANCE_API_KEY = pi_test_...
4. Verificar conectividade
Execute GET /api/v1/templates com X-API-Key: para testar seu workspace
Operações e FAQ
FAQ — Perguntas frequentes e tratamento de erros
Cada resposta usa o envelope de resposta de API padrão. Corrija erros 4xx antes de tentar novamente; aguarde em respostas 5xx e 429 usando o cabeçalho Retry-After.
O gerenciamento de passes segue um ciclo de vida de 6 etapas: 1. Modelo (projeto visual) → 2. Passe (registro assinado criptograficamente) → 3. Distribuição (passAccessUrl segura) → 4. Registro na Wallet (o dispositivo se registra com APNs / Google Push) → 5. Atualizações ao vivo (notificações em tempo real) → 6. Telemetria de leitura e resgate (validação e webhooks).
1. ModeloPOST /api/v1/templates
Layout mestre, tipo de código de barras, cores da marca e campos de esquema
Guias da plataforma
Matriz Apple Wallet vs. Google Wallet
A Passinstance assina automaticamente pacotes .pkpass para iOS e gera objetos JWT assinados para Google Wallet. Recursos gráficos, códigos de barras e gatilhos na tela de bloqueio se adaptam perfeitamente a ambos os sistemas.
Apple WalletiOS · .pkpass
Assinatura Apple Wallet
Assinatura criptográfica PKCS#7 usando certificado Apple Pass Type ID
Google WalletAndroid · JWT
Emissor Google Wallet
Payload REST JWT de conta de serviço do Google Cloud
Paridade multiplataforma (uma única chamada REST)iOS + Android
Códigos de barras universaisQR Code e PDF417 suportados nativamente em ambas as plataformas móveis
Conceitos principais
Mecânicas de passes e motor de fidelidade
Associe mecânicas de negócio com estado a modelos em 8 soluções prontas (Fidelidade, Cartões de selos, Cupons, Cartões-presente/pré-pagos, Ingressos, Associações, Crachás de funcionários, Cartões VIP). As regras executam atomicamente na leitura ou chamada API.
LOYALTY_PROGRAM
LOYALTY_PROGRAM e Níveis
Acúmulo de pontos por leitura (defaultChangeValue) com progressão automática de nível
STAMP_CARD
STAMP_CARD_ADD / DEDUCT
Controla posições de selos (0..maximumValue) com onCap ('noop' | 'reset') e rewardClaimBehavior
PREPAID_CARD
Razão PREPAID_CARD
Contabilidade de razão pré-paga em subunidades ISO 4217 com aplicação de disallowNegativeBalance
VALID_ONCE_PER_DAY
VALID_ONCE_PER_DAY e RENEW
Limites diários por fuso horário e extensão automática de expirationDate na leitura
Gestão de modelos
7 endpoints
GEThttps://api.passinstance.com/api/v1/templatesChave de API
Gestão de modelos
Listar todos os modelos
Recupere uma lista paginada de modelos de passes pertencentes ao contexto de cliente autenticado.
Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório
Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.
POSThttps://api.passinstance.com/api/v1/templates/{id}/publishChave de API
Gestão de modelos
Publicar rascunho do modelo
Promova uma revisão de rascunho (rowKind: DRAFT) para PUBLISHED, marque changesToPush: true e enfileire atualizações APNs e Google Wallet para todos os passes ativos.
Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório
Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.
Exemplo: pi_live_98a7b6c5d4e3f2a1
Parâmetros de caminho1 obrigatório(s)
idstring (UUID)
Obrigatório
UUID do modelo a publicar.
Exemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Payload da requisição controlando publicação imediata ou agendada e propagação push para carteiras.
PATCHhttps://api.passinstance.com/api/v1/passes/{id}Chave de API
Gestão de passes
Atualizar passe e enviar push
Atualize campos dinâmicos, cores ou código de barras do passe e transmita automaticamente notificações push APNs e Google Wallet para dispositivos instalados.
Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório
Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.
POSThttps://api.passinstance.com/api/v1/passes/{id}/useChave de API
Gestão de passes
Aplicar ação de mecânica
Execute uma operação atômica de mecânica do passe: INCREMENT (cartão de selos), DECREMENT, DEBIT (saldo pré-pago), CREDIT ou VALIDATE (cupom de uso único).
Cabeçalhos3 obrigatório(s)
X-API-Keystring
Obrigatório
Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.
Exemplo: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obrigatório
Deve ser application/json.
Exemplo: application/json
Idempotency-Keystring
Obrigatório
UUID obrigatório para garantir execução atômica e evitar deduções duplicadas de saldo ou selos.
Resolva uma página pública personalizada de download de passe por slug (sem prefixo GET /d/{slug}/info). Para consulta autenticada de gestão, use GET /api/v1/download-pages/slug/{slug}.
Parâmetros de caminho1 obrigatório(s)
slugstring
Obrigatório
Slug vanity exclusivo da página de download hospedada.
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsChave de API
Notificações push
Enviar notificação na tela de bloqueio
Envie uma notificação push imediata para um passe Apple Wallet (.pkpass) ou Google Wallet instalado. Para envios agendados ou personalização de cabeçalho, use POST /api/v1/push-notifications/passes/{id}.
Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório
Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.
Exemplo: pi_live_98a7b6c5d4e3f2a1
Parâmetros de caminho1 obrigatório(s)
idUUID
Obrigatório
UUID exclusivo da instância do passe que receberá a notificação.
Exemplo: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
Payload da requisição contendo o corpo da mensagem e título de cabeçalho opcional.
Corpo da requisição1 obrigatório(s) • 1 opcional(is)
messagestring
Obrigatório
Mensagem de texto a ser exibida na tela de bloqueio do usuário.
Exemplo: Your reward points have been updated! You now have 250 points.
Cada leitura de código de barras ou NFC executa um pipeline determinístico de 14 regras (status, expiração, janelas de horário, geofencing, mecânicas, limites de taxa, antirrepetição) com nonces criptográficos opcionais e sincronização offline.
Nonce antirrepetição
POST /api/v1/scans/prepare emite um nonce criptográfico antirrepetição temporário vinculado ao código de barras
Visão geral de Webhooks e verificação de assinatura
Verifique X-Webhook-Signature como HMAC-SHA256 do corpo original exato da solicitação com o segredo da assinatura. Compare em tempo constante e processe os eventos de forma idempotente.
Cabeçalho de assinatura
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Cabeçalho de timestamp
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Proteção contra repetições
Verifique se X-Webhook-Id corresponde ao eventId assinado, elimine eventos duplicados e valide o timestamp assinado conforme a sua política contra repetições.
Retorne HTTP 200 OK em até 5.000 ms para confirmar o recebimento
Chave pública de verificação
GET /api/v1/webhooks/public-key retorna a chave pública ativa para verificação de assinatura
POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChave de API
Visão geral e endpoints
Criar assinatura de webhook
Registre um endpoint HTTPS para receber notificações de eventos em tempo real assinadas por HMAC sobre emissão, atualização, leitura e remoção de passes.
Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório
Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.
Exemplo: pi_live_98a7b6c5d4e3f2a1
Payload da requisição com a URL HTTPS de destino e matriz de itens tipos de eventos webhook.
Corpo da requisição2 obrigatório(s) • 5 opcional(is)
urlstring (HTTPS URL)
Obrigatório
URL do seu servidor (deve começar com https://, máx. 2048 caracteres).
Consuma eventos de passes e leituras em tempo real via webhooks Push assinados por HMAC-SHA256 (com backoff exponencial e disjuntores) ou consulta Pull Webhook para ambientes protegidos por firewall, além de fluxos no-code.
Resiliência Push Webhook
5 tentativas com backoff exponencial com jitter; o disjuntor abre após 10 falhas consecutivas
Consulta Pull Webhook
GET /api/v1/webhook-payload e POST /api/v1/webhook-payload/acknowledge para redes privadas
GEThttps://api.passinstance.com/api/v1/webhook-payloadChave de API
Webhooks baseados em Pull
Consultar eventos pull-webhook na fila
Busque payloads de eventos webhook pendentes via HTTPS GET de saída para ambientes restritos por firewall ou redes privadas sem abrir portas de entrada.
Cabeçalhos1 obrigatório(s)
X-API-Keystring
Obrigatório
Chave de API secreta do workspace (pi_live_... ou pi_test_...). Alternativamente, envie Authorization: ApiKey <key>.