API de creación de sellos

La API de creación de sellos permite emitir sellos a clientes de forma programática.

Indica el Card IDX y la fecha de expiración para añadir un sello a la tarjeta seleccionada. También puedes guardar información del usuario y notas para gestionar el historial de sellos de cada cliente de forma organizada.
El Card IDX se puede consultar en la página “Tarjetas de Sellos” del panel.

Esta API está disponible desde el plan Personal.

POST

/api/stamp/v1/create 

{
    "cardIdx": 123,  // You can check the IDX value on the card management page of the dashboard.
    "domain": "https://vvd.bz",
    "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.
domain string
Default:https://vvd.bz
Dominio de sellos.
Si se deja vacío, se guardará con el dominio predeterminado.
Disponible en planes Premium o superiores: puedes especificar un dominio personalizado registrado en la sección de Gestión de Dominios de Enlaces.
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. 
{
    "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

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