API de validación de cupones

La API de validación de cupones de Vivoldi permite verificar si un cupón es válido antes de procesar su uso.

Además de comprobar su disponibilidad, devuelve información de descuento, condiciones de uso y datos del usuario, lo que permite implementar lógica de negocio flexible.

Esta API está disponible a partir del plan Personal.

GET

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


GET /api/coupon/v1/validate
     ?cpnNo=ZJLF0399WQBEQZJM

Request Parameters

cpnNostringrequired
Número de cupón. 
{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake 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",
        "onsitePwd": "12345",
        "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"
    }
}

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.
cpnNostring
Número de cupón.
domain string
Dominio del cupón.
nmstring
Nombre del cupón.
discTypeIdxinteger
Tipo de descuento. (457: porcentaje %, 458: descuento en importe)
discdouble
Para porcentaje (457): rango 1–100%. Para importe (458): introducir el valor monetario.
discCurrencystring
Moneda. Obligatorio al usar descuento por importe (discTypeIdx:458).
formatDiscCurrencystring
Símbolo de moneda.
strtYmddate
Fecha de inicio de validez del cupón.
endYmddate
Fecha de expiración del cupón.
useLimitinteger
Límite de uso del cupón. (0: ilimitado, 1–5: número máximo de usos)
imgUrlstring
URL de la imagen del cupón.
onsiteYnstring
Cupón en tienda. Indica si se muestra el botón «Usar cupón» en la página del cupón.
Necesario cuando el cupón se valida en tiendas físicas.
onsitePwd string
Contraseña del cupón en tienda.
Obligatoria al llamar a la API de uso de cupones si el cupón en tienda está habilitado (Y).
memostring
Nota de referencia interna.
urlstring
Al introducir una URL, se muestra el botón «Ir a usar el cupón» en la página del cupón.
Al hacer clic en el botón o en la imagen del cupón, se redirige a dicha URL.
userIdstring
Se utiliza para gestionar el destinatario del cupón.
Obligatorio si el límite de uso está configurado entre 2 y 5.
Normalmente se introduce el ID de inicio de sesión del sitio web o el nombre en inglés.
userNmstring
Nombre del usuario del cupón. Uso interno.
userPhnnostring
Teléfono del usuario del cupón. Uso interno.
userEmlstring
Correo electrónico del usuario del cupón. Uso interno.
userEtc1string
Campo adicional de gestión interna.
userEtc2string
Campo adicional de gestión interna.
useCntinteger
Número de usos del cupón.
regYmdtdatetime
Fecha de creación del cupón. Ejemplo: 2025-07-21 11:50:20

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