API para añadir sellos (v1)

La API para añadir sellos incrementa en uno el número de sellos de un registro existente.

Cuando un usuario completa una compra, visita o acción específica, esta API añade automáticamente un sello.
No se añadirán más sellos si se alcanza el máximo definido en la tarjeta.

Esta API está disponible a partir del plan Personal.

Documentación v1 (Legacy).

Para nuevas integraciones, recomendamos utilizar la versión más reciente, v2.
v1 está destinada al mantenimiento de integraciones existentes y no recibe nuevas funciones ni mejoras.

API Version

PUT

/api/stamp/v1/add

Request
Response

{
    "stampIdx": 394
}

Request Parameters

stampIdx integer required: Stamp IDX.

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

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.

Cambio de comportamiento. Antes, v1 seguía procesando la solicitud aunque esta validación fallara. Por eso el error podía quedar sustituido por el mensaje de otro parámetro, o parte de los datos del sello podía guardarse realmente aunque la respuesta indicara error. Ahora se detiene con 400 antes de procesar, igual que la versión más reciente.

Por qué esta API es clave en el sistema de sellos

Mientras que la API de creación emite la tarjeta, la API de añadir sellos registra las acciones reales del usuario.

Cada vez que un usuario realiza una compra o visita, esta API registra la acción y permite crear un sistema de recompensas basado en comportamiento sin necesidad de puntos.

Pagos, compras o encuestas pueden vincularse a la acumulación con una sola llamada API.

Manejo al alcanzar el máximo

Cuando se alcanza el máximo de sellos, no se añadirán más.
Flujo recomendado:

Validar stamps y maxStamps
Si son iguales, el sello está completo
Usar Update API con useYn en Y
Llamar Stamp Create API para iniciar un nuevo ciclo
Continuar con un nuevo proceso de acumulación

Condiciones y restricciones de acumulación

La acumulación de sellos no se aplica automáticamente en todos los casos.

Deben cumplirse las siguientes condiciones:

El sello está activo (activeYn = Y)
Dentro del periodo válido (strtYmd ~ endYmd)
No se ha alcanzado el máximo (stamps < maxStamps)
No ha sido utilizado previamente

Estas condiciones garantizan una acumulación precisa según las reglas del evento.

Casos de uso

Eventos por visita: Añadir un sello al visitar una tienda
Recompensas por compra: Añadir un sello automáticamente tras el pago
Eventos por misión: Otorgar sellos al completar acciones específicas
Check-in diario: Añadir un sello por cada inicio de sesión

Puntos clave en operación

La API de acumulación de sellos es un componente clave que impacta directamente la calidad de la campaña.

Acumulaciones incorrectas reducen la confianza en la campaña
Llamadas duplicadas a la API pueden provocar acumulación excesiva
Impacta directamente en la experiencia del usuario

Debe utilizarse siempre junto con validación y control lógico en el servidor.