Licences

Chariow fournit une gestion intégrée des clés de licence pour les produits logiciels. Les licences sont générées automatiquement lorsque les clients achètent des produits de type licence et peuvent être activées, validées et révoquées via l’API.

Objet Licence

Une licence contient des informations complètes sur son statut, son historique d’activation et sa validité :

{
  "id": "lic_abc123",
  "status": "active",
  "customer": {
    "id": "cus_xyz789",
    "name": "Jean Dupont",
    "email": "jean@example.com"
  },
  "product": {
    "id": "prd_abc456",
    "name": "Premium Software License",
    "slug": "premium-software-license"
  },
  "license": {
    "key": "ABC-123-XYZ-789",
    "masked_key": "ABC-***-***-789"
  },
  "is_active": true,
  "is_expired": false,
  "can_activate": true,
  "activations": {
    "count": 3,
    "max": 10,
    "remaining": 7
  },
  "certificate_url": "https://api.chariow.com/certificates/lic_abc123.pdf",
  "metadata": null,
  "activated_at": "2025-01-15T10:30:00.000000Z",
  "expires_at": "2026-01-15T10:30:00.000000Z",
  "expired_at": null,
  "revoked_at": null,
  "created_at": "2025-01-15T09:00:00.000000Z",
  "updated_at": "2025-01-15T10:30:00.000000Z"
}

Champs Clés

license.key : La chaîne de clé de licence unique (par exemple, ABC-123-XYZ-789)
license.masked_key : Version masquée pour l’affichage (par exemple, ABC-***-***-789)
status : Statut actuel de la licence (voir le tableau ci-dessous)
is_active : Booléen indiquant si la licence est actuellement active et utilisable
is_expired : Booléen indiquant si la licence a expiré
can_activate : Booléen indiquant si la licence peut être activée (a des emplacements restants)
activations.count : Nombre actuel d’activations d’appareils
activations.max : Nombre maximal d’activations autorisées
activations.remaining : Nombre d’emplacements d’activation restants
certificate_url : URL pour télécharger le certificat de licence (si disponible)
activated_at : Date de la première activation de la licence (null si jamais activée)
expires_at : Date d’expiration de la licence (null pour les licences à vie)
revoked_at : Date de révocation de la licence (null si non révoquée)

Statuts des Licences

Statut	Description
`pending_activation`	Licence créée mais pas encore activée
`active`	Licence activée et valide pour utilisation
`expired`	Licence ayant dépassé sa date d’expiration
`revoked`	Licence révoquée de manière permanente

Lister les Licences

Récupérez toutes les licences émises pour votre boutique :

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

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

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

Paramètres de Requête

Paramètre	Type	Description
`per_page`	integer	Nombre de licences par page (par défaut 50, maximum 100)
`cursor`	string	Curseur de pagination de la réponse précédente
`status`	string	Filtrer par statut (`pending_activation`, `active`, `expired`, `revoked`)
`customer_id`	string	Filtrer par ID public du client (par exemple, `cus_abc123`)
`product_id`	string	Filtrer par ID public du produit (par exemple, `prd_def456`)

Exemples de Filtrage

# Obtenir uniquement les licences actives
curl -X GET "https://api.chariow.com/v1/licenses?status=active" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Obtenir les licences pour un produit spécifique
curl -X GET "https://api.chariow.com/v1/licenses?product_id=prd_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Obtenir les licences pour un client spécifique
curl -X GET "https://api.chariow.com/v1/licenses?customer_id=cus_xyz789" \
  -H "Authorization: Bearer sk_live_your_api_key"

Obtenir une Licence par Clé

Récupérez une licence spécifique en utilisant sa clé de licence :

curl -X GET "https://api.chariow.com/v1/licenses/ABC-123-XYZ-789" \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.chariow.com/v1/licenses/ABC-123-XYZ-789', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

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

Valider une Licence

Pour valider une licence dans votre application, récupérez-la et vérifiez son statut :

async function validateLicense(licenseKey) {
  const response = await fetch(
    `https://api.chariow.com/v1/licenses/${licenseKey}`,
    { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
  );

  if (!response.ok) {
    return { valid: false, reason: 'Licence introuvable' };
  }

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

  if (!data.is_active) {
    return { valid: false, reason: 'La licence n\'est pas active' };
  }

  if (data.is_expired) {
    return { valid: false, reason: 'La licence a expiré' };
  }

  return { valid: true, license: data };
}

Activer une Licence

Activez une licence sur un appareil. Le système capture automatiquement l’adresse IP et l’agent utilisateur :

curl -X POST "https://api.chariow.com/v1/licenses/ABC-123-XYZ-789/activate" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "device_identifier": "00:1B:44:11:3A:B7"
  }'

const response = await fetch(
  'https://api.chariow.com/v1/licenses/ABC-123-XYZ-789/activate',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      device_identifier: '00:1B:44:11:3A:B7'  // Adresse MAC, UUID, etc.
    })
  }
);

Comportement de la Première Activation

Lors de la première activation :

Le statut passe de pending_activation à active
L’horodatage activated_at est défini
expires_at est calculé en fonction de la période de validité du produit
activation_count s’incrémente à 1

Activations Suivantes

Lors des activations supplémentaires :

activation_count est incrémenté
Un nouveau record d’activation est créé
Le statut de la licence reste active

Limites d’Activation

Chaque licence a un nombre maximal d’activations (max_activations). Lorsque la limite est atteinte, les activations supplémentaires échoueront :

{
  "message": "Limite d'activation atteinte",
  "data": [],
  "errors": []
}

Vérifiez can_activate et activations.remaining avant de tenter une activation.

Révoquer une Licence

Révoquez une licence pour empêcher toute utilisation ultérieure :

curl -X POST "https://api.chariow.com/v1/licenses/ABC-123-XYZ-789/revoke" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Le client a demandé un remboursement"
  }'

const response = await fetch(
  'https://api.chariow.com/v1/licenses/ABC-123-XYZ-789/revoke',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reason: 'Le client a demandé un remboursement'
    })
  }
);

La révocation d’une licence est permanente. La licence ne peut pas être réactivée après révocation.

Obtenir l’Historique des Activations

Consultez toutes les activations pour une licence spécifique avec un suivi détaillé des appareils :

curl -X GET "https://api.chariow.com/v1/licenses/ABC-123-XYZ-789/activations?per_page=20" \
  -H "Authorization: Bearer sk_live_your_api_key"

Réponse

{
  "data": [
    {
      "id": "act_abc123",
      "activated_by": {
        "ip": {
          "value": "203.0.113.45",
          "country": {
            "code": "US",
            "name": "États-Unis"
          }
        },
        "user_agent": {
          "browser": "Chrome",
          "platform": "Windows",
          "device": "desktop"
        },
        "device": "00:1B:44:11:3A:B7"
      },
      "metadata": null,
      "activated_at": "2025-01-18T15:42:00.000000Z",
      "created_at": "2025-01-18T15:42:00.000000Z"
    },
    {
      "id": "act_def456",
      "activated_by": {
        "ip": {
          "value": "198.51.100.12",
          "country": {
            "code": "FR",
            "name": "France"
          }
        },
        "user_agent": {
          "browser": "Safari",
          "platform": "macOS",
          "device": "desktop"
        },
        "device": "A4:5E:60:D8:2F:11"
      },
      "metadata": null,
      "activated_at": "2025-01-16T09:15:00.000000Z",
      "created_at": "2025-01-16T09:15:00.000000Z"
    }
  ],
  "pagination": {
    "count": 2,
    "per_page": 20,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more_pages": false
  }
}

Ce qui est Suivi

Chaque enregistrement d’activation contient :

Adresse IP : Automatiquement capturée depuis la requête d’activation, avec géolocalisation
User Agent : Informations de navigateur et de plateforme analysées
Identifiant de l’Appareil : Identifiant optionnel que vous fournissez (adresse MAC, UUID, etc.)
Horodatage : Moment de l’activation
Métadonnées : Données personnalisées optionnelles

Ceci est utile pour :

Auditer l’utilisation des licences
Détecter les activités suspectes
Fournir aux clients une gestion des appareils
Déboguer les problèmes d’activation

Exemple d’Implémentation

Voici un exemple complet de validation de licence dans une application de bureau :

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

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

    if (!response.ok) {
      throw new Error('Clé de licence invalide');
    }

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

    if (!data.can_activate) {
      throw new Error('La licence ne peut pas être activée');
    }

    return data;
  }

  async activate(licenseKey, deviceId) {
    const response = await fetch(
      `${this.baseUrl}/licenses/${licenseKey}/activate`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ device_identifier: deviceId })
      }
    );

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

    return response.json();
  }
}

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

try {
  const license = await manager.validate('ABC-123-XYZ-789');
  console.log('Licence valide:', license.is_active);

  await manager.activate('ABC-123-XYZ-789', getDeviceId());
  console.log('Licence activée avec succès');
} catch (error) {
  console.error('Erreur de licence:', error.message);
}

Résumé des Endpoints API

Endpoint	Méthode	Description
`/v1/licenses`	GET	Lister toutes les licences avec filtrage
`/v1/licenses/{licenseKey}`	GET	Obtenir les détails d’une licence spécifique
`/v1/licenses/{licenseKey}/activate`	POST	Activer la licence sur un appareil
`/v1/licenses/{licenseKey}/revoke`	POST	Révoquer définitivement une licence
`/v1/licenses/{licenseKey}/activations`	GET	Obtenir l’historique des activations

Bonnes Pratiques

Sécurité

N’exposez jamais votre clé API dans le code côté client
Utilisez les clés API côté serveur uniquement
Validez les licences côté serveur avant d’accorder l’accès
Stockez les clés de licence de manière sécurisée sur l’appareil du client

Identification des Appareils

Utilisez des identifiants d’appareils uniques et persistants (adresse MAC, UUID matériel)
N’utilisez pas d’identifiants modifiables par l’utilisateur (nom d’ordinateur, nom d’utilisateur)
Considérez les identifiants spécifiques à la plateforme (Windows : GUID de machine, macOS : UUID matériel)

Gestion des Activations

Vérifiez can_activate avant de tenter une activation
Affichez activations.remaining aux utilisateurs
Implémentez une interface de gestion des appareils pour les clients
Gérez les erreurs d’activation avec élégance

Fréquence de Validation

Validez au démarrage de l’application
Re-validez périodiquement (par exemple, toutes les 24 heures)
Mettez en cache les résultats de validation localement
Implémentez une période de grâce hors ligne

Gestion des Erreurs

Gérez les erreurs réseau avec élégance
Fournissez des messages d’erreur clairs aux utilisateurs
Implémentez une logique de nouvelle tentative avec backoff exponentiel
Enregistrez les tentatives d’activation pour le débogage

Ressources Connexes

Guide des Produits

Créer des produits de type licence

API Licences

Consultez la référence complète de l’API Licences

Obtenir une Licence

Récupérer les détails de la licence

Activer une Licence

Activer sur un appareil

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

Objet Licence

Champs Clés

Statuts des Licences

Lister les Licences

Paramètres de Requête

Exemples de Filtrage

Obtenir une Licence par Clé

Valider une Licence

Activer une Licence

Comportement de la Première Activation

Activations Suivantes

Limites d’Activation

Révoquer une Licence

Obtenir l’Historique des Activations

Réponse

Ce qui est Suivi

Exemple d’Implémentation

Résumé des Endpoints API

Bonnes Pratiques

Sécurité

Identification des Appareils

Gestion des Activations

Fréquence de Validation

Gestion des Erreurs

Ressources Connexes

Guide des Produits

API Licences

Obtenir une Licence

Activer une Licence

​Objet Licence

​Champs Clés

​Statuts des Licences

​Lister les Licences

​Paramètres de Requête

​Exemples de Filtrage

​Obtenir une Licence par Clé

​Valider une Licence

​Activer une Licence

​Comportement de la Première Activation

​Activations Suivantes

​Limites d’Activation

​Révoquer une Licence

​Obtenir l’Historique des Activations

​Réponse

​Ce qui est Suivi

​Exemple d’Implémentation

​Résumé des Endpoints API

​Bonnes Pratiques

​Sécurité

​Identification des Appareils

​Gestion des Activations

​Fréquence de Validation

​Gestion des Erreurs

​Ressources Connexes

Guide des Produits

API Licences

Obtenir une Licence

Activer une Licence

Objet Licence

Champs Clés

Statuts des Licences

Lister les Licences

Paramètres de Requête

Exemples de Filtrage

Obtenir une Licence par Clé

Valider une Licence

Activer une Licence

Comportement de la Première Activation

Activations Suivantes

Limites d’Activation

Révoquer une Licence

Obtenir l’Historique des Activations

Réponse

Ce qui est Suivi

Exemple d’Implémentation

Résumé des Endpoints API

Bonnes Pratiques

Sécurité

Identification des Appareils

Gestion des Activations

Fréquence de Validation

Gestion des Erreurs

Ressources Connexes