API de actualización de sellos online

API Version

PUT

/api/stamp/v2/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

stampIdx integer required: Stamp IDX.
cardIdx integer: Card IDX.
El Card IDX puede consultarse en la página «Tarjeta de Sellos» del panel de control.
stamps integer: Especifica el número de sellos acumulados.
Representa el total de sellos que el cliente ha reunido. Al modificar este valor, se actualizará el progreso de sellos y se puede aumentar o disminuir.
Cuando se completan todos los sellos (stamps = número máximo de sellos en la tarjeta), debes establecer useYn en Y para marcar el sello como canjeado.
resetPinYn string
Default:N
Enum: YN: Indica si se debe restablecer el PIN del cliente para el sello.
Y: Restablece el PIN establecido por el cliente. Después del restablecimiento, el cliente deberá definir un nuevo PIN al volver a acceder a la página del sello.
N: Mantiene el PIN actual sin cambios.
useYn string
Default:N
Enum: YN: Indica si el cliente ha utilizado la recompensa del sello.
Y: El cliente ha reunido todos los sellos y ha canjeado una recompensa (por ejemplo, bebida gratis, descuento, etc.). Después del canje, el sello se desactiva y se debe emitir uno nuevo.
N: La recompensa aún no ha sido utilizada.
Al cambiar de N a Y, el número de sellos guardado debe haber alcanzado el máximo de la tarjeta y, si el sello tiene contraseña en tienda, debe enviarse también onsiteToken.
onsiteToken string: Token de intercambio de corta duración. v2 no acepta la contraseña en texto plano (onsitePwd).
Cuando el recurso tiene onsiteYn = Y, envíe tal cual el onsiteToken devuelto por la API de validación.
Idempotency-Key es 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 con 400 (código de error 1228).
Si se indicó una tienda de procesamiento en la validación, esta solicitud debe usar la misma tienda.
domain string
Default:https://vvd.bz: Dominio del sello.
Si está vacío, se utilizará el dominio predeterminado.
Disponible para planes Premium o superiores — puedes especificar un dominio personalizado registrado en la sección de Gestión de Dominios de Enlaces.
strtYmd date: Fecha de inicio de validez del sello. Ejemplo: 2025-01-01
endYmd date: Fecha de caducidad del sello. Ejemplo: 2025-12-31
La fecha de caducidad puede configurarse hasta 5 años desde la fecha actual.
activeYn string
Default:Y
Enum: YN: Estado de activación del sello. Si está desactivado, los clientes no podrán usar el sello.
memo string: Nota interna de referencia.
userId string: ID del usuario. Se utiliza para gestionar al destinatario del sello.
Normalmente, introduce el ID de inicio de sesión del miembro del sitio web.
Si no se especifica, el sistema generará automáticamente un ID de usuario.
userNm string: Nombre del usuario. Solo para uso interno.
userPhnno string: Número de contacto del usuario. Solo para uso interno.
userEml string: Correo electrónico del usuario. Solo para uso interno.
userEtc1 string: Campo adicional para gestión interna.
userEtc2 string: Campo adicional para gestión interna.
branchIdx integer: IDX de la sucursal emisora. Si se omite, se emite desde la oficina central; envíe 0 para vaciarlo.
Disponible en el plan Business o superior.
storeIdx integer: IDX de la tienda emisora. Si se especifica, la sucursal a la que pertenece la tienda pasa a ser la sucursal emisora. Enviar otra sucursal genera un error.
useScope string: Ámbito de uso. Solo se permite ALL (todas las tiendas) o BRANCH (una sucursal concreta). Si se omite, es ALL.
useBranchIdx integer: IDX de la sucursal de uso. Solo es necesario cuando useScope = BRANCH; siempre está vacío con ALL.

{
    "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.

Sucursal emisora, tienda emisora y ámbito de uso

Los valores que se indican aquí son la política que se guarda en el momento de la emisión. "Dónde se emitió" (sucursal emisora, tienda emisora) y "dónde puede usarlo el cliente" (ámbito de uso, sucursal de uso) son conceptos distintos, por eso los parámetros están separados.

Parámetro	Significado	Descripción
`branchIdx`	Sucursal emisora	Si se omite, emite la oficina central. Envíe `0` para vaciarlo a la oficina central.
`storeIdx`	Tienda emisora	Si se indica, la sucursal a la que pertenece la tienda pasa a ser la emisora. Enviar otra sucursal se rechaza.
`useScope`	Ámbito de uso	`ALL` (todas las tiendas) o `BRANCH` (una sucursal). Por defecto, `ALL`.
`useBranchIdx`	Sucursal de uso	Solo es necesario con `useScope=BRANCH`. Siempre vacío con `ALL`.

Parámetros que no se pueden usar — processStoreIdx (tienda de procesamiento) indica la tienda donde ocurrió realmente la validación, el uso, la acumulación o el descuento, por lo que no se puede usar en esta API. Si se envía, se devuelve 400 (código de error 1227).

Las funciones de sucursal y tienda solo están disponibles en el plan Business o superior.

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.

Por qué es necesario controlar directamente la cantidad de sellos

Al operar un sistema de sellos, hay situaciones en las que necesitas ajustar manualmente la cantidad, más allá de la acumulación automática.

Casos comunes incluyen corregir errores de asignación, otorgar sellos adicionales en campañas y ajustes manuales por administradores.

Al configurar el parámetro stamps, puedes aumentar o reducir el valor actual sin sobrescribirlo.
Sin embargo, cuando se alcanza el máximo configurado, debes establecer useYn en Y para procesar el canje de la recompensa.

Flujo de uso de recompensas y reemisión de sellos

Al establecer useYn en Y, el sello se marca como utilizado.

Después del canje, se debe emitir un nuevo sello mediante la API de creación para reiniciar la acumulación.
Este flujo representa el ciclo central de los programas de recompensas basados en sellos.
Automatizar Uso → Nueva emisión → Reacumulación impulsa la participación recurrente.

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.

Esta API solo utiliza el token cuando se produce una transición real de canje de la recompensa (N → Y). Enviar un token en una actualización normal que solo modifica la nota, el periodo o el estado activo se rechaza con 400 (código de error 1227). Aunque la solicitud incluya useYn = Y, el token no se consume si no se produce una transición real N → Y (por ejemplo, si la recompensa ya se había canjeado).

Esta API no acepta el parámetro de tienda de procesamiento (processStoreIdx). Cuando se canjea una recompensa, la ubicación de procesamiento se obtiene de la tienda vinculada al token durante la validación, no de la solicitud, y se registra en el evento y el Webhook. Esta ubicación no se aplica a las actualizaciones normales.

El mismo token también puede utilizarse con la API de canje de recompensas (Redeem), pero solo puede utilizarse una vez en una de las dos API. Una vez consumido en una de ellas, será rechazado por la otra.

Cuándo restablecer el PIN

Al establecer resetPinYn en Y, se restablece el PIN del usuario.

Se utiliza cuando el usuario olvida su PIN, cambia de dispositivo o por razones de seguridad.

Tras el restablecimiento, el usuario deberá crear un nuevo PIN al acceder a la página de sellos. Si se establece en N o se omite, el PIN actual se mantiene.

Casos de uso

Corrección de errores: Ajustar manualmente sellos asignados incorrectamente
Actualización de campañas: Aplicar cambios de condiciones en campañas activas
Reverificación de usuarios: Restablecer PIN para reconfigurar autenticación offline
Desactivación: Desactivar sellos al finalizar una campaña

Aspectos a tener en cuenta

Asegúrate de que los cambios en stamps sean coherentes con el historial existente
Una vez marcado como usado (useYn), debe considerarse una operación irreversible
Mantén registros operativos y un historial detallado para auditoría y seguimiento

API de actualización de sellos (v2)