Installez l’application Vivoldi sur Google Play pour que ce soit encore plus pratique.

API de réduction de tampons (v2)

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.

PUT

/api/stamp/v2/remove 

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

Request Parameters

stampIdx integer required
Stamp IDX.
stamps integer
Nombre de tampons à ajouter (ou à retirer). Valeur par défaut : 1, doit être supérieure à 0.
Les quantités dépassant le maximum de la carte ou inférieures à zéro sont ajustées par le serveur. Si la variation réelle est nulle, aucun historique ni webhook n'est créé.
processStoreIdx integer
IDX du magasin où cette requête est réellement traitée. S'il est envoyé, le serveur vérifie l'appartenance à l'organisation, l'état actif et les autorisations avant de l'enregistrer dans l'historique de traitement.
L'agence de traitement n'est pas reçue dans la requête ; le serveur la déduit de ce magasin. Cette valeur diffère du magasin émetteur (storeIdx). 
{
    "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é.

Indiquer le magasin de traitement

Paramètre Signification Description
processStoreIdx Magasin de traitement Le magasin où cette requête est réellement traitée. Facultatif : s'il est envoyé, le serveur vérifie l'appartenance à l'organisation, l'état actif et les autorisations avant de l'enregistrer dans l'historique.

L'agence de traitement n'est pas reçue dans la requête. Le serveur la déduit du magasin indiqué et l'enregistre.

Si la portée d'utilisation est BRANCH, le traitement n'a lieu que si l'agence du magasin vérifié correspond à l'agence d'utilisation, ou si vous vous authentifiez avec le mot de passe sur place de cette agence. Sans l'un ou l'autre, la requête est refusée.

Paramètres non utilisables — branchIdx (agence émettrice), storeIdx (magasin émetteur), useScope (portée d'utilisation) et useBranchIdx (agence d'utilisation) relèvent de la politique d'émission déjà enregistrée et ne peuvent pas être modifiés via cette API. S'ils sont envoyés, la réponse est 400 (code d'erreur 1227).

Idempotency-Key

Pour réessayer en toute sécurité lorsqu'une réponse est perdue à cause d'une erreur réseau, envoyez une valeur unique par requête dans l'en-tête Idempotency-Key. Vous pouvez aussi l'envoyer via requestId dans le corps ; si les deux sont envoyés avec des valeurs différentes, la requête est refusée. Le format autorisé est de 8 à 64 caractères composés de lettres, de chiffres et de . _ : -.

Si vous renvoyez la même requête avec la même clé, le résultat initial est renvoyé sans nouveau traitement. Rien n'est traité deux fois et les webhooks ne sont pas renvoyés.

N'utilisez la même clé que pour les nouvelles tentatives d'une même opération logique. Pour une opération différente, utilisez toujours une nouvelle clé. Réutiliser la même clé avec un contenu différent ou pour une autre opération peut être refusé avec 409.

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.

  1. Add Stamp → Enregistre les actions utilisateur dans le flux normal
  2. 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