API de creación de cupones online (v2)

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.

API Version

POST

/api/coupon/v2/create

Request
Response

{
    "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",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11,
    "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.
branchIdx integer: IDX de la sucursal emisora. Si se omite, se emite desde la oficina central; envíe 0 para vaciarlo.
Disponible en el plan Business o superior.
storeIdx integer: IDX de la tienda emisora. Si se especifica, la sucursal a la que pertenece la tienda pasa a ser la sucursal emisora. Enviar otra sucursal genera un error.
useScope string: Ámbito de uso. Solo se permite ALL (todas las tiendas) o BRANCH (una sucursal concreta). Si se omite, es ALL.
useBranchIdx integer: IDX de la sucursal de uso. Solo es necesario cuando useScope = BRANCH; siempre está vacío con ALL.

{
    "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

Sucursal emisora, tienda emisora y ámbito de uso

Los valores que se indican aquí son la política que se guarda en el momento de la emisión. "Dónde se emitió" (sucursal emisora, tienda emisora) y "dónde puede usarlo el cliente" (ámbito de uso, sucursal de uso) son conceptos distintos, por eso los parámetros están separados.

Parámetro	Significado	Descripción
`branchIdx`	Sucursal emisora	Si se omite, emite la oficina central. Envíe `0` para vaciarlo a la oficina central.
`storeIdx`	Tienda emisora	Si se indica, la sucursal a la que pertenece la tienda pasa a ser la emisora. Enviar otra sucursal se rechaza.
`useScope`	Ámbito de uso	`ALL` (todas las tiendas) o `BRANCH` (una sucursal). Por defecto, `ALL`.
`useBranchIdx`	Sucursal de uso	Solo es necesario con `useScope=BRANCH`. Siempre vacío con `ALL`.

Parámetros que no se pueden usar — processStoreIdx (tienda de procesamiento) indica la tienda donde ocurrió realmente la validación, el uso, la acumulación o el descuento, por lo que no se puede usar en esta API. Si se envía, se devuelve 400 (código de error 1227).

Las funciones de sucursal y tienda solo están disponibles en el plan Business o superior.

Idempotency-Key

Para reintentar con seguridad cuando se pierde una respuesta por un error de red, envíe un valor único por solicitud en la cabecera Idempotency-Key. También puede enviarlo como requestId en el cuerpo; si envía ambos con valores distintos, la solicitud se rechaza. El formato permitido es de 8 a 64 caracteres con letras, dígitos y . _ : -.

Si vuelve a enviar la misma solicitud con la misma clave, se devuelve el resultado original sin volver a procesarla. Nada se procesa dos veces y los webhooks no se reenvían.

Use la misma clave solo para reintentos de la misma operación lógica. Para una operación distinta, use siempre una clave nueva. Usar la misma clave con otro contenido o para otra operación puede rechazarse con 409.

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.