🎯 Katero — suivi d'affiliation et conversions

1. Le principe en trois minutes

Vous êtes affilié à une plateforme externe (1win, un casino, une boutique…). Vous voulez savoir lequel de vos utilisateurs Telegram s'est inscrit ou a déposé, pour lui verser un bonus.

1. Votre bot envoie un bouton à Marie (ID Telegram 5551234)
   → le lien contient son identifiant, signé

2. Marie tape le bouton
   → Katero enregistre le clic, puis la redirige vers 1win
   → l'URL finale devient : https://1win.com/...?sub1=5551234

3. Marie s'inscrit et dépose 50 $
   → 1win appelle votre URL de postback

4. Katero enregistre la conversion, puis :
   → incrémente la propriété que vous avez choisie
   → EXÉCUTE VOTRE COMMANDE pour Marie

5. Votre commande fait le reste — c'est vous qui codez

2. Créer une campagne

Dans l'application, ouvrez votre bot, puis l'onglet Katero et touchez Nouvelle campagne.

La variable {user.id}

Elle s'écrit directement dans l'URL, à l'endroit que vous voulez, et autant de fois que nécessaire. Katero la remplace par l'identifiant Telegram au moment du clic :

Vous écrivez  https://one-vv4734.life/?open=deposit&p=nwnh&sub1={user.id}
Marie obtient https://one-vv4734.life/?open=deposit&p=nwnh&sub1=5551234

3. Envoyer le lien depuis votre bot

Copier// Commande : /jouer
const lien = await Katero.getLink("1win Dépôt");

Bot.sendMessage("🎁 Inscris-toi et reçois ton bonus !", {
  inline_keyboard: [[
    { text: "S'inscrire maintenant", url: lien }
  ]]
});

Copier# Commande : /jouer
lien = Katero.getLink("1win Dépôt")

bot.sendMessage("🎁 Inscris-toi et reçois ton bonus !", {
    "inline_keyboard": [[
        {"text": "S'inscrire maintenant", "url": lien}
    ]]
})

4. Configurer le postback chez le partenaire

Dans l'onglet Katero, touchez URL de postback pour la copier :

https://mykatero.botstrike.net/webhook/katero/Ax7Kp2mQr9?secret=VOTRE_SECRET

Collez-la dans le panneau de votre partenaire, section Postback / S2S / Callback, en ajoutant les paramètres qu'il propose :

https://mykatero.botstrike.net/webhook/katero/Ax7Kp2mQr9?secret=VOTRE_SECRET&sub1={sub1}&amount={amount}&trans_id={transaction_id}

5. Quand le partenaire nomme ses champs autrement

Chaque plateforme choisit ses propres noms. On ne peut pas les deviner — mais on peut regarder ce qu'elle envoie vraiment.

Le journal des postbacks

Menu de la campagne → Postbacks reçus. Tout ce qui arrive y est enregistré tel quel, même ce que Katero n'a pas su interpréter :

⚠️ non exploité                                    13/08 14:22
player_ref=6425138885   cash_in=50   ref_op=A7X92   currency=USD

Raison : aucun champ identifiant reconnu

Il ne reste qu'à désigner, dans trois menus déroulants, quel champ correspond à quoi. Les vraies valeurs sont affichées sous chacun : vous reconnaissez au lieu de deviner.

Le déroulé recommandé

Le partenaire fait toujours un test avant de tout brancher. Profitez-en :

1. Créez la campagne, copiez l'URL de postback
2. Collez-la chez le partenaire, déclenchez son test
3. Revenez dans « Postbacks reçus » → le postback est là,
   avec ses vrais noms de champs
4. Vérifiez les trois menus (souvent déjà remplis)
5. C'est opérationnel

6. Votre commande, exécutée à la conversion

C'est le cœur de Katero. Quand le partenaire confirme, le serveur incrémente la propriété puis exécute la commande que vous avez choisie, pour cet utilisateur précis — exactement comme s'il l'avait tapée lui-même.

Le vocabulaire est fixe quel que soit le partenaire. C'est la correspondance des champs qui absorbe la différence :

1win envoie      sub1        amount      trans_id
autre société    click_id    payout      conversion_id
une troisième    player_ref  cash_in     ref_op
        │            │           │            │
        └────────────┴───────────┴────────────┘
                     ▼  la correspondance traduit

Votre code voit TOUJOURS :
        Katero.id    Katero.amount   Katero.transaction

Copier// Commande /bonus — choisie dans la campagne
if (!Katero.isConversion()) {
  Bot.sendMessage("Cette commande est déclenchée automatiquement.");
} else {
  const solde = User.getProp(Katero.propertyName) || 0;

  Bot.sendMessage(
    `🎉 Ton dépôt de ${Katero.amount} est confirmé !\n` +
    `Solde : ${solde}`
  );

  // Un champ hors du vocabulaire fixe
  const devise = Katero.raw("currency");
  if (devise === "USD") Bot.sendMessage("Paiement en dollars 💵");
}

Copier# Commande /bonus — choisie dans la campagne
if not Katero.isConversion():
    bot.sendMessage("Cette commande est déclenchée automatiquement.")
else:
    solde = bot.getUserProp(Katero.property_name) or 0

    bot.sendMessage(
        f"🎉 Ton dépôt de {Katero.amount} est confirmé !\n"
        f"Solde : {solde}"
    )

    # Un champ hors du vocabulaire fixe
    devise = Katero.raw("currency")
    if devise == "USD":
        bot.sendMessage("Paiement en dollars 💵")

7. Référence — objet Katero

Données de la conversion en cours

Propriétés — sans parenthèses, sans await.

Méthodes

⏳ = asynchrone en JavaScript, await obligatoire.

8. Limites selon votre plan

9. Questions de sécurité

À quoi sert le secret du postback ?

Sans lui, n'importe qui connaissant l'adresse de votre webhook pourrait déclarer de fausses conversions — et déclencher vos crédits de solde à volonté. Le secret est unique par campagne et vérifié à chaque appel, par une comparaison à temps constant qui empêche de le deviner caractère par caractère.

Mon secret a fuité, que faire ?

Menu de la campagne → Régénérer le secret. L'ancienne URL cesse aussitôt de fonctionner. Pensez à coller la nouvelle chez votre partenaire, sinon les conversions ne remonteront plus.

Quelqu'un peut-il gonfler mes statistiques ?

Non. L'identifiant Telegram placé dans le lien est accompagné d'une signature calculée par le serveur. Un lien fabriqué à la main sera bien redirigé, mais le clic ne sera pas compté.

Le secret apparaît-il dans le journal des postbacks ?

Non. Il est retiré avant l'enregistrement. Et les appels présentant un mauvais secret ne sont pas journalisés du tout : sinon n'importe qui pourrait noyer votre journal de diagnostic.

Pourquoi ne puis-je pas changer l'URL de destination dans le lien ?

L'adresse de destination est lue uniquement en base de données, jamais depuis le lien. Si elle pouvait être passée en paramètre, le domaine botstrike.net deviendrait un tremplin vers n'importe quel site — une aubaine pour l'hameçonnage, et une mise en liste noire assurée pour le domaine.

Pourquoi certaines URL sont-elles refusées à la création ?

Seules http:// et https:// sont acceptées. Les schémas javascript: et data:, ainsi que les adresses internes (127.0.0.1, 192.168.x.x…), sont bloqués. Et l'URL doit contenir {user.id}.

Le partenaire réessaie en boucle, est-ce grave ?

Non. Le numéro de transaction garantit qu'un même événement n'est enregistré qu'une seule fois. Les tentatives suivantes reçoivent 200 avec "duplicate": true, ce qui arrête proprement la boucle sans rien compter en double. La propriété n'est pas recréditée non plus.

Et si le partenaire n'envoie pas de numéro de transaction ?

Katero en fabrique un à partir du contenu du postback. Deux appels rigoureusement identiques seront donc détectés comme doublons. C'est moins fiable qu'un vrai identifiant : demandez-en un à votre partenaire si possible.