API para añadir sellos (v2)

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.

API Version

PUT

/api/stamp/v2/add

Request
Response

{
    "stampIdx": 394,
    "stamps": 1,
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required: Stamp IDX.
stamps integer: Número de sellos que se van a acumular (o descontar). Por defecto es 1 y debe ser mayor que 0.
El servidor ajusta las cantidades que superan el máximo de la tarjeta o que quedan por debajo de cero. Si el cambio real es 0, no se crea historial ni webhook.
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

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.

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.

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.