API de canje de recompensas de sellos

La API de canje de recompensas de sellos marca una recompensa (bebida gratis, descuento, etc.) como utilizada cuando se completan todos los sellos.

Una vez canjeada, la tarjeta ya no puede utilizarse y el usuario debe recibir una nueva para iniciar un nuevo ciclo.
Se utiliza en sistemas de recompensas basados en visitas o compras.

Esta API está disponible a partir del plan Personal.

PUT

/api/stamp/v1/redeem 

{
    "stampIdx": 394,
    "onsitePwd": "12345"
}

Request Parameters

stampIdx integer required
Stamp IDX.
onsitePwd string
Contraseña de autenticación del empleado usada para sellos en tienda.
Solo es obligatoria cuando el sello tiene onsiteYn = Y,
y debe ingresarse al aprobar la recompensa del cliente (p. ej., bebida gratis).
Consulte el valor onsitePwd devuelto por la Validate API. 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer
Código de respuesta: 0 = Éxito, otros valores = Error
message string
Mensaje de respuesta. Si el código no es 0, se devuelve un mensaje de error.
result null

¿En qué etapa se utiliza?

Es la etapa final del sistema de sellos.

  • Verificar que la acumulación esté completa
  • Procesar la entrega de la recompensa
  • Marcar el sello como utilizado

No es solo un cambio de estado, sino la confirmación final del resultado del evento.

Punto final del ciclo

Esta API representa el último paso del ciclo de sellos.

Para el usuario, es el momento de recibir la recompensa. Para el desarrollador, marca el cierre de un ciclo y el inicio del siguiente.

Llamar a Create después de Redeem ayuda a mantener el engagement continuo.

Ciclo completo

  1. Create → Emitir sello
  2. Add Stamp → Acumular sellos
  3. Validate → Verificar completado
  4. Redeem → Canjear recompensa
  5. Create → Iniciar nuevo ciclo

Gestión de sellos en tienda

onsitePwd solo es necesario cuando el sello tiene configurada una contraseña de validación en tienda (onsiteYn = Y).

El personal introduce este valor al aprobar el canje para evitar usos no autorizados.

Utiliza el valor onsitePwd obtenido desde la API de validación.
Si no hay contraseña configurada, este campo puede omitirse.

Flujo de automatización tras el canje

Puedes automatizar acciones cuando la recompensa se marca como utilizada.

  • Llamar a la API de creación de cupones para emitir recompensas al instante
  • Crear un nuevo sello para iniciar el siguiente ciclo
  • Usar webhooks para notificar al usuario

Este flujo permite automatizar todo el ciclo de recompensas sin intervención manual.

Puntos clave en operación

Esta API no es solo una función, sino el punto donde se define el resultado del negocio.

  • Un manejo incorrecto puede generar recompensas duplicadas
  • Posibles reclamaciones o disputas de usuarios

Es esencial garantizar el flujo validación → canje, el control transaccional en el servidor y la auditoría de registros.