API para validar cupones online

API Version

GET

/api/coupon/v2/validate?cpnNo={cpnNo}

Request
Response


GET /api/coupon/v2/validate
     ?cpnNo=ZJLF0399WQBEQZJM
     &processStoreIdx=22

Request Parameters

cpnNostringrequired: Número de cupón.
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": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "grpIdx": 271,
        "grpNm": "Birthday coupon",
        "discTypeIdx": 457,
        "discCurrency": "USD",
        "formatDiscCurrency": "$60",
        "disc": 60.0,
        "strtYmd": "2025-01-01",
        "endYmd": "2025-12-31",
        "useLimit": 1,
        "imgUrl": "https://file.vivoldi.com/coupon/2024/11/08/lmTFkqLQdCzeBuPdONKG.webp",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": "60% off cake with coupon at the venue",
        "url": "",
        "userId": "user08",
        "userNm": "Emily",
        "userPhnno": "202-555-0173",
        "userEml": "test@gmail.com",
        "userEtc1": "",
        "userEtc2": "",
        "useCnt": 0,
        "regYmdt": "2024-11-17 17:29:25",
        "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: Validación exitosa: La respuesta devuelve la información del cupón.
Validación fallida: La respuesta es null y se puede verificar mediante el mensaje de error.

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.

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

¿Qué se puede determinar con el resultado de validación?

Esta API va más allá de una simple verificación de “válido / no válido”.
Está diseñada para que los desarrolladores construyan lógica personalizada basada en datos detallados del cupón.

Con la respuesta (result), puede determinar:

Si se puede aplicar un descuento y calcular su importe
Si el cupón está restringido a usuarios específicos (userId, userEml)
Si se han superado los límites de uso (useCnt, useLimit)
Si el cupón está expirado o aún no es válido (strtYmd, endYmd)
Si se cumplen condiciones específicas (online/offline, etc.) (onsiteYn)
La URL de destino tras aplicar el cupón (url)

En otras palabras, no es solo un resultado,
sino una API orientada a datos para lógica flexible a nivel de aplicación.

Método de validación

La validación se realiza en base al código de cupón (cpNo) considerando múltiples criterios.

Existencia
Periodo de validez
Límites de uso
Condiciones de usuario
Entorno aplicable

El resultado se devuelve como datos estructurados, no como un simple valor booleano.

Cómo utilizar los datos de respuesta

El objeto result contiene toda la información esencial del cupón.

Los desarrolladores pueden usar estos datos para:

Calcular y mostrar descuentos en tiempo real en el frontend
Restringir el uso del cupón a usuarios específicos
Aplicar lógica condicional según el importe del pago
Mostrar mensajes UI según el estado del cupón (expirado, utilizado, etc.)

Casos de uso

Validación previa al pago: Validar el cupón antes de aplicarlo y usarlo solo si es válido
Mensajes al usuario: Mostrar mensajes según el resultado (expirado o ya utilizado)
Cálculo del descuento: Usar (disc, discType) para calcular el importe final

El mismo código puede reutilizarse para crear un nuevo cupón tras su eliminación.

Aspectos a tener en cuenta

El resultado de validación refleja el estado en el momento de la consulta y puede cambiar antes de su uso.
Implemente siempre el flujo: validación → uso (Redeem).
Confiar únicamente en la validación del cliente supone un riesgo de seguridad.
Vuelva a validar el cálculo del descuento en el servidor para mayor precisión y seguridad.

API de validación de cupones (v2)