Developer API

Crear cupón

Esta API permite crear cupones de descuento.
Para crear varios cupones a la vez, debes usar el panel de control.

La API no permite subir imágenes de cupones.
Si necesitas imágenes, primero crea un grupo de cupones en el panel y sube la imagen allí, luego especifica el grupo al crear el cupón.

Al especificar un grupo de cupones, algunos ajustes del cupón serán ignorados y se aplicarán los ajustes del grupo.

Esta API está disponible a partir del plan Personal.

Http Header

POST /api/coupon/v1/create
Host: https://vivoldi.com
Authorization: APIKey {Your API Key}
Content-type: application/json
User-agent: {Your User-agent}
Accept-Language: en

Request

{
	"cpnNo": "",  // You can specify a coupon code manually. If left empty, a 16-character code will be generated automatically by the system.
	"grpIdx": 271,
	"tmplIdx": 0,
	"nm": "$5 discount coupon",
	"discTypeIdx": 458,
	"disc": 5,
	"strtYmd": "2025-01-01",
	"endYmd": "2025-12-31",
	"onsiteYn": "Y",
	"onsitePwd": "123456",
	"memo": "New Member Registration, IP: 211.111.222.33",
	"url": "https://bestshop.com",
	"useLimit": 1,
	"userId": "att78z",
	"userNm": "Brown Smith",
	"userPhnno": "+1 123-4567-8900",
	"userEml": "",
	"userEtc1": "Gold rating",
	"userEtc2": ""
}

Campos	Descripción de los campos	Descripción	Tipo
cpnNo	Número de cupón	Un número de cupón de 8 a 16 dígitos compuesto por letras mayúsculas y números. No se permiten caracteres especiales. Si el valor está vacío, el número de cupón se genera automáticamente por el sistema.	string
grpIdx	Grupo de cupón	Los grupos de cupones permiten categorizar y administrar los cupones. Si hay un ajuste de grupo y de cupón al mismo tiempo, prevalece el ajuste del cupón. Puedes ver el IDX de grupo en la página de grupos de cupones de tu panel. Valor por defecto: 0	int
tmplIdx	Plantilla de cupón	Las plantillas de cupón describen para qué sirve el cupón, cómo usarlo y cualquier condición. Puedes ver el IDX de la plantilla en la página de plantillas de cupones del panel. Valor por defecto: 0	int
nm	Nombre del cupón	El nombre del cupón aparece en la página del cupón.	string
discTypeIdx	Tipo de descuento	Establece el tipo de descuento (porcentaje o cantidad). 457: Descuento por porcentaje (%), 458: Descuento por cantidad Descuento por porcentaje: Aplica un descuento en porcentaje al cupón. Descuento por cantidad: Aplica un descuento por monto fijo.	int
disc	Valor del descuento	Introduce un valor entre 1% y 100% si el descuento es por porcentaje (457). Introduce el monto si el descuento es por cantidad (458).	double
discCurrency	Moneda del descuento	Puedes definir la moneda si el descuento es por cantidad (458). KRW, CAD, CNY, EUR, GBP, IDR, JPY, MUR, RUB, SGD, USD Valor por defecto: KRW	string
strtYmd	Fecha de inicio de validez	Indica la fecha desde la cual el cupón es válido. Valor de 10 dígitos en formato aaaa-mm-dd. Ejemplo: 2024-10-01	date
endYmd	Fecha de vencimiento	Indica la fecha hasta la cual el cupón es válido. Valor de 10 dígitos en formato aaaa-mm-dd. Ejemplo: 2024-12-31	date
onsiteYn	Cupón presencial	Si el valor es Y, la página del cupón muestra un botón para canjearlo presencialmente. El usuario debe mostrar el cupón al personal de tienda para canjearlo. Útil para tiendas físicas. Valor por defecto: N	Y o N
onsitePwd	Contraseña de canje presencial	Si defines una contraseña, el personal deberá ingresarla para canjear el cupón. El usuario no puede canjear el cupón por sí mismo.	string
memo	Notas	Se puede usar para la gestión interna de cupones. No es visible para los usuarios.	string
url	URL	Si introduces una URL, la página del cupón mostrará un botón “Canjear cupón” que dirige a esa URL. Si se sube una imagen del cupón, al hacer clic en la imagen también se accede a la URL.	string
useLimit	Límite máximo de canjes por persona	Establece el número máximo de veces que un cupón puede ser canjeado por una persona. Para la API de Vivoldi, debes definir un rango entre 2 y 5, junto con el ID de usuario. Al gestionar manualmente desde el panel, puedes elegir “Ilimitado” o “1 vez”. Si eliges “Ilimitado”, cualquiera puede canjear el cupón sin límite. 0: Ilimitado, 1: 1 vez, 2: 2 veces, 3: 3 veces, 4: 4 veces, 5: 5 veces	int
color	Color del texto	Establece el color del texto del cupón en la página. Se debe ingresar un valor HEX de hasta 9 dígitos (con transparencia). Valor por defecto: #4F4F4FFF	string
background	Color de fondo	En la página de cupones, define el color de fondo del cupón. Se debe ingresar un valor HEX de hasta 9 dígitos (con transparencia). Valor por defecto: #FFFFFFFF	string
userId	ID de usuario	Se usa para saber quién emitió y canjeó el cupón. Si el límite de canjes por persona es entre 2 y 5, debes ingresar el ID de usuario. Por lo general, es el ID de usuario que se registró en tu web.	string
userNm	Nombre de usuario	Si ya sabes a quién quieres entregar el cupón, introduce el nombre del usuario. Esto ayuda a gestionar la emisión y el canje.	string
userPhnno	Contacto del usuario	Define el número de contacto del usuario que canjeará el cupón.	string
userEml	Email del usuario	Define el correo electrónico del usuario que canjeará el cupón.	string
userEtc1	Otra información del usuario 1	Define información adicional del usuario para fines internos.	string
userEtc2	Otra información del usuario 2	Define información adicional del usuario para fines internos.	string

Response

{
	"code": 0,
	"message": "",
	"result": "ZJLF0399WQBEQZJM"
}

Campos	Descripción	Tipo
code	Código de respuesta (0:Éxito)	int
message	El mensaje de respuesta, o un mensaje relacionado si el código de respuesta es distinto de cero.	string
result	Valor de la respuesta (número de cupón)	string