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
Início rápido em 5 minObter chave de API

Crie seu primeiro passe de Wallet em menos de 5 minutos

Emita, assine criptograficamente e distribua passes Apple Wallet (.pkpass) e Google Wallet com uma única chamada REST.

Estúdio de passes ao vivo — edite os campos para atualizar código e cartão
Entrega Apple Wallet (.pkpass) e Google Wallet
Pré-visualização
ARAcme Rewards
Pontos
450
Membro
Jane Doe
Gold VIP
MEMBER-2024-8891
PKCS#7 · .pkpassHTTP 201
POST/api/v1/passes
curl --max-time 30 -X POST https://api.passinstance.com/api/v1/passes \
  -H "X-API-Key: $PASSINSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "externalId": "CRM-CUST-99201",
    "name": "Acme VIP Customer Pass",
    "attributes": {
      "guestName": "Jane Doe",
      "tier": "Gold VIP",
      "points": "450"
    },
    "storedValue": "50.00",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'
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

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

Exemplo: pi_live_98a7b6c5d4e3f2a1
Parâmetros de consulta3 opcional(is)

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/templates/{id}Chave de API
Gestão de modelos

Obter detalhes do modelo

Recupere detalhes completos de um modelo de passe incluindo cores, configurações de código de barras, campos de layout e regras mecânicas.

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

Identificador exclusivo do modelo.

Exemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/templates/{id}/fieldsChave de API
Gestão de modelos

Obter campos do modelo

Recupere as definições de campos dinâmicos e chaves personalizadas que podem ser preenchidas por passe para um determinado modelo.

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 exclusivo do modelo.

Exemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Parâmetros de consulta1 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/templatesChave de API
Gestão de modelos

Criar um modelo de passe

Crie e registre um novo modelo reutilizável com identidade visual, tipo de código de barras, configuração NFC e campos de layout.

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

Configuração de criação de modelo correspondente ao esquema JSON OpenAPI.

Corpo da requisição6 obrigatório(s) • 4 opcional(is)
namestring
Obrigatório

Nome de exibição do modelo.

Exemplo: VIP Loyalty Card Template
descriptionstring
Obrigatório

Descrição detalhada da finalidade do passe e benefícios do nível.

Exemplo: Exclusive loyalty and rewards card for VIP customers
organizationNamestring
Obrigatório

Nome da organização ou marca impresso no cabeçalho do cartão.

Exemplo: Acme Rewards
kindstring (enum)
Obrigatório

storeCard, coupon, eventTicket, generic, boardingPass ou membership.

Exemplo: storeCard
statusstring (enum)
Obrigatório

DRAFT, PUBLISHED, ARCHIVED, DEPRECATED ou UNDER_REVIEW.

Exemplo: PUBLISHED
preferredStyleSchemestring (enum)
Obrigatório

DARK, posterGeneric, posterEventTicket, bannerEventTicket ou semanticBoardingPass.

Exemplo: DARK

Códigos de status de resposta

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.

Corpo da requisição4 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/templates/{id}/copyChave de API
Gestão de modelos

Duplicar modelo

Clone um modelo de passe existente com seu layout, cores, imagens e mecânicas dentro do mesmo workspace.

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 de origem a ser duplicado.

Exemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Optional name, description, and ISO 4217 currency override for the duplicated template.

Corpo da requisição3 opcional(is)

Códigos de status de resposta

DELETEhttps://api.passinstance.com/api/v1/templates/{id}Chave de API
Gestão de modelos

Excluir modelo

Exclua um modelo de passe e agende uma tarefa assíncrona para revogar e desativar os passes associados no Apple Wallet e Google Wallet.

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 ser excluído.

Exemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Códigos de status de resposta

Notificações de modelo

3 endpoints
POSThttps://api.passinstance.com/api/v1/push-notifications/templates/{id}/sendChave de API
Notificações de modelo

Transmitir push para passes do modelo

Transmita uma notificação push imediata na tela de bloqueio para todos os passes ativos do Apple Wallet e Google Wallet emitidos sob um modelo.

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 cujos dispositivos registrados receberão a transmissão.

Exemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Payload Payload da requisição contendo pushNotificationText (máx. 85 caracteres) e texto de cabeçalho opcional.

Corpo da requisição1 obrigatório(s) • 1 opcional(is)
pushNotificationTextstring
Obrigatório

Mensagem na tela de bloqueio enviada aos passes ativos (máx. 85 caracteres; aceita marcadores).

Exemplo: Flash Sale starts now! Show your VIP pass at checkout for 2x points.

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/templates/{id}/notificationChave de API
Notificações de modelo

Listar notificações agendadas

Liste todas as campanhas de notificações push agendadas e executadas recentemente para um modelo de passe específico.

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

Template UUID.

Exemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Códigos de status de resposta

DELETEhttps://api.passinstance.com/api/v1/templates/notification/{notificationId}Chave de API
Notificações de modelo

Cancelar notificação agendada

Cancele uma notificação push de modelo agendada pendente antes que ela seja enviada aos dispositivos registrados.

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)
notificationIdstring (UUID)
Obrigatório

UUID da notificação agendada retornado ao listar ou agendar notificações.

Exemplo: f1e2d3c4-b5a6-4987-8765-43210fedcba9

Códigos de status de resposta

Integrações de modelo

2 endpoints
POSThttps://api.passinstance.com/api/v1/integration-connections/embed-widgetsChave de API
Integrações de modelo

Criar integração incorporada (iFrame)

Crie uma configuração de widget iFrame incorporável para um modelo publicado para integrar o cadastro de passes em seu site.

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

Configuration for the embedded download widget including templateId and allowed host domains.

Corpo da requisição3 obrigatório(s) • 1 opcional(is)
namestring
Obrigatório

Nome de exibição para a integração do widget incorporado.

Exemplo: Checkout Loyalty Embed Widget
templateIdstring (UUID)
Obrigatório

UUID do modelo de passe de destino.

Exemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
allowedDomainsstring[]
Obrigatório

Lista de origens (domínios) autorizadas a incorporar o widget.

Exemplo: ["shop.yourbrand.com", "app.yourbrand.com"]

Códigos de status de resposta

Gestão de passes

11 endpoints
POSThttps://api.passinstance.com/api/v1/passesChave de API
Gestão de passes

Emitir um novo passe

Crie e emita um novo passe Apple Wallet (.pkpass) e Google Wallet a partir de um modelo com campos do cliente, código de barras e valores dinâmicos.

Cabeçalhos2 obrigatório(s) • 1 opcional(is)
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
Parâmetros de consulta2 opcional(is)

Payload Payload da requisição contendo ID do modelo, número de série único, valores de campos do cliente e configuração opcional de código de barras.

Corpo da requisição1 obrigatório(s) • 15 opcional(is)
templateIdstring (UUID)
Obrigatório

ID do modelo para o passe.

Exemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idChave de API
Gestão de passes

Criar ou atualizar passe por ID externo (Upsert)

Crie ou atualize de forma idempotente um passe indexado por (customerId, externalId) para sincronização perfeita com CRM, PDV e e-commerce.

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 contendo templateId, externalId e atributos dinâmicos do passe.

Corpo da requisição2 obrigatório(s) • 3 opcional(is)
templateIdstring (UUID)
Obrigatório

UUID do modelo de destino.

Exemplo: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Obrigatório

Identificador externo de CRM/PDV estável e único dentro do seu espaço.

Exemplo: CRM-CUST-99201

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createChave de API
Gestão de passes

Emitir passes em lote

Emita múltiplos passes wallet em uma operação em lote atômica com validação e relatório de falhas.

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 contendo uma matriz de configurações de passes.

Corpo da requisição1 obrigatório(s)
passesarray of objects
Obrigatório

Matriz de itens de passe com templateId, barcodeValue e additionalData.

Exemplo: [ { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-001", "additionalData": { "name": "Member #001" } }, { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-002", "additionalData": { "name": "Member #002" } } ]

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/passesChave de API
Gestão de passes

Listar todos os passes

Recupere uma lista paginada de passes para o espaço de cliente autenticado com filtros de busca e status.

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 consulta13 opcional(is)

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/passes/{id}Chave de API
Gestão de passes

Obter um passe

Obtenha todos os detalhes, status de instalação e links de download de um único passe pelo seu ID exclusivo.

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

Identificador UUID exclusivo do passe.

Exemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Códigos de status de resposta

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

Exemplo: pi_live_98a7b6c5d4e3f2a1
Parâmetros de caminho1 obrigatório(s)
idstring (UUID)
Obrigatório

UUID exclusivo do passe a atualizar.

Exemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Campos Payload da requisição a modificar no passe. Dispositivos instalados receberão atualizações instantâneas em segundo plano.

Corpo da requisição13 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidChave de API
Gestão de passes

Desativar um passe

Marque um passe como anulado ou reativado no Apple Wallet e Google Wallet com propagação push instantânea.

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

ID exclusivo da instância do passe a anular ou reativar.

Exemplo: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Payload Payload da requisição controlando o estado de anulação, motivo de auditoria e opções de propagação wallet.

Corpo da requisição1 obrigatório(s) • 1 opcional(is)
voidedboolean
Obrigatório

Defina como true para anular o passe ou false para reativá-lo.

Exemplo: true

Códigos de status de resposta

DELETEhttps://api.passinstance.com/api/v1/passes/{id}Chave de API
Gestão de passes

Excluir passe

Exclua permanentemente um passe do seu workspace e revogue qualquer instalação ativa no Apple Wallet e Google Wallet.

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 exclusivo do passe a ser excluído.

Exemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Códigos de status de resposta

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.

Exemplo: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Parâmetros de caminho1 obrigatório(s)
idstring (UUID)
Obrigatório

UUID exclusivo do passe a operar.

Exemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Payload da requisição contendo a ação mecânica, valor decimal opcional, ID do operador e local.

Corpo da requisição1 obrigatório(s) • 4 opcional(is)
actionstring (enum)
Obrigatório

INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE ou NOOP.

Exemplo: INCREMENT

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueChave de API
Gestão de passes

Ajustar saldo do passe

Credite (adicione) ou debite (deduza) manualmente saldo armazenado ou pontos de recompensa em um passe com registro de auditoria de transações.

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 ajuste atômico e evitar créditos duplicados.

Exemplo: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Parâmetros de caminho1 obrigatório(s)
idUUID
Obrigatório

ID da instância do passe de destino.

Exemplo: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Payload de ajuste especificando operação CREDIT ou DEBIT, valor e motivo.

Corpo da requisição2 obrigatório(s) • 2 opcional(is)
actionstring
Obrigatório

Ação da transação: 'CREDIT' para adicionar valor ou 'DEBIT' para deduzir valor.

Exemplo: CREDIT
amountstring
Obrigatório

Valor numérico a creditar ou debitar como texto.

Exemplo: 25.00

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/mechanics/redeemChave de API
Gestão de passes

Resgatar recompensa de mecânica do passe

Resgate uma recompensa conquistada de fidelidade ou cartão de selos usando sua mecânica de passe configurada com proteção de idempotência.

Cabeçalhos1 obrigatório(s) • 1 opcional(is)
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

Solicitação de resgate especificando passId, mechanicId e opcionalmente idempotencyKey.

Corpo da requisição2 obrigatório(s) • 3 opcional(is)
passIdstring (UUID)
Obrigatório

UUID do passe que resgata a recompensa.

Exemplo: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Obrigatório

UUID da regra de mecânica do passe vinculada ao modelo.

Exemplo: mech_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Códigos de status de resposta

Pesquisa e análises

4 endpoints
GEThttps://api.passinstance.com/api/v1/passes/searchChave de API
Pesquisa e análises

Pesquisar passes

Realize uma pesquisa de texto completo nos passes emitidos por número de série, ID externo, e-mail, titular ou atributos.

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 consulta1 obrigatório(s)
querystring
Obrigatório

Texto de pesquisa (até 500 caracteres).

Exemplo: Jane Doe

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}Chave de API
Pesquisa e análises

Obter estatísticas de passes

Obtenha estatísticas agregadas de emissão, ativação, instalação na carteira e resgates para um modelo de passe específico.

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)
templateIdstring (UUID)
Obrigatório

UUID do modelo de destino.

Exemplo: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Parâmetros de consulta2 opcional(is)

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyChave de API
Pesquisa e análises

Obter histórico de status do passe

Recupere o histórico cronológico de auditoria de mudanças de status, atualizações de saldo/pontos, leituras e anulações de um passe.

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

Pass UUID.

Exemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8
Parâmetros de consulta1 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/passes/exportChave de API
Pesquisa e análises

Exportar passes para CSV

Transmita uma exportação CSV UTF-8 (text/csv; charset=utf-8) das instâncias de passes selecionadas por 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

Payload da requisição especificando de 1 a 2.000 UUIDs de passes e o formato de exportação.

Corpo da requisição2 obrigatório(s)
passIdsstring[] (UUID v4)
Obrigatório

Matriz de 1 a 2.000 UUIDs de passes a incluir na exportação CSV.

Exemplo: ["pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"]
formatstring (enum)
Obrigatório

Formato de saída da exportação ('csv').

Exemplo: csv

Códigos de status de resposta

Entrega de passes

4 endpoints
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisChave de API
Entrega de passes

Obter URLs de recursos do passe

Obtenha as URLs diretas de download e distribuição de um passe, incluindo página PassFlow, .pkpass, JWT do Google Wallet e QR code.

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

Pass UUID.

Exemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Códigos de status de resposta

GEThttps://api.passinstance.com/d/{slug}/infoPúblico
Entrega de passes

Obter página de download personalizada

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.

Exemplo: acme-vip-2026
Parâmetros de consulta2 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadChave de API
Entrega de passes

Habilitar download do passe

Reative ou desbloqueie o link de download de um passe quando o modelo estiver configurado com bloqueio de novo download.

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 passe cujo download será desbloqueado.

Exemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Optional timestamp specifying how long re-download remains unlocked.

Corpo da requisição1 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailChave de API
Entrega de passes

Enviar passe por e-mail

Envie um e-mail transacional ao titular contendo o link direto de instalação para Apple Wallet e Google Wallet.

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 passe a ser enviado por e-mail.

Exemplo: b1d972dc-eccf-4f87-ab21-25939d9213d8

Recipient email address(es) and optional custom subject and message body.

Corpo da requisição4 opcional(is)

Códigos de status de resposta

Notificações push

2 endpoints
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.

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsChave de API
Notificações push

Enviar notificações push em massa

Envie uma notificação push na tela de bloqueio simultaneamente para uma lista selecionada de IDs de passes via APNs e Google Wallet.

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

Target pass UUID array (up to 500 passes) and notification message text supporting {attribute} placeholders.

Corpo da requisição2 obrigatório(s)
listOfPassesstring[] (UUID)
Obrigatório

Lista de 1 a 500 UUIDs de passes.

Exemplo: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Obrigatório

Mensagem de notificação na tela de bloqueio (suporta variáveis dinâmicas como {holderName}).

Exemplo: Hi {holderName}, you unlocked a new reward!

Códigos de status de resposta

Gestão de pacotes

4 endpoints
POSThttps://api.passinstance.com/api/v1/bundles/upsertChave de API
Gestão de pacotes

Criar ou atualizar pacote de passes

Crie ou atualize um pacote multipasse (.pkpasses) que permite aos usuários instalar vários passes relacionados com um único toque.

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

Array of pass UUIDs (up to 10) and optional existing bundleId.

Corpo da requisição1 obrigatório(s) • 1 opcional(is)
passesstring[] (UUID)
Obrigatório

Lista de 1 a 10 UUIDs de passes para agrupar no pacote.

Exemplo: ["b1d972dc-eccf-4f87-ab21-25939d9213d8", "c2e083ed-fddf-4a98-bc32-36040e0324e9"]

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/bundles/{id}/passesChave de API
Gestão de pacotes

Listar passes no pacote

Liste todos os passes individuais atualmente associados a um pacote de passes, incluindo status e números de série.

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 pacote de passes.

Exemplo: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
Parâmetros de consulta3 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/bundles/{id}/voidChave de API
Gestão de pacotes

Anular passes do pacote

Anule ou reative todos os passes pertencentes a um pacote de passes em uma única operação.

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 pacote de passes.

Exemplo: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Confirmation flag and optional audit reason for voiding all passes in the bundle.

Corpo da requisição1 obrigatório(s) • 1 opcional(is)
voidedboolean
Obrigatório

Deve ser definido como true para anular todos os passes do pacote.

Exemplo: true

Códigos de status de resposta

DELETEhttps://api.passinstance.com/api/v1/bundles/{id}Chave de API
Gestão de pacotes

Excluir pacote de passes

Exclua um agrupamento de pacote de passes do seu workspace.

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 pacote de passes a ser excluído.

Exemplo: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Códigos de status de resposta

Segurança

Visão geral — Como funciona a validação de passes

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

Pipeline de 14 regras

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Sincronização offline

GET /api/v1/scans/offline-dataset fornece snapshots paginados por cursor para terminais offline

Pareamento de chave scanner

POST /api/v1/scanner-keys/from-link troca token de pareamento + PIN por uma x-scanner-key

Configuração de scanner

3 endpoints
GEThttps://api.passinstance.com/api/v1/validation/configsChave de API
Configuração de scanner

Listar configurações de scanner

Liste todos os perfis de configuração de scanner (app móvel, scanner web, PDV) e suas permissões de modelo no seu workspace.

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 consulta2 opcional(is)

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}Chave de API
Configuração de scanner

Obter configuração de scanner

Obtenha os detalhes de uma configuração de scanner específica, incluindo modelos permitidos, mensagem pós-leitura e regras.

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 da configuração de scanner.

Exemplo: 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/validation/configsChave de API
Configuração de scanner

Criar configuração de scanner

Crie um novo perfil de configuração de scanner com modelos vinculados, ação de leitura padrão e mensagem de confirmação.

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

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Corpo da requisição2 obrigatório(s) • 2 opcional(is)
namestring
Obrigatório

Nome legível para a configuração do scanner.

Exemplo: Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Obrigatório

UUIDs dos modelos autorizados para validação neste perfil.

Exemplo: ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Códigos de status de resposta

Operações de leitura

4 endpoints
GEThttps://api.passinstance.com/api/v1/validation/scansChave de API
Operações de leitura

Listar registros de leitura

Consulte o histórico paginado de auditoria de leituras de passes filtrando por modelo, passe, configuração de scanner, decisão e período.

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 consulta3 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/scansChave de scanner
Operações de leitura

Processar leitura de código de barras / NFC

Valide um código de barras óptico, QR ou leitura NFC Apple VAS / Google Smart Tap de um terminal ou scanner móvel através do motor de 14 regras.

Cabeçalhos2 obrigatório(s) • 2 opcional(is)
x-scanner-keystring
Obrigatório

Chave de configuração de scanner provisionada no painel ou via link de pareamento.

Exemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Obrigatório

Deve ser application/json.

Exemplo: application/json

Payload Payload da requisição com string de código de barras lida, nonce antirrepetição opcional, metadados de canal/protocolo e contexto do operador.

Corpo da requisição1 obrigatório(s) • 8 opcional(is)
scannedBarcodeValuestring
Obrigatório

A string bruta lida de QR code, PDF417, CODE128, AZTEC ou toque NFC.

Exemplo: PI-8891-JD-VIP

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/scans/prepareChave de scanner
Operações de leitura

Preparar nonce de leitura antirrepetição

Emita um nonce criptográfico antirrepetição de curta duração vinculado a um código de barras antes de executar POST /api/v1/scans.

Cabeçalhos1 obrigatório(s)
x-scanner-keystring
Obrigatório

Chave de configuração de scanner provisionada no painel ou via link de pareamento.

Exemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Payload da requisição contendo o valor do código de barras lido ao qual vincular o nonce criptográfico.

Corpo da requisição1 obrigatório(s)
scannedBarcodeValuestring
Obrigatório

String do código de barras ou token NFC ao qual vincular o nonce antirrepetição.

Exemplo: PI-8891-JD-VIP

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetChave de scanner
Operações de leitura

Obter conjunto de dados offline do scanner

Baixe um conjunto paginado por cursor de instantâneos de passes restrito à x-scanner-key chamante para validação offline local quando a conexão cair.

Cabeçalhos1 obrigatório(s)
x-scanner-keystring
Obrigatório

Chave de configuração de scanner provisionada no painel ou via link de pareamento.

Exemplo: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Parâmetros de consulta3 opcional(is)

Códigos de status de resposta

Visão geral e endpoints

4 endpoints
Webhooks

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.

Eventos suportados

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Resposta esperada

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

Exemplo: https://your-server.com/webhooks/passinstance
eventsstring[] (enum)
Obrigatório

Valores tipos de eventos webhook: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Exemplo: ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Códigos de status de resposta

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}Chave de API
Visão geral e endpoints

Cancelar inscrição de Webhook

Exclua uma inscrição de webhook ativa pelo seu identificador e interrompa o envio de eventos futuros para esse endpoint.

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 da inscrição de webhook a ser removida.

Exemplo: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChave de API
Visão geral e endpoints

Listar assinaturas de webhooks

Recupere todas as assinaturas de webhooks ativas registradas para o seu espaço de cliente.

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

Códigos de status de resposta

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyPúblico
Visão geral e endpoints

Obter chave pública de assinatura Webhook

Obtenha a chave pública PEM ativa do Passinstance para verificar criptograficamente as assinaturas dos webhooks recebidos.

Códigos de status de resposta

Webhooks baseados em Pull

2 endpoints
Webhooks

Como funcionam os Pull Webhooks e suas limitações

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

Gatilhos de fluxo

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Ações de fluxo

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

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

Exemplo: pi_live_98a7b6c5d4e3f2a1
Parâmetros de consulta3 opcional(is)

Códigos de status de resposta

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeChave de API
Webhooks baseados em Pull

Confirmar eventos pull-webhook

Confirme payloads pull-webhook processados até um ID específico para que sejam marcados como entregues e removidos da fila.

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 especificando o ID limite superior processado (upTo).

Corpo da requisição1 obrigatório(s) • 1 opcional(is)
upTostring (UUID)
Obrigatório

Último ID de payload webhook processado; todos os eventos até este ID são confirmados.

Exemplo: whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Códigos de status de resposta

Eventos Webhook

4 guias
Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de modelo (Template Events)

Notificações webhook HTTP POST enviadas quando um modelo de passe é criado, atualizado, publicado ou excluído.

Modelo criado
POST
TEMPLATE_CREATED

Disparado quando um novo modelo de passe é criado

Modelo atualizado
POST
TEMPLATE_UPDATED

Disparado quando campos, layout ou mecânicas do modelo são alterados

Modelo publicado
POST
TEMPLATE_PUBLISHED

Disparado quando um rascunho é publicado para passes ativos

Modelo excluído
POST
TEMPLATE_DELETED

Disparado quando a exclusão do modelo e revogação na carteira são iniciadas

Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de passe (Pass Events)

Notificações webhook HTTP POST que acompanham todas as etapas do ciclo de vida do passe, da criação à remoção do dispositivo.

Passe criado
POST
PASS_CREATED

Disparado imediatamente quando um novo passe é emitido via API REST ou PassFlow

Passe atualizado
POST
PASS_UPDATED

Disparado quando atributos, pontos de fidelidade, nível ou saldo do passe mudam

Passe anulado
POST
PASS_VOIDED

Disparado quando um passe é anulado ou desativado no Apple Wallet e Google Wallet

Primeiro download do passe
POST
PASS_FIRST_DOWNLOAD

Disparado na primeira vez que um cliente resgata ou baixa o passe

Passe baixado
POST
PASS_DOWNLOADED

Disparado em cada download subsequente do pacote ou link do Google Wallet

Passe removido do dispositivo
POST
PASS_REMOVED

Disparado quando o cliente remove o passe do Apple Wallet ou Google Wallet

Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de leitura (Scan Events)

Notificações webhook HTTP POST emitidas em tempo real sempre que o código de barras ou NFC de um passe é lido e validado.

Leitura de passe criada
POST
APP_SCAN_CREATED

Disparado quando POST /api/v1/scans ou um scanner registra uma leitura

Metadados do resultado

Inclui passId, serialNumber, templateId, configId, decisão de validação e delta de saldo

Garantia de entrega

Entrega HTTPS POST pelo menos uma vez com cabeçalhos X-Webhook-Id e X-Webhook-Signature

Compatibilidade com fila Pull

Também disponível via GET /api/v1/webhook-payload para PDVs atrás de firewall

Eventos WebhookNotificação Webhook HTTP POST de saída

Eventos de mensagem e referência de status (Message Events)

Notificações webhook HTTP POST e códigos de status de entrega para notificações push, envios de e-mail e SMS.

Mensagem enviada
POST
MESSAGE_SENTNOTIFICATION_SENT

Disparado quando uma mensagem ou push de passe é enviado

Falha na entrega
POST
MESSAGE_FAILED

Disparado quando um e-mail, SMS ou notificação push falha na entrega

Referência de status da mensagem

QUEUED -> SENT -> DELIVERED (ou FAILED / BOUNCED com código de diagnóstico)

Correlação idempotente

Correlacione eventId e passId no consumidor webhook para desduplicar novas tentativas

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.