Descripción general: selección y emparejamiento de hardware lector sin contacto
Debido a que los teléfonos inteligentes iOS y Android restringen la emulación directa de tarjetas y exigen protocolos criptográficos con el terminal para pases de monedero de circuito cerrado, el canje real por aproximación requiere hardware lector Apple VAS + Google Smart Tap. Passinstance modela y autentica de forma nativa parques de lectores físicos mediante las entidades de base de datos hardware reader, reader device, store location y POS terminal.
Arquitecturas de lectores compatibles y NfcReaderMode
Passinstance admite cuatro modos operativos definidos por el enum de backend NfcReaderMode entre los proveedores de hardware compatibles (reader provider: HID, ZEBRA, INGENICO, VERIFONE, PAX, SUNMI):
Enum NfcReaderMode | Comportamiento de protocolo e idoneidad de hardware |
|---|---|
AUTO | Sondeo automático de protocolo dual: el terminal alterna entre Apple VAS y Google Smart Tap dentro de una misma ventana de 300 ms al acercar el teléfono (recomendado para certified NFC y terminales POS modernos). |
KEYBOARD_WEDGE | Emulación de teclado USB HID: el lector descifra el payload del pase localmente y escribe el serialNumber + Enter directamente en el Escáner Web de Passinstance o en la pantalla de cobro del POS. |
APPLE_WALLET | Sondeo dedicado exclusivamente a Apple VAS; optimizado para entornos exclusivos de iOS o tornos rápidos de protocolo único. |
GOOGLE_SMART_TAP | Sondeo NDEF dedicado exclusivamente a Google Smart Tap. |
Familias de hardware certificadas
-
1
Lectores certified NFC (
NFC Terminal,NFC Terminal,NFC TerminalWi-Fi/PoE): Lectores NFC diseñados específicamente para monederos móviles compatibles con descifrado simultáneo de Apple VAS y Google Smart Tap. Las unidades NFC Pro envían lecturas descifradas directamente aPOST /api/v1/reader/validatecon cabecera de firma HMACx-reader-signature(ox-signature). -
2
Terminales Verifone, Ingenico, HID, Zebra, PAX y Sunmi: Terminales empresariales modelados mediante reader provider y registros
store location/POS terminal/hardware reader. -
3
Escáneres ópticos 2D de mostrador (respaldo sin permisos Apple/Google): Escáneres ópticos estándar de códigos 2D (Zebra, Honeywell, Tera) que leen códigos QR o Aztec en modo
KEYBOARD_WEDGEofrecen despliegue inmediato sin aprobaciones de claves NFC de Apple ni Google.
Importante: Los lectores que invocan
POST /api/v1/reader/redeemo/api/v1/reader/validatedeben autenticarse medianteX-Reader-Secret(reader integration secret), mientras que los webhooks en la nube NFC que invocanPOST /api/v1/reader/validatefirman las peticiones mediantex-reader-signature/x-signature.
Endpoints de API de lectores físicos y terminales (Reader Management API / Reader Orchestration API)
| Método | Ruta del endpoint | Cabecera de auth | Descripción |
|---|---|---|---|
GET / POST | /api/v1/reader/devices | Bearer / Clave API | Lista o registra dispositivos hardware reader de certified NFC (GET/PUT/DELETE .../readers/:id y POST .../readers/:id/test). |
| GET | /api/v1/reader/devices/:id/config-file | Bearer / Clave API | Genera un archivo config.txt listo para cargar en lectores certified NFC (VAS1MerchantID, ST1CollectorID, ranuras de clave y URL de webhook en nube). |
| POST | /api/v1/reader/validate | x-reader-signature | Webhook dedicado de ingesta de lecturas para lectores en nube certified NFC Pro (reader event payload, además de /events/batch). |
| POST | /api/v1/reader/validate | X-Reader-Secret | Valida una entrada mediante barcodeValue (request payload: customerId, barcodeValue, idempotencyKey, operatorId?, location?). |
| POST | /api/v1/reader/redeem | X-Reader-Secret | Procesa un canje por proximidad idempotente (request payload: customerId, passId, amount?, idempotencyKey, operatorId?). |
Ejemplo: canje desde lector 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"
}
Respuesta (200 OK):
{
"success": true,
"resultingValue": "37.50"
}
Consulte Configuración de pases NFC, Apple VAS, Google Smart Tap y Configuración del escáner.
