API para reducir sellos (v2)

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.

API Version

PUT

/api/stamp/v2/remove

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.

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