API de canje de recompensas de sellos (v2)
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.
/api/stamp/v2/redeem
{
"stampIdx": 394,
"onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
"processStoreIdx": 22
}Request Parameters
- stampIdx integer required
- Stamp IDX.
- onsiteToken string
-
Token de intercambio de corta duración. v2 no acepta la contraseña en texto plano
(
onsitePwd).
Cuando el recurso tieneonsiteYn = Y, envíe tal cual elonsiteTokendevuelto por la API de validación.
Idempotency-Keyes obligatorio en las solicitudes que usan token. Un reintento con la misma clave reproduce el resultado original; usar el mismo token con otra clave se rechaza con400(código de error1228).
Si se indicó una tienda de procesamiento en la validación, esta solicitud debe usar la misma tienda. - processStoreIdx integer
-
IDX de la tienda donde se procesa realmente esta solicitud. Al enviarlo, el servidor verifica la propiedad de la organización, el estado activo y los permisos antes de registrarlo en el historial de procesamiento.
La sucursal de procesamiento no se recibe en la solicitud; el servidor la deduce de esta tienda. Es distinto de la tienda emisora (storeIdx).
{
"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.
Especificar la tienda de procesamiento
| Parámetro | Significado | Descripción |
|---|---|---|
processStoreIdx |
Tienda de procesamiento | La tienda donde se procesa realmente esta solicitud. Es opcional; al enviarla, el servidor verifica la propiedad de la organización, el estado activo y los permisos antes de registrarla en el historial. |
La sucursal de procesamiento no se recibe en la solicitud. El servidor la deduce de la tienda indicada y la registra.
Si el ámbito de uso es BRANCH, solo se procesa cuando la sucursal de la tienda verificada coincide con la sucursal de uso,
o cuando se autentica con la contraseña presencial de esa sucursal. Sin ninguna de las dos, se rechaza.
Parámetros que no se pueden usar — branchIdx (sucursal emisora),
storeIdx (tienda emisora), useScope (ámbito de uso) y
useBranchIdx (sucursal de uso) son política de emisión ya guardada y no se pueden cambiar con esta API.
Si se envían, se devuelve 400 (código de error 1227).
Idempotency-Key
Para reintentar con seguridad cuando se pierde una respuesta por un error de red, envíe un valor único por solicitud
en la cabecera Idempotency-Key. También puede enviarlo como requestId en el cuerpo;
si envía ambos con valores distintos, la solicitud se rechaza.
El formato permitido es de 8 a 64 caracteres con letras, dígitos y . _ : -.
Si vuelve a enviar la misma solicitud con la misma clave, se devuelve el resultado original sin volver a procesarla. Nada se procesa dos veces y los webhooks no se reenvían.
Use la misma clave solo para reintentos de la misma operación lógica.
Para una operación distinta, use siempre una clave nueva.
Usar la misma clave con otro contenido o para otra operación puede rechazarse con 409.
¿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
Create→ Emitir selloAdd Stamp→ Acumular sellosValidate→ Verificar completadoRedeem→ Canjear recompensaCreate→ Iniciar nuevo ciclo
Token de verificación en tienda (onsiteToken)
v2 no acepta la contraseña de tienda en texto plano (onsitePwd).
Envía sin modificar el onsiteToken devuelto por la API de validación.
Enviar onsitePwd por separado o junto con onsiteToken se rechaza con
400 (código de error 1227).
Idempotency-Key es obligatorio en las solicitudes que utilizan un token.
Reintentar con la misma Idempotency-Key devuelve el resultado original.
Reutilizar el mismo token con otra Idempotency-Key se rechaza con
400 (código de error 1228).
La tienda utilizada para la validación debe ser la misma en la que se procesa la operación.
Si se indicó processStoreIdx durante la validación, esta solicitud debe utilizar la misma tienda.
No se puede asociar posteriormente una tienda a un token validado sin tienda.
Los tokens caducados, manipulados, ya utilizados o con una vinculación incorrecta devuelven todos 1228.
Los motivos no se diferencian de forma intencionada para evitar que terceros puedan sondear el estado interno utilizando otro token.
No se requiere ningún token para recursos que no utilizan verificación en tienda (onsiteYn = N).
v1 sigue aceptando onsitePwd en texto plano.
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.