Affiliés

Chariow fournit un système complet de gestion d’affiliation qui vous permet de développer vos ventes grâce aux partenariats. Les affiliés peuvent promouvoir vos produits en utilisant des codes de parrainage uniques et gagner des commissions sur les ventes réussies.

Objet Affilié

Un affilié contient des informations sur son compte, ses métriques de performance et les détails imbriqués de son compte :

{
  "id": "saff_xyz789abc",
  "status": "active",
  "source": {
    "value": "invitation",
    "label": "Invitation",
    "description": "Ajouté via invitation de la boutique"
  },
  "total_visits": 156,
  "total_sales": 32,
  "total_earnings": {
    "value": 1250,
    "formatted": "$1,250.00",
    "short": "1K",
    "currency": "USD"
  },
  "first_visit_at": "2025-01-16T08:00:00+00:00",
  "last_visit_at": "2025-02-01T14:22:00+00:00",
  "suspended_at": null,
  "suspended_reason": null,
  "account": {
    "id": "aff_abc123def",
    "pseudo": "creative_studio",
    "country": {
      "name": "United States",
      "code": "US",
      "alpha_3_code": "USA",
      "dial_code": "+1",
      "currency": "USD",
      "flag": "https://cdn.axazara.com/flags/svg/US.svg"
    },
    "status": "active",
    "user": {
      "id": "usr_def456",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "nickname": null,
      "email": "john@example.com",
      "profile_photo_url": null
    },
    "created_at": "2025-01-15T09:00:00+00:00"
  },
  "created_at": "2025-01-15T10:00:00+00:00",
  "updated_at": "2025-02-01T14:22:00+00:00"
}

Champs Clés

id : ID public de l’affilié de la boutique (préfixé par saff_)
status : Statut actuel (active ou suspended)
source : Comment l’affilié a rejoint (par exemple, invitation, network)
total_visits : Nombre de visites via le lien de parrainage
total_sales : Nombre de ventes complétées à partir des recommandations
total_earnings : Commission totale gagnée avec montant formaté
account : Détails imbriqués du compte affilié incluant les informations utilisateur
account.user : Profil utilisateur de l’affilié (nom, email, etc.)
account.pseudo : Nom d’affichage utilisé par l’affilié
account.country : Pays de l’affilié (nom, codes ISO, indicatif, devise et drapeau)
suspended_at : Horodatage de la suspension (null si actif)
suspended_reason : Raison de la suspension (null si actif)

Statuts des Affiliés

Statut	Description
`active`	L’affilié est actif et peut gagner des commissions
`suspended`	Le compte affilié a été suspendu

Obtenir un Affilié

Récupérez un affilié spécifique en utilisant son code de parrainage unique :

curl -X GET "https://api.chariow.com/v1/affiliates/CREATOR123" \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.chariow.com/v1/affiliates/CREATOR123', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const { data } = await response.json();

Ceci est utile pour :

Valider un code affilié avant d’appliquer des commissions
Afficher les informations de l’affilié sur votre site web
Construire des tableaux de bord pour les affiliés

Envoyer des Invitations d’Affiliation

Invitez des affiliés potentiels à rejoindre votre programme en envoyant des emails d’invitation :

curl -X POST "https://api.chariow.com/v1/affiliates/invitations" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["jean@example.com", "marie@example.com", "partenaire@entreprise.com"]
  }'

const response = await fetch('https://api.chariow.com/v1/affiliates/invitations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emails: ['jean@example.com', 'marie@example.com', 'partenaire@entreprise.com']
  })
});

const { data } = await response.json();

Invitations par Lot

Vous pouvez envoyer jusqu’à 25 invitations en une seule requête. L’API va :

Créer et envoyer des invitations pour les nouveaux emails valides
Ignorer les emails qui sont déjà des affiliés enregistrés
Ignorer les emails qui ont des invitations en attente
Mettre les adresses en minuscules et supprimer les doublons

Les adresses ignorées ne figurent pas dans la réponse : data ne contient que les invitations créées, et reste vide si toutes les adresses ont été ignorées. Le message est Invitation envoyée avec succès. pour une invitation et N invitations envoyées avec succès. sinon.

Réponse

{
  "message": "2 invitations envoyées avec succès.",
  "data": [
    {
      "id": "affinv_abc123xyz",
      "email": "jean@example.com",
      "status": "pending",
      "expires_at": "2026-02-10T10:30:00+00:00",
      "accepted_at": null,
      "created_at": "2026-01-11T10:30:00+00:00"
    },
    {
      "id": "affinv_def456uvw",
      "email": "marie@example.com",
      "status": "pending",
      "expires_at": "2026-02-10T10:30:00+00:00",
      "accepted_at": null,
      "created_at": "2026-01-11T10:30:00+00:00"
    }
  ],
  "errors": []
}

Objet Invitation

Une invitation contient des informations sur son statut et son expiration :

{
  "id": "affinv_abc123xyz",
  "email": "jean@example.com",
  "status": "pending",
  "expires_at": "2026-02-10T10:30:00+00:00",
  "accepted_at": null,
  "created_at": "2026-01-11T10:30:00+00:00"
}

Statuts des Invitations

Statut	Description
`pending`	Invitation envoyée mais pas encore acceptée
`accepted`	L’invitation a été acceptée
`expired`	L’invitation a dépassé sa date d’expiration
`cancelled`	L’invitation a été annulée

Événements Webhook

Lorsqu’un affilié rejoint votre boutique, via une invitation ou via le réseau d’affiliation, un événement webhook est déclenché via les Pulses. L’événement est signé et enregistré comme tous les autres événements Pulse ; consultez le guide des Pulses pour le détail de la charge utile.

affiliate.joined

Déclenché lorsqu’un nouvel affilié rejoint votre boutique.

{
  "event": "affiliate.joined",
  "affiliate": {
    "id": "saff_xyz789abc",
    "account": {
      "id": "aff_abc123def",
      "code": "CREATOR123",
      "pseudo": "studio_creatif",
      "email": "creator@example.com",
      "first_name": "Jean",
      "last_name": "Dupont",
      "name": "Jean Dupont",
      "country": {
        "name": "France",
        "code": "FR",
        "alpha_3_code": "FRA",
        "dial_code": "+33",
        "currency": "EUR",
        "flag": "https://cdn.axazara.com/flags/svg/FR.svg"
      },
      "phone": {
        "number": 33612345678,
        "country": {
          "name": "France",
          "code": "FR",
          "alpha_3_code": "FRA",
          "dial_code": "+33",
          "currency": "EUR",
          "flag": "https://cdn.axazara.com/flags/svg/FR.svg"
        }
      }
    },
    "source": {
      "value": "invitation",
      "label": "Invitation",
      "description": "Added via store invitation"
    },
    "status": "active",
    "joined_at": "2025-01-15T10:40:00+00:00"
  },
  "store": {
    "id": "str_xyz789",
    "name": "Ma Boutique Digitale",
    "url": "https://maboutique.mychariow.com"
  }
}

Configurez les Pulses dans votre tableau de bord Chariow (Automatisation → Pulses) pour recevoir ces événements.

Exemple d’Implémentation

Voici un exemple complet de gestion des affiliés dans votre application :

class AffiliateManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.chariow.com/v1';
  }

  async getAffiliate(code) {
    const response = await fetch(
      `${this.baseUrl}/affiliates/${code}`,
      { headers: { 'Authorization': `Bearer ${this.apiKey}` }}
    );

    if (!response.ok) {
      throw new Error('Affilié non trouvé');
    }

    const { data } = await response.json();
    return data;
  }

  async sendInvitations(emails) {
    const response = await fetch(
      `${this.baseUrl}/affiliates/invitations`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ emails })
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    return response.json();
  }

  async validateAffiliateCode(code) {
    try {
      const affiliate = await this.getAffiliate(code);
      return {
        valid: affiliate.status === 'active',
        affiliate
      };
    } catch (error) {
      return { valid: false, error: error.message };
    }
  }
}

// Utilisation
const manager = new AffiliateManager('sk_live_your_api_key');

// Valider un code affilié au moment du paiement
const { valid, affiliate } = await manager.validateAffiliateCode('CREATOR123');
if (valid) {
  console.log(`L'affilié ${affiliate.account.user.name} est actif`);
  console.log(`Gains totaux : ${affiliate.total_earnings.formatted}`);
}

// Envoyer des invitations aux affiliés potentiels
const result = await manager.sendInvitations([
  'partenaire1@example.com',
  'partenaire2@example.com'
]);
console.log(`${result.data.length} invitations envoyées`);

Résumé des Endpoints API

Endpoint	Méthode	Description
`/v1/affiliates/{affiliateCode}`	GET	Obtenir les détails d’un affilié par code
`/v1/affiliates/invitations`	POST	Envoyer des invitations d’affiliation

Bonnes Pratiques

Validation du Code Affilié

Validez toujours les codes affiliés avant d’appliquer des commissions
Vérifiez que le statut de l’affilié est active
Mettez en cache les données des affiliés pour réduire les appels API

Gestion des Invitations

Utilisez les invitations par lot pour plus d’efficacité (jusqu’à 25 emails)
Gérez les emails ignorés avec élégance
Implémentez une logique de nouvelle tentative pour les invitations échouées

Intégration Webhook

Configurez les webhooks pour recevoir les événements affiliate.joined
Utilisez les webhooks pour déclencher des workflows d’intégration
Stockez les données des affiliés lorsqu’ils rejoignent pour des recherches plus rapides

Suivi des Commissions

Suivez avec précision les recommandations des affiliés
Fournissez aux affiliés des statistiques en temps réel
Implémentez des fenêtres d’attribution appropriées

Ressources Connexes

Guide des Pulses

Configurer les webhooks pour les événements affiliés

API Obtenir Affilié

Voir la référence API Obtenir Affilié

API Envoyer Invitations

Voir la référence API Envoyer Invitations

Guide des Ventes

Suivre les ventes des affiliés

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

Objet Affilié

Champs Clés

Statuts des Affiliés

Obtenir un Affilié

Envoyer des Invitations d’Affiliation

Invitations par Lot

Réponse

Objet Invitation

Statuts des Invitations

Événements Webhook

affiliate.joined

Exemple d’Implémentation

Résumé des Endpoints API

Bonnes Pratiques

Validation du Code Affilié

Gestion des Invitations

Intégration Webhook

Suivi des Commissions

Ressources Connexes

Guide des Pulses

API Obtenir Affilié

API Envoyer Invitations

Guide des Ventes

​Objet Affilié

​Champs Clés

​Statuts des Affiliés

​Obtenir un Affilié

​Envoyer des Invitations d’Affiliation

​Invitations par Lot

​Réponse

​Objet Invitation

​Statuts des Invitations

​Événements Webhook

​affiliate.joined

​Exemple d’Implémentation

​Résumé des Endpoints API

​Bonnes Pratiques

​Validation du Code Affilié

​Gestion des Invitations

​Intégration Webhook

​Suivi des Commissions

​Ressources Connexes

Guide des Pulses

API Obtenir Affilié

API Envoyer Invitations

Guide des Ventes

Objet Affilié

Champs Clés

Statuts des Affiliés

Obtenir un Affilié

Envoyer des Invitations d’Affiliation

Invitations par Lot

Réponse

Objet Invitation

Statuts des Invitations

Événements Webhook

affiliate.joined

Exemple d’Implémentation

Résumé des Endpoints API

Bonnes Pratiques

Validation du Code Affilié

Gestion des Invitations

Intégration Webhook

Suivi des Commissions

Ressources Connexes