Passer au contenu principal
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": "[email protected]"
  },
  "product": {
    "id": "prd_abc456",
    "name": "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

StatutDescription
pending_activationLicence créée mais pas encore activée
activeLicence activée et valide pour utilisation
expiredLicence ayant dépassé sa date d’expiration
revokedLicence 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"

​
Paramètres de Requête

ParamètreTypeDescription
per_pageintegerNombre de licences par page (par défaut 50, maximum 100)
cursorstringCurseur de pagination de la réponse précédente
statusstringFiltrer par statut (pending_activation, active, expired, revoked)
customer_idstringFiltrer par ID public du client (par exemple, cus_abc123)
product_idstringFiltrer 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"

​
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"
  }'

​
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"
  }'
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

EndpointMéthodeDescription
/v1/licensesGETLister toutes les licences avec filtrage
/v1/licenses/{licenseKey}GETObtenir les détails d’une licence spécifique
/v1/licenses/{licenseKey}/activatePOSTActiver la licence sur un appareil
/v1/licenses/{licenseKey}/revokePOSTRévoquer définitivement une licence
/v1/licenses/{licenseKey}/activationsGETObtenir 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