Points de terminaison de l'API

Points de terminaison de l'API de parrainage

Si vous préférez le suivi des parrainages côté serveur (ou en avez besoin pour des intégrations backend uniquement), vous pouvez appeler ces points de terminaison directement au lieu d'utiliser le script de suivi JavaScript.

Tous les points de terminaison de parrainage prennent en charge CORS et ne nécessitent pas d'authentification par clé API.

Campagnes de parrainage vs campagnes d'affiliation : Les campagnes de parrainage attribuent des points lors des inscriptions et des achats. Les campagnes d'affiliation attribuent une commission en dollars sur les achats référés en utilisant une structure de paiement exclusive — soit un pourcentage de la vente, soit un tarif fixe par vente (pas les deux). Le suivi des inscriptions ne paie pas de commission sur les campagnes d'affiliation (uniquement sur les achats). Les réponses aux achats incluent pointsAwarded pour le mode parrainage et commissionAwarded pour le mode affiliation.

Valider un code de parrainage

GET/api/referral/validate-code

No authentication required

Vérifiez si un code de parrainage est valide et récupérez des informations sur le parrain.

Paramètres de requête

codestring required

Le code de parrainage à valider

contestIdstring required

L'identifiant du concours

Requête

bash

curl -X GET "https://blitzrocket.com/api/referral/validate-code?code=REF-XYZ789&contestId=clx1abc123"

javascript

const params = new URLSearchParams({
  code: "REF-XYZ789",
  contestId: "clx1abc123",
});

const response = await fetch(
  `https://blitzrocket.com/api/referral/validate-code?${params}`
);

const data = await response.json();
if (data.valid) {
  console.log(`Parrainé par : ${data.referrerName || data.referrerEmail}`);
}

python

import requests

response = requests.get(
    "https://blitzrocket.com/api/referral/validate-code",
    params={
        "code": "REF-XYZ789",
        "contestId": "clx1abc123"
    }
)

data = response.json()
if data.get("valid"):
    print(f"Parrainé par : {data.get('referrerName') or data.get('referrerEmail')}")

Réponse

json

{
  "valid": true,
  "referrerEmail": "jane@example.com",
  "referrerName": "Jane Doe",
  "contestId": "clx1abc123"
}

Suivre une visite

POST/api/referral/track-visit

No authentication required

Enregistrez qu'une personne a visité votre site via un lien de parrainage.

Corps de la requête

referralCodestring required

Le code de parrainage provenant de l'URL

contestIdstring required

L'identifiant du concours

urlstring

L'URL de la page visitée (optionnel)

Requête

bash

curl -X POST https://blitzrocket.com/api/referral/track-visit \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "REF-XYZ789",
    "contestId": "clx1abc123",
    "url": "https://yoursite.com/landing-page"
  }'

javascript

await fetch("https://blitzrocket.com/api/referral/track-visit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    referralCode: "REF-XYZ789",
    contestId: "clx1abc123",
    url: window.location.href,
  }),
});

python

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-visit",
    json={
        "referralCode": "REF-XYZ789",
        "contestId": "clx1abc123",
        "url": "https://yoursite.com/landing-page"
    }
)

Réponse

json

{
  "success": true
}

Suivre une inscription

POST/api/referral/track-signup

No authentication required

Enregistrez qu'un visiteur parrainé s'est inscrit.

Corps de la requête

emailstring required

Adresse e-mail du nouvel inscrit

contestIdstring required

L'identifiant du concours

referralCodestring

Le code de parrainage de la personne qui l'a parrainé (optionnel pour les inscriptions directes)

externalSiteUrlstring required

URL de la page où l'inscription a eu lieu

namestring

Nom du nouvel inscrit (optionnel)

Requête

bash

curl -X POST https://blitzrocket.com/api/referral/track-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "externalSiteUrl": "https://yoursite.com/signup"
  }'

javascript

await fetch("https://blitzrocket.com/api/referral/track-signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "newuser@example.com",
    contestId: "clx1abc123",
    referralCode: "REF-XYZ789",
    name: "New User",
  }),
});

python

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-signup",
    json={
        "email": "newuser@example.com",
        "contestId": "clx1abc123",
        "referralCode": "REF-XYZ789",
        "name": "New User"
    }
)

Réponse

json

{
  "success": true,
  "data": {
    "entryId": "entry_new789",
    "isReferred": true,
    "pointsAwarded": {
      "advocate": 10,
      "friend": 5
    }
  }
}

Suivre un achat

POST/api/referral/track-purchase

No authentication required

Enregistrer qu’un utilisateur référé a effectué un achat. Utilisé par RocketTracker.trackPurchase() dans blitzrocket.js.

Corps de la requête

campaignIdstring required

L’identifiant du concours (identique à contestId)

referralCodestring required

Le code de parrainage de l’ambassadeur

orderIdstring required

Identifiant unique de la commande

amountnumber required

Montant de l’achat

externalSiteUrlstring required

URL de la page où l’achat a eu lieu

emailstring

Adresse email de l’acheteur (optionnel)

phonestring

Téléphone de l’acheteur (optionnel)

currencystring

Code de la devise (par défaut : 'USD')

Requête

bash

curl -X POST https://blitzrocket.com/api/referral/track-purchase \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "clx1abc123",
    "referralCode": "REF-XYZ789",
    "orderId": "order-12345",
    "amount": 99.99,
    "currency": "USD",
    "externalSiteUrl": "https://yoursite.com/checkout/success",
    "email": "buyer@example.com"
  }'

javascript

await fetch("https://blitzrocket.com/api/referral/track-purchase", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    campaignId: "clx1abc123",
    referralCode: "REF-XYZ789",
    orderId: "order-12345",
    amount: 99.99,
    currency: "USD",
    externalSiteUrl: "https://yoursite.com/checkout/success",
    email: "buyer@example.com",
  }),
});

python

import requests

requests.post(
    "https://blitzrocket.com/api/referral/track-purchase",
    json={
        "campaignId": "clx1abc123",
        "referralCode": "REF-XYZ789",
        "orderId": "order-12345",
        "amount": 99.99,
        "currency": "USD",
        "externalSiteUrl": "https://yoursite.com/checkout/success",
        "email": "buyer@example.com",
    }
)

Réponse

Campagne de parrainage (points) :

json

{
  "success": true,
  "message": "Achat enregistré avec succès",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 50, "friend": 10 },
  "commissionAwarded": { "advocate": 0 }
}

Campagne d’affiliation (commission en dollars) :

json

{
  "success": true,
  "message": "Achat enregistré avec succès",
  "referrerEntryId": "entry_abc123",
  "pointsAwarded": { "advocate": 0, "friend": 0 },
  "commissionAwarded": { "advocate": 24.99 }
}

Pour le suivi d’achat uniquement par email (sans code de parrainage dans la requête), utilisez plutôt POST /api/contest/track-purchase.

Exemple complet côté serveur

Voici un exemple complet d'implémentation du suivi des parrainages sur votre serveur :

javascript

const express = require("express");
const app = express();

const BLITZROCKET_BASE = "https://blitzrocket.com/api/referral";
const CONTEST_ID = process.env.CONTEST_ID;

app.post("/api/signup", async (req, res) => {
  const { email, name, referralCode } = req.body;

  // 1. Créer un utilisateur dans votre système
  const user = await createUser({ email, name });

  // 2. Suivre l'inscription parrainée dans Blitz Rocket
  if (referralCode) {
    await fetch(`${BLITZROCKET_BASE}/track-signup`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        email,
        name,
        contestId: CONTEST_ID,
        referralCode,
      }),
    });
  }

  res.json({ success: true, user });
});

app.post("/api/purchase", async (req, res) => {
  const { email, orderId, amount, currency } = req.body;

  // 1. Traiter l'achat dans votre système
  const order = await processOrder({ email, orderId, amount });

  // 2. Suivre l'achat dans Blitz Rocket
  await fetch(`${BLITZROCKET_BASE}/track-purchase`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email,
      contestId: CONTEST_ID,
      orderId,
      amount,
      currency,
    }),
  });

  res.json({ success: true, order });
});