Instale la aplicación Vivoldi desde Google Play para que le resulte aún más cómodo.

API de canje de recompensas de sellos (v1)

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.

Documentación v1 (Legacy).

Para nuevas integraciones, recomendamos utilizar la versión más reciente, v2.
v1 está destinada al mantenimiento de integraciones existentes y no recibe nuevas funciones ni mejoras.

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

Validación de parámetros numéricos

Si un parámetro numérico recibe un valor no numérico o un número fuera del rango que el servidor puede procesar, la solicitud se rechaza de inmediato con 400 (código de error 653).

En ese caso, los datos del sello y el historial de acumulación no cambian en absoluto, y no se genera ningún registro de evento ni envío de Webhook. Si recibe una respuesta de error, no se guardó nada.

Cambio de comportamiento. Antes, v1 seguía procesando la solicitud aunque esta validación fallara. Por eso el error podía quedar sustituido por el mensaje de otro parámetro, o parte de los datos del sello podía guardarse realmente aunque la respuesta indicara error. Ahora se detiene con 400 antes de procesar, igual que la versión más reciente.

¿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.