API de actualización de sellos

La API de actualización de sellos permite modificar los datos de sellos ya emitidos.

Además de cambios básicos, puedes ajustar la cantidad de sellos, procesar el canje de recompensas y restablecer PINs, con control directo sobre el estado acumulado del usuario.

Esta API está disponible desde el plan Personal.

PUT

/api/stamp/v1/update 

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "resetPinYn": "Y",
    "userEml": "example@gmail.com"
}

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

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.

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