API para reducir sellos (v1)

La API para reducir sellos decrementa en uno el número de sellos de un registro existente.

No forma parte del flujo normal, sino que se utiliza para corregir acumulaciones incorrectas, actualizar reglas de campañas o gestionar reclamaciones.
El número de sellos nunca será inferior a cero.

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/remove

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.

Cuándo usar la deducción de sellos

Esta API no está diseñada para uso frecuente, sino como una herramienta administrativa para resolver problemas.
Se utiliza en los siguientes casos:

Procesamiento duplicado de eventos que genera sellos duplicados
Errores del sistema que incrementan sellos incorrectamente
Cambios en reglas de campaña que requieren ajustar datos existentes
Necesidad de revertir acumulaciones incorrectas

Dejar datos incorrectos sin corregir puede aumentar costos y reducir la confianza.
La API de deducción permite corregirlos de forma inmediata.

Relación con la API Add Stamp

Ambas APIs funcionan en direcciones opuestas, pero con roles claramente definidos.

Add Stamp → Registra acciones del usuario en el flujo normal
Remove Stamp → Corrige o revierte datos en casos excepcionales

En cada uso de Add Stamp API, deben contemplarse cancelaciones y fallos,
e integrar Remove Stamp como parte del flujo para asegurar la estabilidad del sistema.

Puntos clave en operación

La API de deducción de sellos no se utiliza con frecuencia, sino que es una API administrativa clave para resolver problemas de datos.

Datos incorrectos sin corregir reducen la confianza
La sobreacumulación incrementa los costos de recompensas
Puede afectar negativamente la experiencia del usuario

Utilízala junto con logs de auditoría y control de acceso administrativo estricto.

Aspectos a tener en cuenta

El número de sellos no baja de 0. Verifica stamps con la API de validación antes de descontar
Llamadas repetidas pueden causar deducciones excesivas
No la invoques directamente desde el cliente; controla su uso en el servidor
Registra el historial de deducciones y protégelo con control de acceso