API de actualización de cupones (v2)

La API de actualización de cupones permite modificar los datos de cupones ya emitidos.

Usando el código de cupón (cpNo) como identificador, puede actualizar el tipo de descuento, la fecha de expiración, los límites de uso, el grupo y la información del usuario.
Algunos campos no pueden modificarse una vez que el cupón ha sido canjeado.

Esta API está disponible a partir del plan Personal.

API Version

PUT

/api/coupon/v2/update

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "nm": "$10 discount coupon",
    "disc": 10,
    "endYmd": "2025-12-31",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

cpnNostringrequired: Número de cupón.
domain string: Dominio del cupón.
Disponible en planes Premium y superiores: puede especificar un dominio personalizado.
webhookEnableYn string
Enum: YN: Activación del Webhook.
El Webhook global debe estar habilitado.
Esta función solo está disponible en el plan Enterprise.
nmstring: Nombre del cupón.
discTypeIdxinteger: Tipo de descuento. (457: Porcentaje %, 458: Descuento fijo)
discdouble: Para porcentaje (457): rango de 1 a 100%. Para descuento fijo (458): ingresar monto.
discCurrencystring: Moneda. Obligatorio al usar descuento fijo (discTypeIdx:458).
strtYmddate: Fecha de inicio de validez del cupón. Ejemplo: 2024-10-01
endYmddate: Fecha de vencimiento del cupón. Ejemplo: 2024-12-31
La fecha de vencimiento solo se puede establecer hasta el 31 de diciembre del año siguiente.
useLimitinteger: Límite de uso del cupón. (0: Ilimitado, 1–5: Número de usos)
Si se establece en 2 o más, el valor userId debe especificarse.
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": 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

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 modificar las condiciones de cupones ya emitidos.

Es útil para gestionar campañas activas, como extender periodos promocionales, ajustar descuentos o añadir restricciones por usuario.

Dado que el código del cupón no cambia, puede actualizar sus condiciones sin necesidad de volver a emitir ni retirar los cupones ya distribuidos.

Cómo extender la expiración

Para extender la fecha de expiración, establezca un nuevo valor en el parámetro endYmd.
Los cupones expirados pueden reactivarse al actualizar la fecha a un valor futuro. Utilice el formato YYYY-MM-DD.

Casos de uso

Extender promociones: Actualice endYmd para ampliar la validez de una campaña activa
Ajustar configuraciones de descuento: Modifique disc según cambios en la estrategia
Aumentar límites de uso: Incremente useLimit para permitir usos repetidos en clientes VIP
Reasignar grupos: Cambie grpIdx para mover el cupón a otro grupo y aplicar nuevas configuraciones
Segmentación de usuarios: Ofrezca descuentos personalizados según email o ID de usuario
Actualizar landing page: Cambie la URL del cupón a otra página promocional

Aspectos a tener en cuenta

Si cpNo (código de cupón) no es válido, la actualización fallará.
Algunos campos pueden estar restringidos si el cupón ya ha sido utilizado.
Modificar el descuento puede afectar la experiencia del usuario.
Los cupones expirados pueden no activarse inmediatamente tras la actualización.
En cupones de tienda física, actualice la contraseña cuando cambie el personal.