API de creación de sellos online

API Version

POST

/api/stamp/v2/create

Request
Response

{
    "cardIdx": 123,
    "storeIdx": 22,
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "activeYn": "Y",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cardIdx integer required: Card IDX.
El Card IDX puede consultarse en la página “Tarjeta de Sellos” del panel de control.
strtYmd date required: Fecha de inicio de validez del sello. Ejemplo: 2025-01-01
endYmd date required: Fecha de expiración del sello. Ejemplo: 2025-12-31
La fecha de expiración puede configurarse hasta 5 años a partir de hoy.
activeYn string
Default:Y
Enum: YN: Estado de activación del sello.
Si está desactivado, los clientes no podrán usar el sello.
memo string: Nota interna de referencia.
userId string: ID de usuario.
Se utiliza para gestionar el destinatario de la emisión del sello.
Normalmente, introduce el ID de inicio de sesión de un miembro del sitio web.
Si no se especifica, el sistema generará automáticamente un ID de usuario.
userNm string: Nombre del usuario. Solo para uso interno.
userPhnno string: Número de contacto del usuario. Solo para uso interno.
userEml string: Correo electrónico del usuario. Solo para uso interno.
userEtc1 string: Campo adicional para gestión interna.
userEtc2 string: Campo adicional para gestión interna.
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.

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

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 integer: Valor de respuesta. Se devolverá el Stamp IDX generado.
Ejemplo: 1347

Validación de parámetros numéricos

Si un parámetro numérico recibe un valor no numérico o un número fuera del rango que el servidor puede procesar, la solicitud se rechaza de inmediato con 400 (código de error 653).

En ese caso, los datos del sello y el historial de acumulación no cambian en absoluto, y no se genera ningún registro de evento ni envío de Webhook. Si recibe una respuesta de error, no se guardó nada.

Sucursal emisora, tienda emisora y ámbito de uso

La sucursal emisora, el ámbito de uso y la sucursal de uso siguen los valores definidos en la tarjeta de sellos. Solo cuando la tarjeta deja vacía la tienda emisora puede elegirla directamente con storeIdx. Enviar un valor distinto al de la tarjeta devuelve 400 (código de error 1221).

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

Utiliza esta API para crear campañas basadas en sellos y sistemas de recompensas.

Campañas de recompensas basadas en visitas
Programas de acumulación de sellos en tiendas físicas
Sistemas de verificación de actividad de usuarios
Registro de acciones específicas (compras, participación, etc.)

Ideal para registrar acciones de los usuarios y convertirlas en recompensas.

Relación entre tarjetas de sellos y sellos

La tarjeta de sellos define las reglas y el diseño de la campaña, mientras que los sellos son las unidades que se entregan a los usuarios.

Al llamar a la API de creación, utiliza cardIdx para indicar en qué tarjeta se emitirá el sello.

El Card IDX está disponible en el panel. Cada tarjeta tiene condiciones y recompensas distintas, por lo que es importante seleccionar la correcta.

Estructura y componentes de creación de sellos

Un sello no es solo un dato, sino una unidad que representa la actividad del usuario.

Componentes clave:

Identificador de tarjeta (cardIdx) : ID de la tarjeta a la que pertenece el sello
Periodo de validez (strtYmd, endYmd) : Intervalo en el que el sello es válido
Estado (activeYn) : Indica si el sello está activo y disponible
Información del usuario (userId, userNm, userEmail, etc.) : Usuario objetivo
Campos adicionales (memo, userEtc1, userEtc2) : Datos personalizados

Permite un seguimiento y gestión personalizados de la actividad del usuario.

Integración de datos de usuario

El campo userId permite identificar y gestionar al destinatario del sello.

Normalmente se utiliza el ID de usuario del sistema propio. Si no se proporciona, el sistema lo generará automáticamente.

Al incluir userNm, userPhnno y userEml, puedes almacenar datos de contacto y gestionar la actividad de sellos por usuario desde el panel.

Casos de uso

Sello de bienvenida al registrarse: Emite automáticamente un sello al completar el registro llamando a la API
Recompensas automáticas por compra: Llama a la API tras el pago para asignar sellos según el número de compras
Campañas por tiempo limitado: Emite sellos válidos solo dentro de un periodo definido usando strtYmd·endYmd
Seguimiento de participación en eventos: Genera sellos al participar para registrar el historial
Gestión de campañas de recompensas: Otorga cupones o beneficios según los sellos acumulados

Diferencia con la API de cupones

Tanto la API de cupones como la API de sellos se utilizan en marketing, pero cumplen funciones y flujos distintos.

La API de cupones está orientada a la conversión, impulsando compras inmediatas mediante descuentos.
La API de sellos se centra en la retención, registrando el comportamiento del usuario y fomentando la participación recurrente.

1. Propósito

API de cupones → Descuentos → Impulsar compras (Conversión)
API de sellos → Registro de actividad → Fomentar el regreso (Retención)

Los cupones son eficaces para ingresos a corto plazo, mientras que los sellos impulsan la retención a largo plazo.

2. Momento de uso

Cupón → Antes o durante el pago
Sello → Cuando ocurre una acción (visita, participación, etc.)

El cupón incentiva la compra inmediata, mientras que el sello promueve la siguiente acción.

3. Estructura de datos

Los cupones son eventos puntuales.

Uso único o limitado
Basado en descuento
Se consume o cambia de estado al usarse

Los sellos son acumulativos.

Se pueden emitir repetidamente
Seguimiento por usuario
Recompensas al cumplir condiciones

En resumen, los cupones son disparadores únicos y los sellos son datos acumulativos.

4. Estrategia de marketing

Estrategia con cupones:

Captación de nuevos usuarios
Aumento de conversiones
Promoción de productos

Estrategia con sellos:

Fidelización
Repetición de visitas
Campañas a largo plazo

5. Uso combinado

En la práctica, ambas APIs suelen utilizarse juntas.

Ejemplo:

Acumulación de sellos (10 visitas)
Emisión automática de cupón al cumplir condiciones
Uso del cupón para impulsar la compra

Esto conecta Participación → Retención → Conversión en un solo flujo.

Aspectos a tener en cuenta

cardIdx debe corresponder a un ID de tarjeta válido
Define una política clara para evitar duplicados por usuario
Una configuración incorrecta del periodo puede afectar la campaña

API de creación de sellos (v2)