Skip to content
Referência da API REST e SDKs

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.

Obter chaves de API
Bancada interativa — os trechos são atualizados enquanto você digita
Visão geral

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.

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.

Chaves de produção (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Chaves Sandbox (Teste)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Chaves de scanner hardware
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
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.

Abrir especificação JSON OpenAPI 3.0
1. URL da especificação OpenAPI 3.0
https://passinstance.com/api/docs/openapi.json
2. Importar no Postman / Bruno

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.

200 OK / 201 CreatedSucesso
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
Conceitos principais

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

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
Artes Hero / StripApple: 375×123 px (3:1) | Google: 1032×336 px (aprox. 3:1)
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

Documentação completa de Plataforma e API

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.

Abrir Central de Ajuda

Tudo o que precisa para começar a utilizar a Passinstance rapidamente.