API de réduction de tampons (v1)

L’API de réduction de tampons diminue de un le nombre de tampons d’un enregistrement existant.

Elle n’est pas utilisée dans le flux normal, mais pour des corrections telles que les erreurs d’accumulation, les modifications de règles de campagne ou la gestion des réclamations.
Le nombre de tampons ne descend jamais en dessous de zéro.

Cette API est disponible à partir de l’offre Personal.

Documentation v1 (Legacy).

Pour les nouvelles intégrations, nous recommandons d’utiliser la version la plus récente, v2.
v1 est destinée à la maintenance des intégrations existantes et ne reçoit aucune nouvelle fonctionnalité ni amélioration.

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: Code de réponse : 0 = Succès, autres valeurs = Erreur
message string: Message de réponse. Si le code n’est pas 0, un message d’erreur est renvoyé.
result null

Validation des paramètres numériques

Si un paramètre numérique reçoit une valeur non numérique ou un nombre dépassant la plage que le serveur peut traiter, la requête est immédiatement refusée avec 400 (code d'erreur 653).

Dans ce cas, les données du tampon et l'historique de cumul ne changent pas du tout, et aucun enregistrement d'événement ni envoi de Webhook n'est produit. Une réponse en échec signifie que rien n'a été enregistré.

Changement de comportement. Auparavant, v1 poursuivait le traitement de la requête même lorsque cette validation échouait. L'erreur pouvait alors être remplacée par le message d'un autre paramètre, ou une partie des données du tampon était réellement enregistrée alors que la réponse signalait une erreur. Le traitement s'arrête désormais avec 400 avant traitement, comme dans la dernière version.

Quand utiliser la déduction de tampons

Cette API n’est pas destinée à un usage fréquent, mais sert d’outil pour corriger des problèmes de données.
Elle est utilisée dans les cas suivants :

Traitement en double entraînant une accumulation incorrecte
Erreurs système provoquant une augmentation incorrecte des tampons
Modification des règles nécessitant un ajustement des données
Annulation d’accumulations incorrectes

Laisser ces erreurs augmente les coûts et réduit la confiance.
Cette API permet une correction immédiate.

Relation avec l’API Add Stamp

Les deux APIs fonctionnent en sens opposé, avec des rôles clairement définis.

Add Stamp → Enregistre les actions utilisateur dans le flux normal
Remove Stamp → Corrige ou annule les données en cas exceptionnel

Chaque utilisation de Add Stamp API doit inclure des scénarios d’échec et d’annulation,
et intégrer Remove Stamp pour garantir la stabilité du système.

Points clés en opération

L’API de réduction des tampons n’est pas utilisée fréquemment, mais constitue une API essentielle pour résoudre les problèmes de données.

Des données incorrectes non corrigées réduisent la confiance
L’accumulation excessive augmente les coûts de récompense
Peut dégrader l’expérience utilisateur

Utilisez-la avec journalisation d’audit et contrôle d’accès administrateur strict.

Points à considérer

Le nombre de tampons ne descend pas sous 0. Vérifiez stamps via l’API de validation avant réduction
Des appels répétés peuvent entraîner une réduction excessive
Évitez les appels directs côté client; contrôlez via le serveur
Enregistrez l’historique et protégez-le avec des droits administrateur