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

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