Documentação para Desenvolvedores Passinstance
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.
Introdução — Visão geral da API
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.
https://api.passinstance.com/api/v1https://staging-api.passinstance.com/api/v1Autenticaçã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.
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxxAuthorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxxx-scanner-key: scan_key_77a8b9c0d1e2f3a4...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.
export PASSINSTANCE_API_KEY="pi_test_..."POST /api/v1/passes com templateId e serialNumber
Extrair response.data.passAccessUrl do retorno 201 Created
Enviar URL por SMS/e-mail; o usuário toca em "Adicionar ao Apple/Google Wallet"
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.
https://passinstance.com/api/docs/openapi.jsonClique em Import no Postman, Insomnia ou Bruno e cole /api/docs/openapi.json para carregar todas as rotas
Defina baseUrl = https://api.passinstance.com e PASSINSTANCE_API_KEY = pi_test_...
Execute GET /api/v1/templates com X-API-Key: para testar seu workspace
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.
{
"success": true,
"data": { ... },
"errors": [],
"statusCode": 200
}Arquitetura e ciclo de vida do passe
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).
POST /api/v1/templatesLayout mestre, tipo de código de barras, cores da marca e campos de esquema
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.
Assinatura criptográfica PKCS#7 usando certificado Apple Pass Type ID
Payload REST JWT de conta de serviço do Google Cloud
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_PROGRAMLOYALTY_PROGRAM e Níveis
Acúmulo de pontos por leitura (defaultChangeValue) com progressão automática de nível
STAMP_CARDSTAMP_CARD_ADD / DEDUCT
Controla posições de selos (0..maximumValue) com onCap ('noop' | 'reset') e rewardClaimBehavior
PREPAID_CARDRazão PREPAID_CARD
Contabilidade de razão pré-paga em subunidades ISO 4217 com aplicação de disallowNegativeBalance
VALID_ONCE_PER_DAYVALID_ONCE_PER_DAY e RENEW
Limites diários por fuso horário e extensão automática de expirationDate na leitura
Central de Ajuda Passinstance: Navegue pelos 10 tópicos e 94 guias
Explore guias passo a passo, diagramas de arquitetura de fluxos, esquemas de payloads JSON e recursos de solução de problemas em cada domínio.
Tudo o que precisa para começar a utilizar a Passinstance rapidamente.
Descubra como aplicar cartões digitais Wallet a diferentes modelos de negócio.
Desenhe, emita, organize e mantenha os seus cartões digitais Wallet.
Entregue cartões aos clientes e mantenha as carteiras sempre atualizadas.
Configure fornecedores Wallet, certificados e recursos NFC.
Valide passes, controle entradas e processe recompensas de clientes.
Ligue a Passinstance aos seus sistemas atuais e automatize processos.
Acompanhe o desempenho, atividade e adoção dos seus passes.
Gerencie organização, utilizadores, subscrição e definições fiscais.
Encontre respostas, resolva falhas e contacte a equipa de suporte.
