Pulses

Les Pulses sont des notifications webhook qui vous permettent de recevoir des requêtes HTTP POST en temps réel lorsque des événements spécifiques se produisent dans votre boutique Chariow. Au lieu d’interroger constamment l’API, les Pulses envoient les données d’événements vers votre URL de point de terminaison configurée dès que quelque chose se produit, vous permettant de construire des intégrations et des automatisations réactives.

Comment fonctionnent les Pulses

Un événement se produit

Un événement se produit dans votre boutique (par exemple, une vente est finalisée).

Pulse déclenché

Chariow envoie une requête HTTP POST vers votre point de terminaison configuré.

Traiter l'événement

Votre serveur reçoit la charge utile et la traite.

Confirmer la réception

Votre serveur renvoie un code de statut 2xx pour confirmer la réception.

Configuration des Pulses

Vous pouvez configurer les Pulses de plusieurs manières :

Via le tableau de bord de la boutique

Allez dans Automatisation → Pulses
Cliquez sur Ajouter un Pulse
Entrez l’URL de votre point de terminaison webhook (doit être en HTTPS)
Sélectionnez les événements que vous souhaitez recevoir
Sélectionnez éventuellement des produits spécifiques (laissez vide pour tous les produits)
Enregistrez votre Pulse

Votre point de terminaison Pulse doit être accessible via HTTPS. Les points de terminaison HTTP ne sont pas pris en charge pour des raisons de sécurité.

Événements Pulse

Les Pulses prennent en charge les événements suivants. Lorsqu’un événement se produit, la charge utile du webhook contient un champ event avec la valeur de l’événement.

Événements de vente

Valeur d’événement	Libellé	Description
`successful.sale`	Vente réussie	Se déclenche lorsqu’une vente est finalisée
`abandoned.sale`	Vente abandonnée	Se déclenche lorsqu’une vente est abandonnée
`failed.sale`	Vente échouée	Se déclenche lorsqu’une vente échoue

Événements de licence

Valeur d’événement	Libellé	Description
`license.activated`	Licence activée	Se déclenche lorsqu’une licence est activée
`license.expired`	Licence expirée	Se déclenche lorsqu’une licence expire
`license.issued`	Licence émise	Se déclenche lorsqu’une licence est émise à un client
`license.revoked`	Licence révoquée	Se déclenche lorsqu’une licence est révoquée

Événements d’affiliation

Valeur d’événement	Libellé	Description
`affiliate.joined`	Affilié rejoint	Se déclenche lorsqu’un nouvel affilié rejoint votre boutique

Vous pouvez configurer plusieurs événements pour une seule URL de Pulse. Lorsque l’un des événements sélectionnés se produit, Chariow enverra une notification webhook à votre point de terminaison avec la valeur d’événement correspondante.

Charge utile Pulse

Lorsqu’un événement configuré se produit, Chariow envoie une requête HTTP POST vers votre URL webhook avec les données de l’événement dans le corps de la requête. La structure exacte de la charge utile dépend du type d’événement.

Les charges utiles Pulse contiennent des données d’événement complètes, y compris des détails sur l’entité (vente, licence, etc.), les informations client, les détails du produit et le contexte de la boutique. La structure de la charge utile varie selon le type d’événement pour fournir des informations pertinentes pour chaque événement.

Exemple de vente réussie

Lorsqu’une vente est finalisée, Chariow envoie un webhook avec l’événement successful.sale :

{
  "event": "successful.sale",
  "sale": {
    "id": "sal_xyz789abc",
    "amount": {
      "value": 99,
      "formatted": "99,00 €",
      "short": "99",
      "currency": "EUR"
    },
    "original_amount": {
      "value": 99,
      "formatted": "99,00 €",
      "short": "99",
      "currency": "EUR"
    },
    "discount_amount": {
      "value": 0,
      "formatted": "0,00 €",
      "short": "0",
      "currency": "EUR"
    },
    "settlement": {
      "amount": {
        "value": 89.10,
        "formatted": "89,10 €",
        "short": "89",
        "currency": "EUR"
      },
      "due_at": "2025-01-22T10:30:00+00:00",
      "done_at": null,
      "service_fee": {
        "value": 4.95,
        "formatted": "4,95 €",
        "short": "5",
        "currency": "EUR"
      },
      "payment_fee": {
        "value": 4.95,
        "formatted": "4,95 €",
        "short": "5",
        "currency": "EUR"
      },
      "fee": {
        "value": 9.90,
        "formatted": "9,90 €",
        "short": "10",
        "currency": "EUR"
      }
    },
    "status": "completed",
    "created_at": "2025-01-15T10:30:00+00:00",
    "custom_fields": null,
    "custom_metadata": {"order_ref": "CMD-123"},
    "completed_at": "2025-01-15T10:32:00+00:00",
    "abandoned_at": null,
    "failed_at": null
  },
  "product": {
    "id": "prd_def456",
    "name": "Cours Premium",
    "url": "https://maboutique.mychariow.com/p/cours-premium",
    "price": {
      "value": 99,
      "formatted": "99,00 €",
      "short": "99",
      "currency": "EUR"
    }
  },
  "customer": {
    "id": "cus_abc123",
    "name": "Jean Dupont",
    "first_name": "Jean",
    "last_name": "Dupont",
    "email": "client@example.com",
    "phone": "+33612345678",
    "country": "FR"
  },
  "affiliate": null,
  "store": {
    "id": "str_xyz789",
    "name": "Ma Boutique Digitale",
    "url": "https://maboutique.mychariow.com"
  },
  "checkout": {
    "url": "https://maboutique.mychariow.com/checkout/sal_xyz789abc"
  }
}

Exemple de licence activée

Lorsqu’une licence est activée, Chariow envoie un webhook avec l’événement license.activated :

{
  "event": "license.activated",
  "license": {
    "id": "lic_ghi789def",
    "key": "XXXX-XXXX-XXXX-XXXX",
    "status": "active",
    "source_type": "sale",
    "activation_count": 1,
    "max_activations": 5,
    "activated_at": "2025-01-15T10:35:00+00:00",
    "expires_at": "2026-01-15T10:30:00+00:00",
    "expired_at": null,
    "revoked_at": null,
    "created_at": "2025-01-15T10:30:00+00:00"
  },
  "product": {
    "id": "prd_def456",
    "name": "Licence Logiciel Pro",
    "url": "https://maboutique.mychariow.com/p/licence-logiciel-pro"
  },
  "customer": {
    "id": "cus_abc123",
    "name": "Jean Dupont",
    "first_name": "Jean",
    "last_name": "Dupont",
    "email": "client@example.com",
    "phone": "+33612345678",
    "country": "FR"
  },
  "store": {
    "id": "str_xyz789",
    "name": "Ma Boutique Digitale",
    "url": "https://maboutique.mychariow.com"
  }
}

Exemple d’affilié rejoint

Lorsqu’un nouvel affilié rejoint votre boutique, Chariow envoie un webhook avec l’événement affiliate.joined :

{
  "event": "affiliate.joined",
  "affiliate": {
    "id": "saff_xyz789abc",
    "account": {
      "id": "aff_abc123def",
      "code": "CREATOR123",
      "pseudo": "studio_creatif",
      "email": "creator@example.com",
      "country": {
        "code": "FR",
        "name": "France"
      }
    },
    "source": "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"
  }
}

La structure exacte de la charge utile peut inclure des champs supplémentaires selon le type d’événement et le contexte. Vérifiez toujours la charge utile réelle reçue à votre point de terminaison pour la structure complète des données.

Gestion des Pulses

Exemple basique (Node.js/Express)

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

app.post('/webhooks/chariow', express.json(), (req, res) => {
  const payload = req.body;
  const event = payload.event;

  switch (event) {
    case 'successful.sale':
      handleSuccessfulSale(payload.sale, payload.product, payload.customer, payload.store);
      break;
    case 'abandoned.sale':
      handleAbandonedSale(payload.sale, payload.store);
      break;
    case 'failed.sale':
      handleFailedSale(payload.sale, payload.store);
      break;
    case 'license.activated':
      handleLicenseActivated(payload.license, payload.product, payload.customer);
      break;
    case 'license.expired':
      handleLicenseExpired(payload.license, payload.customer);
      break;
    case 'license.issued':
      handleLicenseIssued(payload.license, payload.product, payload.customer);
      break;
    case 'license.revoked':
      handleLicenseRevoked(payload.license, payload.customer);
      break;
    case 'affiliate.joined':
      handleAffiliateJoined(payload.affiliate, payload.store);
      break;
    default:
      console.log(`Type d'événement non géré : ${event}`);
  }

  // Toujours renvoyer 200 pour confirmer la réception
  res.status(200).send('OK');
});

function handleSuccessfulSale(sale, store) {
  console.log(`Vente finalisée : ${sale.id} dans la boutique ${store.name}`);
  // Ajouter le client au CRM, envoyer un email de confirmation, accorder l'accès, etc.
}

function handleLicenseActivated(license, customer) {
  console.log(`Licence activée : ${license.key} pour ${customer.email}`);
  // Enregistrer l'activation, mettre à jour les enregistrements internes, notifier le client, etc.
}

function handleAffiliateJoined(affiliate, store) {
  console.log(`Nouvel affilié rejoint : ${affiliate.account.code} dans la boutique ${store.name}`);
  // Envoyer un email de bienvenue, créer l'accès au tableau de bord affilié, notifier l'équipe, etc.
}

app.listen(3000, () => console.log('Serveur webhook en cours d\'exécution sur le port 3000'));

Exemple PHP

<?php

// Lire les données POST brutes
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

$event = $data['event'] ?? null;

switch ($event) {
    case 'successful.sale':
        handleSuccessfulSale($data['sale'], $data['product'], $data['customer'], $data['store']);
        break;
    case 'abandoned.sale':
        handleAbandonedSale($data['sale'], $data['store']);
        break;
    case 'failed.sale':
        handleFailedSale($data['sale'], $data['store']);
        break;
    case 'license.activated':
        handleLicenseActivated($data['license'], $data['product'], $data['customer']);
        break;
    case 'license.expired':
        handleLicenseExpired($data['license'], $data['customer']);
        break;
    case 'license.issued':
        handleLicenseIssued($data['license'], $data['product'], $data['customer']);
        break;
    case 'license.revoked':
        handleLicenseRevoked($data['license'], $data['customer']);
        break;
    case 'affiliate.joined':
        handleAffiliateJoined($data['affiliate'], $data['store']);
        break;
    default:
        error_log("Type d'événement non géré : " . $event);
}

// Toujours renvoyer 200 pour confirmer la réception
http_response_code(200);
echo 'OK';

function handleSuccessfulSale($sale, $store) {
    error_log("Vente finalisée : {$sale['id']} dans la boutique {$store['name']}");
    // Ajouter le client au CRM, envoyer un email de confirmation, accorder l'accès, etc.
}

function handleLicenseActivated($license, $customer) {
    error_log("Licence activée : {$license['key']} pour {$customer['email']}");
    // Enregistrer l'activation, mettre à jour les enregistrements internes, notifier le client, etc.
}

function handleAffiliateJoined($affiliate, $store) {
    error_log("Nouvel affilié rejoint : {$affiliate['account']['code']} dans la boutique {$store['name']}");
    // Envoyer un email de bienvenue, créer l'accès au tableau de bord affilié, notifier l'équipe, etc.
}

Politique de réessai

Si votre point de terminaison ne répond pas avec un code de statut 2xx, Chariow réessaiera le Pulse :

Tentative	Délai
1ère tentative	1 minute
2ème tentative	5 minutes
3ème tentative	30 minutes
4ème tentative	2 heures
5ème tentative	24 heures

Après 5 tentatives échouées, le Pulse est marqué comme échoué.

Assurez-vous que votre point de terminaison Pulse répond rapidement (dans les 30 secondes). Les processus de longue durée doivent être gérés de manière asynchrone.

Meilleures pratiques

Répondre rapidement

Renvoyez une réponse 200 immédiatement, puis traitez le Pulse de manière asynchrone pour éviter les délais d’expiration :

app.post('/webhooks/chariow', (req, res) => {
  // Confirmer la réception immédiatement
  res.status(200).send('OK');

  // Traiter de manière asynchrone (par exemple, file d'attente de tâches, worker en arrière-plan)
  queuePulseProcessing(req.body);
});

Gérer les doublons

En raison de la logique de réessai, les Pulses peuvent être envoyés plusieurs fois. Implémentez l’idempotence en suivant les événements traités :

const processedEvents = new Set();

async function processPulse(payload) {
  // Créer un identifiant unique à partir des données du pulse
  const uniqueId = `${payload.event}_${payload.sale?.id || payload.license?.id || payload.affiliate?.id}`;

  if (processedEvents.has(uniqueId)) {
    console.log('Pulse en double, ignoré');
    return;
  }

  processedEvents.add(uniqueId);
  // Traiter le pulse...
}

Utiliser HTTPS

Utilisez toujours HTTPS pour votre point de terminaison Pulse afin de garantir que les données sont chiffrées en transit. Chariow rejettera les points de terminaison HTTP pour des raisons de sécurité.

Surveiller les échecs

Surveillez votre point de terminaison Pulse pour détecter les échecs et les erreurs. Vérifiez régulièrement votre tableau de bord de boutique pour les échecs de livraison de Pulse et enquêtez sur la cause première.

Filtrer par produits

Pour les boutiques à fort volume, envisagez de créer des Pulses séparés pour différents produits afin de rendre le traitement plus efficace et organisé.

Test des Pulses

Utilisez la fonctionnalité de test de Pulse dans votre tableau de bord :

Allez dans Automatisation → Pulses
Cliquez sur votre Pulse
Cliquez sur Envoyer un événement de test
Sélectionnez un type d’événement
Vérifiez que votre point de terminaison a reçu la charge utile de test

Pour le développement local, utilisez un service comme ngrok pour exposer votre serveur local à Internet.

Gestion des Pulses via l’API

Vous pouvez gérer vos Pulses de manière programmatique en utilisant l’API publique Chariow :

Lister tous les Pulses

curl -X GET "https://api.chariow.com/v1/pulses" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "pls_abc123xyz",
      "url": "https://example.com/webhooks/chariow",
      "is_enabled": true,
      "source": {
        "value": "manual",
        "label": "Manuel",
        "description": "Créé manuellement"
      },
      "triggers": [
        {
          "value": "successful_sale",
          "label": "Vente réussie",
          "description": "Se déclenche lorsqu'une vente est finalisée"
        }
      ],
      "products": [
        {
          "id": "prd_def456",
          "name": "Cours Premium",
          "type": "course",
          "pictures": {
            "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
            "cover": "https://cdn.chariow.com/products/cover.jpg"
          },
          "category": {
            "value": "education_and_learning",
            "label": "Education and Learning"
          },
          "pricing": {
            "type": "one_time",
            "price": {
              "value": 99,
              "formatted": "99,00 €",
              "short": "99",
              "currency": "EUR"
            },
            "effective": {
              "value": 99,
              "formatted": "99,00 €",
              "short": "99",
              "currency": "EUR"
            }
          },
          "bundle": null,
          "metadata": null
        }
      ],
      "store": {
        "id": "str_xyz789",
        "name": "Ma Boutique Digitale",
        "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
        "url": "https://maboutique.mychariow.com"
      },
      "is_editable": true,
      "created_at": "2025-01-10T08:00:00+00:00",
      "updated_at": "2025-01-10T08:00:00+00:00"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

Obtenir un Pulse spécifique

curl -X GET "https://api.chariow.com/v1/pulses/pls_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

La réponse pour un pulse unique utilise la même structure que chaque élément dans la réponse de la liste.

Filtrer les Pulses

Vous pouvez filtrer les pulses par URL ou type d’événement en utilisant le paramètre de recherche :

curl -X GET "https://api.chariow.com/v1/pulses?search=successful_sale" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pour la documentation complète de l’API, consultez les points de terminaison Lister les Pulses et Obtenir un Pulse.

Ressources associées

Référence API - Lister les Pulses

Consultez la documentation détaillée de l’API

Référence API - Obtenir un Pulse

Obtenez un pulse spécifique via l’API

Guide des ventes

En savoir plus sur les événements de vente

Guide des licences

En savoir plus sur les événements de licence

Guide des affiliés

En savoir plus sur les événements d’affiliation

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

Comment fonctionnent les Pulses

Configuration des Pulses

Via le tableau de bord de la boutique

Événements Pulse

Événements de vente

Événements de licence

Événements d’affiliation

Charge utile Pulse

Exemple de vente réussie

Exemple de licence activée

Exemple d’affilié rejoint

Gestion des Pulses

Exemple basique (Node.js/Express)

Exemple PHP

Politique de réessai

Meilleures pratiques

Test des Pulses

Gestion des Pulses via l’API

Lister tous les Pulses

Obtenir un Pulse spécifique

Filtrer les Pulses

Ressources associées

Référence API - Lister les Pulses

Référence API - Obtenir un Pulse

Guide des ventes

Guide des licences

Guide des affiliés

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

​Comment fonctionnent les Pulses

​Configuration des Pulses

​Via le tableau de bord de la boutique

​Événements Pulse

​Événements de vente

​Événements de licence

​Événements d’affiliation

​Charge utile Pulse

​Exemple de vente réussie

​Exemple de licence activée

​Exemple d’affilié rejoint

​Gestion des Pulses

​Exemple basique (Node.js/Express)

​Exemple PHP

​Politique de réessai

​Meilleures pratiques

​Test des Pulses

​Gestion des Pulses via l’API

​Lister tous les Pulses

​Obtenir un Pulse spécifique

​Filtrer les Pulses

​Ressources associées

Référence API - Lister les Pulses

Référence API - Obtenir un Pulse

Guide des ventes

Guide des licences

Guide des affiliés

Comment fonctionnent les Pulses

Configuration des Pulses

Via le tableau de bord de la boutique

Événements Pulse

Événements de vente

Événements de licence

Événements d’affiliation

Charge utile Pulse

Exemple de vente réussie

Exemple de licence activée

Exemple d’affilié rejoint

Gestion des Pulses

Exemple basique (Node.js/Express)

Exemple PHP

Politique de réessai

Meilleures pratiques

Test des Pulses

Gestion des Pulses via l’API

Lister tous les Pulses

Obtenir un Pulse spécifique

Filtrer les Pulses

Ressources associées