Skip to content
Guía del Centro de ayuda
4 min de lecturaVerificado 2026-11-16

Cupones y vales

Lanza promociones de un solo uso o limitadas en el tiempo con validación por escaneo y caducidad automática.

En esta guía

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:

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
CANJE Y ANULACIÓN DE CUPÓN
ACTORES DEL SISTEMA
P1 Pase en Wallet cliente
P2 Escáner / Terminal POS
P3 API Central Passinstance
PASO 1 SOLICITUD / ACCIÓN Presentar código QR
›
(PI-CPN-849201)
PASO 2 SOLICITUD / ACCIÓN POST/api/v1/scans
›
Cabecera: x-scanner-key
›
Body: {scannedBarcodeVal}
PASO 3 SOLICITUD / ACCIÓN Verificar status === ACTIVE
PASO 4 SOLICITUD / ACCIÓN Verificar expirationDate >= now()
PASO 5 SOLICITUD / ACCIÓN Actualización atómica:
›
status = VOIDED,
›
oidedAt = now()
PASO 6 RESPUESTA 200 OK
PASO 7 SOLICITUD / ACCIÓN Push APNs y PATCH Google
›
{ decision: "SUCCESS",
›
(Actualización silenciosa)
PASO 8 RESPUESTA Tarjeta atenuada y anulada ==== status: "ACCEPTED" }

Prevención del fraude por captura de pantalla y repetición

Cuando un cajero escanea el código de barras del cupón:

  1. 1
    El escáner envía una solicitud a POST /api/v1/scans con scannedBarcodeValue y la clave secreta del escáner en x-scanner-key.
  2. 2
    El servidor confirma que el estado del pase sea ACTIVE y que la hora actual sea anterior a expirationDate.
  3. 3
    Si es válido, la base de datos pasa atómicamente el estado del pase a VOIDED, asigna voidReason: "SCANNED_AT_CHECKOUT" y registra la transacción de escaneo.
  4. 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_VOIDED y el mensaje de error PASS_VOIDED_AFTER_SCAN.
  5. 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

POST /api/v1/scans
Cabeceras
x-scanner-key sk_live_counter_register_04
Content-Type application/json
JSON
{
  "scannedBarcodeValue": "PI-CPN-849201",
  "operatorId": "emp_sarah_m"
}

Respuesta HTTP (200 OK)

JSON
{
  "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 en request payload o 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= o X-Wallet-Experience-Pin) enviado por SMS o en el recibo de compra.
  • Correlación con CRM y comercio electrónico (externalId): Envíe un externalId (por ejemplo, order_88412_cpn) en POST /api/v1/passes o /api/v1/passes/upsert-by-external-id para 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 limitToOneActivePerPass para 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 mode anula el pase inmediatamente tras un escaneo válido, mientras que INVALIDATE_AFTER_SCAN scan mode establece el estado en INACTIVE / REDEEMED. Verifique siempre qué ScanMode se ajusta a sus requisitos contables y de visualización en el monedero.

Descubra más en nuestra Descripción general de cupones y vales.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.