API para canjear cupones online

API Version

PUT

/api/coupon/v2/redeem

Request
Response

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

Request Parameters

cpnNo string required: Número de cupón.
onsiteToken string: Token de intercambio de corta duración. v2 no acepta la contraseña en texto plano (onsitePwd).
Cuando el recurso tiene onsiteYn = Y, envíe tal cual el onsiteToken devuelto por la API de validación.
Idempotency-Key es obligatorio en las solicitudes que usan token. Un reintento con la misma clave reproduce el resultado original; usar el mismo token con otra clave se rechaza con 400 (código de error 1228).
Si se indicó una tienda de procesamiento en la validación, esta solicitud debe usar la misma tienda.
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.
processStoreIdx integer: IDX de la tienda donde se procesa realmente esta solicitud. Al enviarlo, el servidor verifica la propiedad de la organización, el estado activo y los permisos antes de registrarlo en el historial de procesamiento.
La sucursal de procesamiento no se recibe en la solicitud; el servidor la deduce de esta tienda. Es distinto de la tienda emisora (storeIdx).

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

Especificar la tienda de procesamiento

Parámetro	Significado	Descripción
`processStoreIdx`	Tienda de procesamiento	La tienda donde se procesa realmente esta solicitud. Es opcional; al enviarla, el servidor verifica la propiedad de la organización, el estado activo y los permisos antes de registrarla en el historial.

La sucursal de procesamiento no se recibe en la solicitud. El servidor la deduce de la tienda indicada y la registra.

Si el ámbito de uso es BRANCH, solo se procesa cuando la sucursal de la tienda verificada coincide con la sucursal de uso, o cuando se autentica con la contraseña presencial de esa sucursal. Sin ninguna de las dos, se rechaza.

Parámetros que no se pueden usar — branchIdx (sucursal emisora), storeIdx (tienda emisora), useScope (ámbito de uso) y useBranchIdx (sucursal de uso) son política de emisión ya guardada y no se pueden cambiar con esta API. Si se envían, se devuelve 400 (código de error 1227).

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.

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.

Token de verificación en tienda (onsiteToken)

v2 no acepta la contraseña de tienda en texto plano (onsitePwd). Envía sin modificar el onsiteToken devuelto por la API de validación. Enviar onsitePwd por separado o junto con onsiteToken se rechaza con 400 (código de error 1227).

Idempotency-Key es obligatorio en las solicitudes que utilizan un token. Reintentar con la misma Idempotency-Key devuelve el resultado original. Reutilizar el mismo token con otra Idempotency-Key se rechaza con 400 (código de error 1228).

La tienda utilizada para la validación debe ser la misma en la que se procesa la operación. Si se indicó processStoreIdx durante la validación, esta solicitud debe utilizar la misma tienda. No se puede asociar posteriormente una tienda a un token validado sin tienda.

Los tokens caducados, manipulados, ya utilizados o con una vinculación incorrecta devuelven todos 1228. Los motivos no se diferencian de forma intencionada para evitar que terceros puedan sondear el estado interno utilizando otro token.

No se requiere ningún token para recursos que no utilizan verificación en tienda (onsiteYn = N). v1 sigue aceptando onsitePwd en texto plano.

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.

API de uso de cupones (Redeem) (v2)