API de uso de cupones (Redeem)

La API de uso de cupones de Vivoldi (Redeem) permite marcar un cupón emitido como canjeado.

Puede procesar el canje automáticamente mediante API sin necesidad de intervención manual en el panel.
Cada solicitud reduce el número de usos disponibles y, una vez alcanzado el límite, se bloquean usos adicionales.

Esta API está disponible a partir del plan Personal.

PUT

/api/coupon/v1/redeem 

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233"
}

Request Parameters

cpnNo string required
Número de cupón.
onsitePwd string
Contraseña del cupón en sitio. Obligatoria si se ha configurado una contraseña para el cupón en sitio.
userId string
ID de usuario. Identificador del emisor/usuario del cupón.
Debe proporcionarse si el límite de uso del cupón está configurado entre 2–5.
memo string
Nota interna de referencia. Puede usarse para registrar la IP del usuario, el lugar de uso del cupón u otros detalles.
Si el uso del cupón es ilimitado, este campo puede utilizarse en lugar de userId para diferenciar usuarios. 
{
    "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

Cómo usar con la API de validación

Dado que la API de uso cambia el estado del cupón, se recomienda verificar primero su validez mediante la API de validación.

Al confirmar previamente que el cupón es válido, se evitan procesamientos innecesarios de cupones expirados o ya utilizados.

El flujo estándar es: validación → uso.

Cuándo usar esta API

Utilice esta API cuando necesite aplicar un cupón después de validarlo.

  • Marcar el cupón como canjeado tras el pago
  • Registrar el uso del descuento al confirmar un pedido
  • Gestionar el uso en tienda física u offline
  • Actualizar el estado para evitar usos duplicados

En resumen, es la etapa final donde el cupón se consume.

Flujo de uso del cupón

El cupón se marca como canjeado según el código (cpnNo).

  • El número de usos se reduce inmediatamente al canjearlo
  • El cupón pasa a un estado no reutilizable
  • El uso se registra en función de la información del usuario (userId)
  • Se pueden almacenar registros adicionales mediante memo

Este proceso no es solo un cambio de estado, sino una transacción clave vinculada al pago.

Identificación de usuario y uso de memo

El userId se utiliza para identificar al usuario que canjea el cupón.

Si el cupón permite entre 2 y 5 usos, este campo es obligatorio y evita el uso duplicado por el mismo usuario.

El campo memo permite registrar información interna como IP, ubicación o origen de la solicitud.
Si no hay límite de uso, también puede utilizarse en lugar de userId para distinguir usuarios.

Gestión de contraseña en cupones presenciales

El campo onsitePwd es obligatorio cuando el cupón tiene una contraseña configurada.

Se utiliza en entornos físicos donde el personal verifica la contraseña antes de procesar el canje.

Casos de uso

  • Integración en e-commerce: Llamar a la API al completar el pago para aplicar automáticamente el cupón y registrar el descuento
  • Uso en tienda física: El personal escanea el QR, obtiene el código y lo canjea al instante mediante API
  • Seguimiento de uso: Guardar IP y origen en memo para analizar usos indebidos o patrones anómalos
  • Control de uso múltiple: Usar userId para evitar que un mismo usuario supere el límite permitido

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

Aspectos a tener en cuenta

  • Llame a esta API siempre después de la validación para mayor seguridad.
  • Una vez canjeado, el cupón no puede volver a utilizarse.
  • Puede ser necesaria una estrategia de rollback en caso de fallo de pago.
  • Implemente mecanismos para evitar canjes duplicados por solicitudes repetidas.