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
Equivalente visual no Painel
Elementos-chave da interface

Equivalente no Painel: Chaves personalizadas e regras de validação

As chaves definidas em Custom properties (ex.: holderName, validUntil) correspondem exatamente às chaves JSON aceitas na API.

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