API de validación de sellos (v2)

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.

API Version

GET

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

Request
Response


GET /api/stamp/v2/validate
     ?stampIdx=274
     &processStoreIdx=22

Request Parameters

stampIdx integer required: IDX del sello.
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": {
        "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",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "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",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

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.

Token de verificación en tienda (onsiteToken)

La respuesta de la API de validación v2 no incluye la contraseña de tienda en texto plano (onsitePwd). En su lugar, devuelve un onsiteToken válido durante 180 segundos.

El objetivo es minimizar la exposición de la contraseña en texto plano, no reforzar la autenticación. La API de validación no verifica la contraseña, por lo que el token no añade un factor de autenticación adicional. En su lugar, su corta duración, su uso único y la vinculación al contexto limitan su reutilización.

Elemento	Valor
Validez	180 segundos. El periodo de validez también se devuelve en `onsiteTokenExpiresIn`.
Usos	Uno. Una vez consumido, solo los reintentos con la misma `Idempotency-Key` devuelven el resultado original.
Vinculación	Organización, cuenta de la clave de API, recurso, acción y tienda de procesamiento confirmada durante la validación
Se aplica a	Canje de cupones, canje de recompensas de sellos y actualización de sellos con `useYn = Y`

No se emite ningún token para recursos que no utilizan verificación en tienda (onsiteYn = N). La API de validación v1 sigue devolviendo onsitePwd en texto plano.

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

¿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