Visão Geral: Selecionar e Emparelhar Hardware Leitor Sem Contacto
Como os smartphones iOS e Android de consumo restringem a emulação simples de cartões anfitriões e exigem handshakes criptográficos do terminal para passes de carteira de circuito fechado, a verdadeira validação por aproximação requer hardware leitor Apple VAS + Google Smart Tap. A Passinstance modela e autentica nativamente parques físicos de leitores através das entidades de base de dados hardware reader, reader device, store location e POS terminal.
Arquiteturas de Leitores Suportadas e NfcReaderMode
A Passinstance suporta quatro modos operacionais definidos pelo enum de backend NfcReaderMode entre os fornecedores de hardware suportados (reader provider: HID, ZEBRA, INGENICO, VERIFONE, PAX, SUNMI):
Enum NfcReaderMode | Comportamento do Protocolo e Adequação de Hardware |
|---|---|
AUTO | Interrogação automática de protocolo duplo: o terminal alterna entre Apple VAS e Google Smart Tap numa única janela de aproximação de 300ms (recomendado para certified NFC e terminais POS modernos). |
KEYBOARD_WEDGE | Emulação de teclado HID USB: o leitor desencripta o payload do passe no dispositivo e escreve o serialNumber + Enter diretamente no Web Scanner da Passinstance ou no ecrã de caixa do POS. |
APPLE_WALLET | Interrogação dedicada apenas a Apple VAS; otimizado para ambientes exclusivos iOS ou torniquetes rápidos de protocolo único. |
GOOGLE_SMART_TAP | Interrogação NDEF dedicada apenas a Google Smart Tap. |
Famílias de Hardware Certificadas
-
1
Leitores certified NFC (
NFC Terminal,NFC Terminal,NFC TerminalWi-Fi/PoE): Leitores NFC dedicados para carteiras móveis que suportam desencriptação simultânea Apple VAS e Google Smart Tap. As unidades NFC Pro enviam aproximações desencriptadas diretamente paraPOST /api/v1/reader/validatecom cabeçalho de assinatura HMACx-reader-signature(oux-signature). -
2
Terminais Verifone, Ingenico, HID, Zebra, PAX e Sunmi: Terminais empresariais modelados através de reader provider e registos
store location/POS terminal/hardware reader. -
3
Leitores Óticos de Balcão 2D (Alternativa Sem Autorização): Leitores de códigos de barras óticos 2D padrão (Zebra, Honeywell, Tera) a ler códigos QR/Aztec da Carteira em modo
KEYBOARD_WEDGEoferecem implementação instantânea sem necessidade de aprovações de chaves NFC da Apple/Google.
Importante: Os leitores que chamam
POST /api/v1/reader/redeemou/api/v1/reader/validatetêm de se autenticar comX-Reader-Secret(reader integration secret), ao passo que os webhooks na cloud NFC que chamamPOST /api/v1/reader/validateassinam os pedidos comx-reader-signature/x-signature.
Endpoints da API de Leitores de Hardware e Terminais (Reader Management API / Reader Orchestration API)
| Método | Caminho do Endpoint | Cabeçalho Auth | Descrição |
|---|---|---|---|
GET / POST | /api/v1/reader/devices | Bearer / API Key | Lista ou regista dispositivos hardware reader certified NFC (GET/PUT/DELETE .../readers/:id e POST .../readers/:id/test). |
| GET | /api/v1/reader/devices/:id/config-file | Bearer / API Key | Gera um pacote config.txt pronto a carregar para leitores certified NFC (VAS1MerchantID, ST1CollectorID, ranhuras de chaves e URL de webhook cloud). |
| POST | /api/v1/reader/validate | x-reader-signature | Webhook dedicado de receção de aproximações para leitores cloud certified NFC Pro (reader event payload, além de lote /events/batch). |
| POST | /api/v1/reader/validate | X-Reader-Secret | Valida uma entrada por barcodeValue (request payload: customerId, barcodeValue, idempotencyKey, operatorId?, location?). |
| POST | /api/v1/reader/redeem | X-Reader-Secret | Processa um resgate idempotente por aproximação (request payload: customerId, passId, amount?, idempotencyKey, operatorId?). |
Exemplo: Resgate por Aproximação em Leitor de Hardware (POST /api/v1/reader/redeem)
POST /api/v1/reader/redeem
Headers:
X-Reader-Secret: <reader integration secret>
Content-Type: application/json
{
"customerId": "8f94d930-b302-4fc8-9f12-000000000001",
"passId": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"amount": "12.50",
"idempotencyKey": "tap_01J9Z9K2M4N6P8Q0R2S4",
"operatorId": "term_checkout_lane_02"
}
Resposta (200 OK):
{
"success": true,
"resultingValue": "37.50"
}
Consulte Configuração de Passes NFC, Apple VAS, Google Smart Tap e Configuração e Definições do Scanner.
