API de validación de sellos

La API de validación de sellos permite comprobar si un sello está en un estado válido antes de añadir, eliminar o procesar recompensas.

Verifica en una sola solicitud el stamp IDX, el periodo de validez, el estado activo y si la recompensa ya ha sido utilizada.

Además de la validación, devuelve el estado de acumulación y la información de la tarjeta, lo que permite construir la vista de sellos para el usuario.

Esta API está disponible a partir del plan Personal.

GET

/api/stamp/v1/validate?stampIdx={stampIdx} 


GET /api/stamp/v1/validate
     ?stampIdx=274

Request Parameters

stampIdx integer required
IDX del sello. 
{
    "code": 0,
    "message": "",
    "result": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsitePwd": "123456",
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "payloadVersion": "v1"
    }
}

Response Parameters

codeinteger
Código de respuesta: 0 = Éxito, cualquier otro valor = Error
messagestring
Mensaje de respuesta. Si el código no es 0, se devuelve un mensaje relacionado con el error.
resultobject
Si la verificación es exitosa, la respuesta incluirá la información del sello.
Si falla, el valor de la respuesta será null y el mensaje de error mostrará la causa.
stampIdx integer
Stamp IDX.
domain string
Dominio del sello.
cardIdx integer
Card IDX.
cardNm string
Nombre de la tarjeta.
cardTtl string
Título de la tarjeta.
stamps integer
Número de sellos acumulados hasta el momento.
maxStamps integer
Número máximo de sellos permitidos en la tarjeta.
stampUrl string
URL de la página del sello.
url string
URL a la que se redirige al usuario al hacer clic en el botón dentro de la página del sello.
strtYmd date
Fecha de inicio de validez del sello.
endYmd date
Fecha de expiración del sello.
onsiteYn string
Enum:
YN
Indica si la acumulación en tienda está habilitada.
Si el valor es Y, el personal de la tienda puede añadir sellos directamente en el establecimiento.
onsitePwd string
Contraseña de acumulación en tienda.
Obligatoria al usar la API de beneficios si la opción en tienda está activada (Y).
memo string
Nota interna de referencia.
activeYn string
Enum:
YN
Indica si el sello está activo.
Si está desactivado, los clientes no podrán usar el sello.
userId string
ID del usuario. Se usa para administrar el destinatario del sello.
Normalmente corresponde al ID de inicio de sesión del miembro del sitio web.
Si no se establece, el sistema generará automáticamente un ID de usuario.
userNm string
Nombre del usuario. Solo para uso interno.
userPhnno string
Teléfono 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.
stampImgUrl string
URL de la imagen del sello.
regYmdt datetime
Fecha de creación del sello. Ejemplo: 2025-07-21 11:50:20

¿Cuál es el rol de la validación de sellos?

La API de validación de sellos va más allá de una simple verificación.
Permite decidir la siguiente acción según el estado actual de acumulación.

  • Determinar si se pueden emitir más sellos
  • Verificar si se cumplen las condiciones de recompensa
  • Confirmar la participación en campañas
  • Consultar el progreso por usuario

En resumen, es la API clave para interpretar el progreso de una campaña.

Qué puedes determinar con el resultado

La respuesta (result) contiene toda la información necesaria para evaluar el progreso.

Con estos datos puedes:

  • Comparar stamps con maxStamps
  • Determinar si se puede seguir acumulando
  • Verificar si se cumplen las condiciones de recompensa
  • Comprobar el estado (activeYn)
  • Evaluar el contexto de uso (onsiteYn)
  • Aplicar personalización basada en datos del usuario

Clave: “API de validación = estado + entrada para lógica de decisión”

Cómo usar los datos de respuesta

La respuesta de la API de validación se utiliza directamente en la lógica de la aplicación.

Ejemplos:

  • Mostrar progreso: Visualizar el avance en tiempo real en la interfaz
  • Controlar acciones: Activar o desactivar botones según el estado
  • Mostrar recompensas: Presentar beneficios al alcanzar objetivos
  • Gestionar estados: Aplicar lógica según el progreso del usuario

En resumen, esta API es la fuente clave que conecta la UI con la lógica de negocio.

Diferencia con la API de validación de cupones

Ambas APIs devuelven datos de validación, pero el tipo de información es diferente.

La validación de cupones proporciona datos transaccionales como tipo de descuento, valor y límites de uso.
La validación de sellos proporciona datos de progreso como stamps, maxStamps, nombre de la tarjeta, título e imagen.

La validación de cupones se utiliza para calcular “cuánto descuento se aplica ahora”,
mientras que la validación de sellos muestra “cuánto se ha acumulado y cuánto falta”.

Importancia operativa

La API de validación de sellos es el núcleo del flujo de eventos.

  • Evita acumulaciones incorrectas
  • Bloquea acciones cuando no se cumplen las condiciones
  • Mejora la experiencia del usuario
  • Garantiza la estabilidad de la lógica del evento

Omitir la validación puede provocar inconsistencias de datos y errores en el flujo del evento.

Aspectos a tener en cuenta

  • El estado puede cambiar entre la validación y la ejecución real
  • Se recomienda llamar inmediatamente a la API de acumulación tras validar
  • No es recomendable depender únicamente de la validación en el cliente
  • En entornos de alto tráfico, optimiza las llamadas e implementa reintentos en caso de fallo