Descripción general
Los cupones y vales digitales para monederos conviven junto a las tarjetas de pago en la pantalla de bloqueo del smartphone del cliente, logrando tasas de canje muy superiores a los códigos promocionales por correo electrónico o vales en papel. Passinstance ofrece protección criptográfica, verificación antifraude de un solo uso y anulación en tiempo real tras el canje en mostrador.
Arquitectura del backend y mapeo de tipos de pase
En el backend de Passinstance, los programas de cupones se asignan a los tipos primitivos oficiales de cupones de Apple Wallet y Google Wallet:
-
Tipo de pase (pass type):
coupon(utiliza el diseño nativo de cupón de Apple con una insignia visual destacada para el descuento). -
Plantilla de demostración del catálogo:
promotional-coupon(disponible durante la incorporación). -
Modo de validación predeterminado:
VOIDED_AFTER_SCAN scan mode. -
Restricciones principales de dominio:
- limitToOneActivePerPass: true: Restringe los enlaces inteligentes de descarga a un único dispositivo, evitando el reenvío masivo de códigos de descuento en grupos. - expirationDate: Marca de tiempo W3C ISO 8601 que activa automáticamente las notificaciones nativas de vencimiento en la pantalla de bloqueo. - addSecurityAnimation: true: Renderiza un borde holográfico dinámico alrededor de los códigos de barras 2D para impedir la presentación fraudulenta de capturas de pantalla estáticas.
Ejecución de canje y protección antifraude
El flujo de canje en mostrador garantiza la integridad estricta de un solo uso mediante transacciones atómicas en base de datos dentro de Pass Mechanics Engine:
Prevención del fraude por captura de pantalla y repetición
Cuando un cajero escanea el código de barras del cupón:
-
1
El escáner envía una solicitud a
POST /api/v1/scansconscannedBarcodeValuey la clave secreta del escáner enx-scanner-key. -
2
El servidor confirma que el estado del pase sea
ACTIVEy que la hora actual sea anterior aexpirationDate. -
3
Si es válido, la base de datos pasa atómicamente el estado del pase a
VOIDED, asignavoidReason: "SCANNED_AT_CHECKOUT"y registra la transacción de escaneo. -
4
Si un operador o un actor malintencionado intenta escanear el mismo código de barras otra vez, el motor de validación rechaza la transacción de inmediato con el código de decisión
ALREADY_VOIDEDy el mensaje de errorPASS_VOIDED_AFTER_SCAN. -
5
Al mismo tiempo, Passinstance encola una notificación push en segundo plano hacia Apple APNs y Google Wallet. El pase en el teléfono del cliente se muestra inmediatamente en gris con la marca visible "Redeemed" / "Canjeado", impidiendo su reutilización en otra caja.
DTO concretos de solicitud y respuesta de escaneo
Los sistemas de punto de venta, terminales de escaneo y cajas de comercio electrónico interactúan con el endpoint de validación:
Solicitud HTTP
/api/v1/scans
{
"scannedBarcodeValue": "PI-CPN-849201",
"operatorId": "emp_sarah_m"
}
Respuesta HTTP (200 OK)
{
"decision": "SUCCESS",
"status": "ACCEPTED",
"passSnapshot": {
"id": "pass_cpn_849201",
"templateId": "tmpl_coupon_7712",
"serialNumber": "PI-CPN-849201",
"status": "VOIDED",
"attributes": {
"discount": "25% OFF",
"terms": "Valid on purchases over €50"
}
}
}
Salvaguardas de distribución de campañas
Al distribuir cupones a través de páginas públicas de PassFlow, creación por API o campañas por SMS:
-
Caducidad de descarga (
enableDownloadUntil): Defina una fecha y hora límite estricta ("YYYY-MM-DD HH:mm"o marca temporal ISO enrequest payloado configuración de plantilla) tras la cual los enlaces no reclamados devuelven HTTP 410 Gone. -
Protección con PIN de acceso: Proteja enlaces promocionales de alto valor con un PIN de acceso (
?pin=oX-Wallet-Experience-Pin) enviado por SMS o en el recibo de compra. -
Correlación con CRM y comercio electrónico (
externalId): Envíe unexternalId(por ejemplo,order_88412_cpn) enPOST /api/v1/passeso/api/v1/passes/upsert-by-external-idpara conciliar con precisión los canjes de vales de un solo uso en su sistema de pedidos. -
Vinculación de enlace a un único dispositivo: Active
limitToOneActivePerPasspara que el enlace de descarga serializado de cada cliente quede bloqueado en el primer dispositivo registrado en lugar de circular en grupos públicos.
Importante:
VOIDED_AFTER_SCAN scan modeanula el pase inmediatamente tras un escaneo válido, mientras queINVALIDATE_AFTER_SCAN scan modeestablece el estado enINACTIVE/REDEEMED. Verifique siempre quéScanModese ajusta a sus requisitos contables y de visualización en el monedero.
Descubra más en nuestra Descripción general de cupones y vales.
