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
P1Integração Externa
P2Passinstance /api/v1/*
P3Fornecedores Wallet e BD
ETAPA 1PEDIDO / AÇÃOPOST/api/v1/passes
ETAPA 2PEDIDO / AÇÃOValidar DTO e Âmbito Tenant
ETAPA 3PEDIDO / AÇÃOAssinar .pkpass (bundleId)
›
idempotencyKey
›
e Construir JWT Google
ETAPA 4RESPOSTA201 Created
›
API response (request payload)
ETAPA 5PEDIDO / AÇÃOPATCH/api/v1/passes/:id
ETAPA 6PEDIDO / AÇÃOGravar Atualização de Campo
ETAPA 7RESPOSTA200 OK
›
7. Colocar Push APNs/Google→
[ FLUXO DE ARQUITETURA DO SISTEMA: CICLO DE VIDA DE PEDIDOS REST API E ENVELOPE ]
Integração Externa Passinstance /api/v1/* Fornecedores Wallet e BD
| | |
|-- 1. POST /api/v1/passes --------->| |
| Header: x-api-key: pi_live_.. |-- 2. Validar DTO e Âmbito Tenant |
| Body: externalId, |-- 3. Assinar .pkpass (bundleId) |
| idempotencyKey | e Construir JWT Google ------>|
|<-- 4. 201 Created -----------------| |
| API response (request payload) | |
| | |
|-- 5. PATCH /api/v1/passes/:id ---->| |
| Body: { attributes: {...} } |-- 6. Gravar Atualização de Campo ->|
|<-- 7. 200 OK ----------------------|-- 7. Colocar Push APNs/Google ---->|
Catálogo de Endpoints REST por Domínio
1. Passes, Upserts e Operações em Lote
Verbo
Caminho
Descrição
POST
/api/v1/passes
Emite 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-id
Cria ou atualiza de forma idempotente um passe correspondido por (templateId, externalId) (request payload).
GET
/api/v1/passes
Lista instâncias de passes com paginação, filtragem por estado (pass status) e consultas de pesquisa.
GET
/api/v1/passes/:id
Obtém detalhes completos, atributos dinâmicos, externalId, serialNumber e estado de registo.
PATCH / PUT
/api/v1/passes/:id
Atualiza 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/void
Anula um passe (request payload + VoidingReason) e envia uma atualização push silenciosa com voided: true.
DELETE
/api/v1/passes/:id
Elimina de forma reversível um passe e revoga instalações ativas na carteira.
POST
/api/v1/passes/export
Exporta registos de passes filtrados como tarefa de transferência CSV UTF-8 ou JSON.
POST
/api/v1/batch-pass-operations/create
Executa 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-processing
Submete uma tarefa assíncrona em massa de grande volume em CSV/JSON monitorizada através de Batch Processing API.
2. Modelos e Mecânicas
Verbo
Caminho
Descrição
GET
/api/v1/templates
Lista 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/:id
Devolve o esquema do modelo, a configuração visual de disposição e as mecânicas ativas.
POST
/api/v1/templates/:id/publish
Publica alterações de rascunho (request payload) e envia atualizações push em lote (execute GET .../publish-risk-check previamente).
GET
/api/v1/templates/:templateId/attributes
Lista chaves e tipos de campos dinâmicos necessários ao emitir passes (suporta OAuth templates:read).
POST
/api/v1/mechanics/redeem
Resgata uma recompensa desbloqueada de cartão de fidelização ou de carimbos (request payload: UUID passId, mechanicId).
Devolve 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
Verbo
Caminho
Descrição
POST
/api/v1/scans
Avalia uma leitura de código de barras/NFC face ao Validation Rules Engine de 14 regras (ScanMode e scan status).
POST
/api/v1/scans/prepare
Emite um scan nonce criptográfico de curta duração para proteção contra ataques de repetição.
GET
/api/v1/scans/pass
Pesquisa de passe só de leitura por ?barcode=... (ou parâmetro de caminho GET /api/v1/scans/pass/:barcodeValue).