API de creación de cupones online

La API de creación de cupones de Vivoldi le permite generar cupones de descuento de forma programática.

Puede elegir entre descuentos porcentuales (%) o de importe fijo, y configurar opciones como fecha de expiración, límite de uso, grupo y plantilla directamente en la solicitud.

Para crear cupones en lote, utilice el panel de control.
Si necesita imágenes, primero cree un grupo de cupones y cargue las imágenes en el panel, luego genere los cupones utilizando ese grupo.

Esta API está disponible a partir del plan Personal.

POST

/api/coupon/v1/create 

{
    "cpnNo": "",
    "cpnNoDigits": 12,
    "domain": "https://vvd.bz",
    "webhookEnableYn": N",
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5,
    "discCurrency": "USD",
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "useLimit": 1,
    "grpIdx": 271,
    "tmplIdx": 0,
    "onsiteYn": "Y",
    "onsitePwd": "123456",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "url": "https://bestshop.com",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cpnNostring
Número de cupón. Entre 8 y 16 caracteres alfanuméricos. Si no se especifica, el sistema lo genera automáticamente. No se permiten caracteres especiales.
Ejemplo: V5H8GR5T
cpnNoDigits integer
Default:16
Enum:
16128
Longitud del código de cupón.
Si no se especifica, se utilizará la longitud predeterminada (16).
Solo se aplica cuando no se proporciona un código. El sistema generará uno automáticamente con la longitud seleccionada.
domain string
Predeterminado:https://vvd.bz
Dominio del cupón.
Si se deja vacío, se guardará con el dominio predeterminado.
Disponible en planes Premium y superiores: puede especificar un dominio personalizado registrado en la Gestión de Dominios de Enlaces.
webhookEnableYn string
Enum:
YN
Activación del Webhook.
El Webhook global debe estar habilitado.
Esta función solo está disponible en el plan Enterprise.
nmstringrequired
Nombre del cupón.
discTypeIdxintegerrequired
Tipo de descuento. (457: Porcentaje %, 458: Monto fijo)
discdoublerequired
Para porcentaje (457): rango de 1 a 100%. Para monto fijo (458): ingresar la cantidad.
discCurrencystring
Unidad de moneda. Obligatorio cuando se usa descuento por monto fijo (discTypeIdx:458).
strtYmddaterequired
Fecha de inicio de validez del cupón. Ejemplo: 2024-10-01
endYmddaterequired
Fecha de expiración del cupón. Ejemplo: 2024-12-31
La fecha de vencimiento solo se puede establecer hasta el 31 de diciembre del año siguiente.
useLimitintegerrequired
Límite de uso del cupón. (0: Ilimitado, 1–5: Número de usos)
Si se establece en 2 o más, es obligatorio especificar userId.
grpIdxinteger
Grupo de cupones. Se utiliza para gestionar cupones por grupos. El IDX del grupo se puede consultar en el panel de control.
Si hay configuraciones duplicadas entre grupo y cupón, prevalece la del grupo.
tmplIdxinteger
Plantilla de cupón. Se utiliza como referencia al crear un cupón. El IDX de la plantilla se puede consultar en el panel.
onsiteYnstring
Indicador de cupón presencial. Muestra el botón “Usar cupón” en la página del cupón.
Necesario para que el personal en tienda valide el cupón.
onsitePwdstring
Contraseña del cupón presencial. Obligatoria al usar el cupón.
memostring
Nota interna de referencia.
urlstring
Si se introduce una URL, se mostrará un botón “Ir a usar cupón” en la página del cupón.
Al hacer clic en el botón o en la imagen se redirige a esa URL.
colorstring
Color del texto del cupón. Ingresar valor HEX. Ejemplo: #4F4F4F
backgroundstring
Color de fondo del cupón. Ingresar valor HEX. Ejemplo: #FFFFFF
userIdstring
Se utiliza para gestionar al destinatario del cupón.
Obligatorio si el límite de uso está entre 2 y 5. Normalmente es el ID de inicio de sesión o nombre del usuario.
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 para gestión interna.
userEtc2string
Campo adicional para gestión interna. 
{
    "code": 0,
    "message": "",
    "result": "ZJLF0399WQBEQZJM"
}

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 string
Valor de respuesta. Se devuelve el número de cupón generado.
Ejemplo: ZJLF0399WQBEQZJM

Cuándo usar esta API

Utilice esta API cuando necesite generar cupones automáticamente en promociones, eventos o campañas de adquisición de usuarios.

Se adapta a múltiples escenarios de marketing, como incentivos de registro, descuentos personalizados y aumento de conversiones desde tráfico publicitario.

Configuración del formato del código de cupón

El código de cupón se controla mediante los parámetros cpNo y cpNoDigits.
Si se especifica cpNo, ese valor se utiliza directamente como código. Si no, el sistema lo genera automáticamente.

En la generación automática, puede definir la longitud con cpNoDigits (valor predeterminado: 16).
Ajuste la longitud según el uso: códigos más largos reducen el riesgo de colisión, mientras que los más cortos facilitan la introducción.

Integración de datos de usuario

Para asignar un cupón a un usuario específico, establezca el parámetro userId.

Para asociar cupones a múltiples usuarios, utilice los campos userEml·userPhone·userEtc1·userEtc2 en conjunto.
Estos datos se utilizan en el panel para identificar y filtrar a los propietarios de cupones, siendo útiles en servicios B2C que requieren identificación de usuarios.

Casos de uso

  • Recompensas automáticas por registro: Llama a la API al registrar un usuario para generar y entregar un cupón personalizado al instante
  • Promociones por tiempo limitado: Define fechas de inicio y fin para emitir cupones válidos solo durante un período específico
  • Seguimiento de conversiones: Vincula cupones a enlaces publicitarios para rastrear clic → canje → compra
  • Segmentación de usuarios: Ofrece descuentos personalizados basados en correo electrónico o ID de usuario
  • Cupones en tienda física: Configura onsiteYn en Y para que el personal valide el cupón con contraseña

Aspectos a tener en cuenta

  • Para crear cupones con imágenes, primero crea un grupo de cupones y sube las imágenes en el panel, luego especifica el ID del grupo en grpIdx antes de llamar a la API.
  • Para recibir webhooks, establece webhookEnablYn en Y y registra previamente la URL en el panel.
  • Si useLimit es ilimitado, el cupón no se marcará como usado aunque haya sido canjeado.
  • En cupones para tienda física, asegúrate de gestionar correctamente la contraseña de validación.