Skip to content
Guia da Central de Ajuda · API de programador
6 min de leituraVerificado 2026-11-16

Referência da API

Navegue pelo catálogo REST completo para Passes, Modelos, Scanner, Entrega, Webhooks e Operações em lote.

Neste guia

Visão Geral

A API REST do Passinstance está organizada em controladores de domínio modulares montados principalmente sob /api/v1 (com montagens dedicadas sem prefixo para POS /v1/pos/*, Pull Webhooks /webhook-payload, Webhooks de Fornecedores de Entrada /webhooks/*, sondas de Saúde /health/* e Ligações Inteligentes /s/:token e /d/:slug). Todos os endpoints utilizam verbos HTTP padrão (GET, POST, PUT, PATCH, DELETE), impõem o isolamento de tenant do espaço de trabalho a partir da sua credencial de API e devolvem um payload JSON determinístico (API response (T) nas APIs do espaço de trabalho).

Pré-requisitos: Gere uma chave de API do espaço de trabalho (pi_live_... ou pi_test_...) com os valores API_KEY_SCOPE_VALUES necessários (passes, templates, scans, webhooks, analytics ou *) em /settings/workspace/developer/api-credentials antes de invocar rotas /api/v1/*. A documentação OpenAPI interativa está disponível em GET /api/public/docs e /docs.

Ciclo de Vida de Pedidos e Respostas

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
CICLO DE VIDA DE PEDIDOS REST API E ENVELOPE
ATORES DE SISTEMA PARTICIPANTES
P1 Integração Externa
P2 Passinstance /api/v1/*
P3 Fornecedores Wallet e BD
ETAPA 1 PEDIDO / AÇÃO POST/api/v1/passes
ETAPA 2 PEDIDO / AÇÃO Validar DTO e Âmbito Tenant
ETAPA 3 PEDIDO / AÇÃO Assinar .pkpass (bundleId)
›
idempotencyKey
›
e Construir JWT Google
ETAPA 4 RESPOSTA 201 Created
›
API response (request payload)
ETAPA 5 PEDIDO / AÇÃO PATCH/api/v1/passes/:id
ETAPA 6 PEDIDO / AÇÃO Gravar Atualização de Campo
ETAPA 7 RESPOSTA 200 OK
›
7. Colocar Push APNs/Google

Catálogo de Endpoints REST por Domínio

1. Passes, Upserts e Operações em Lote

VerboCaminhoDescrição
POST/api/v1/passesEmite uma instância de passe (request payload: templateId, externalId opcional, idempotencyKey, attributes) assinada com o certificado do modelo (bundleId = passTypeIdentifier da Apple).
POST/api/v1/passes/upsert-by-external-idCria ou atualiza de forma idempotente um passe correspondido por (templateId, externalId) (request payload).
GET/api/v1/passesLista instâncias de passes com paginação, filtragem por estado (pass status) e consultas de pesquisa.
GET/api/v1/passes/:idObtém detalhes completos, atributos dinâmicos, externalId, serialNumber e estado de registo.
PATCH / PUT/api/v1/passes/:idAtualiza campos dinâmicos, escalão ou data de expiração e envia atualizações push em tempo real para as carteiras instaladas.
POST/api/v1/passes/voiding/:id/voidAnula um passe (request payload + VoidingReason) e envia uma atualização push silenciosa com voided: true.
DELETE/api/v1/passes/:idElimina de forma reversível um passe e revoga instalações ativas na carteira.
POST/api/v1/passes/exportExporta registos de passes filtrados como tarefa de transferência CSV UTF-8 ou JSON.
POST/api/v1/batch-pass-operations/createExecuta a criação em massa de passes síncrona/em fila através de Batch Operations API (também /update, /upsert, /activate, /deactivate, /delete).
POST/api/v1/batch-processingSubmete uma tarefa assíncrona em massa de grande volume em CSV/JSON monitorizada através de Batch Processing API.

2. Modelos e Mecânicas

VerboCaminhoDescrição
GET/api/v1/templatesLista modelos de passes do espaço de trabalho, tipos de passes (PassKind), vinculações de certificado bundleId e estados de publicação.
GET/api/v1/templates/:idDevolve o esquema do modelo, a configuração visual de disposição e as mecânicas ativas.
POST/api/v1/templates/:id/publishPublica alterações de rascunho (request payload) e envia atualizações push em lote (execute GET .../publish-risk-check previamente).
GET/api/v1/templates/:templateId/attributesLista chaves e tipos de campos dinâmicos necessários ao emitir passes (suporta OAuth templates:read).
POST/api/v1/mechanics/redeemResgata uma recompensa desbloqueada de cartão de fidelização ou de carimbos (request payload: UUID passId, mechanicId).
GET/api/v1/mechanics/:mechanicId/passes/:passId/ledgerDevolve o registo contabilístico de transações para a mecânica de valor armazenado ou fidelização de um passe (GET /api/v1/balance-changes para o feed do tenant).

3. Leituras, Dispositivos e Validação POS

VerboCaminhoDescrição
POST/api/v1/scansAvalia uma leitura de código de barras/NFC face ao Validation Rules Engine de 14 regras (ScanMode e scan status).
POST/api/v1/scans/prepareEmite um scan nonce criptográfico de curta duração para proteção contra ataques de repetição.
GET/api/v1/scans/passPesquisa de passe só de leitura por ?barcode=... (ou parâmetro de caminho GET /api/v1/scans/pass/:barcodeValue).
POST/api/v1/scans/pass/:passId/useExecuta diretamente uma ação request payload (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET).
GET/api/v1/scans/result/:scanIdObtém o registo de auditoria e o ruleTrace de uma leitura concluída.
GET/api/v1/scans/offline-datasetInstantâneo de passes paginado por cursor (offline scan dataset) para leitores portáteis offline.
POST/v1/pos/redeemEndpoint POS sem prefixo que executa comandos atómicos PosOperation (DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, CUSTOM).
POST/api/v1/reader/redeemProcessa resgates em leitores físicos NFC autenticados através de X-Reader-Secret (POST /api/v1/reader/validate para validação de entrada).

4. Notificações Push, Webhooks e Fluxos de Trabalho

VerboCaminhoDescrição
POST/api/v1/push-notifications/templates/:id/sendEnvia uma notificação imediata para todos os dispositivos registados num modelo (request payload em /passes/:id/schedule).
POST/api/v1/push-notifications/segmentationDireciona atualizações push localizadas para um segmento filtrado de passes (request payload).
POST/api/v1/push-notifications/batchEnvia notificações em lote para listas de passes ou carregamentos CSV (request payload).
GET / POST/api/v1/webhooksObtém a visão geral de webhooks ou gere endpoints de webhooks push HTTPS de saída (/api/v1/webhooks/subscriptions).
GET/webhook-payloadAPI Pull sem prefixo (GET /api/v3/webhook-payload também suportado) que consulta eventos não confirmados para recetores restritos por firewall.
POST/webhook-payload/acknowledgeConfirmação sem prefixo ({ upTo, webhookId }, ou POST /api/v3/webhook-payload/acknowledge).
GET / POST/api/v1/workflowsLista ou cria fluxos de trabalho automatizados orientados a eventos (Workflow Engine API, juntamente com /api/v1/automations).

5. Analítica, Faturação e Governação de Privacidade

VerboCaminhoDescrição
GET/api/v1/analyticsRelatório de telemetria multissérie (passes, registrations, walletAppsShare; consulte /api/v1/analytics/passes/overview).
GET/api/v1/analytics/wallet-installationsMatriz de instalação Apple Wallet vs. Google Wallet ao nível do dispositivo e do passe (request payload).
GET/api/v1/billing/subscriptionDevolve o plano de subscrição ativo, o ciclo de faturação e o estado de renovação.
GET/api/v1/billing/invoices/:id/downloadTransmite a fatura fiscal em PDF (application/pdf).
POST/api/v1/customer/:customerId/privacy-settings/data-subject-exportGera um arquivo de dados pessoais em conformidade com o RGPD para um titular de passe.

Envelope Padrão API response (T) e Códigos de Estado

Envelope de Sucesso (200 OK / 201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01hxyz8821",
    "templateId": "tmpl_vip_member",
    "serialNumber": "PI-VIP-8821",
    "externalId": "crm_cust_44910",
    "bundleId": "pass.com.passinstance.vip",
    "status": "ACTIVE",
    "passAccessUrl": "https://api.passinstance.com/s/vip-8821-x9a2"
  },
  "meta": {
    "requestId": "req_99481a2b7c",
    "timestamp": "2026-11-16T10:10:00.000Z"
  }
}

Códigos de Estado HTTP Padrão

Código de EstadoSignificadoResolução
200 OK / 201 CreatedO pedido foi concluído com sucesso de forma síncrona.Leia o payload do resultado a partir de data.
400 Bad RequestFalha na validação do DTO ou violação de restrição de domínio.Inspecione errorCode, messageKey e a matriz details.
401 UnauthorizedChave de API / token Bearer em falta, expirado ou inválido.Verifique o cabeçalho x-api-key ou Authorization (e a correspondência do espaço de trabalho pi_test_ vs pi_live_).
403 ForbiddenA chave válida não possui o âmbito necessário (por exemplo, falta 'passes') ou acesso ao tenant.Verifique os âmbitos atribuídos através de GET /api/v1/api-keys.
404 Not FoundO ID do recurso de destino não existe no espaço de trabalho autenticado.Verifique o UUID / serialNumber / externalId e o ambiente do espaço de trabalho.
409 ConflictexternalId ou serialNumber duplicado, ou colisão concorrente de idempotência.Utilize /api/v1/passes/upsert-by-external-id ou forneça uma idempotencyKey única.
429 Too Many RequestsLimite de rajada de 1 segundo ou limite de taxa de quota excedido.Respeite os cabeçalhos de resposta Retry-After e RateLimit-Reset.

Consulte as definições completas de esquemas no Centro de Documentação para Programadores e em Visão Geral da API e Autenticação.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.