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