Authentification API : documentation CheckoutOS

L’API CheckoutOS utilise des clés API pour l’authentification. Ce guide explique comment générer des clés, authentifier les requêtes et gérer les accès API en toute sécurité.

Clés API

Les clés API authentifient toutes les requêtes envoyées à l’API CheckoutOS. Chaque clé est liée à votre boutique et dispose d’autorisations configurables.

Générer des clés API

Accéder aux paramètres

Accédez à CheckoutOS → Settings → API.

Créer une clé

Cliquez sur "Create API Key".

Nommer la clé

Donnez-lui un nom descriptif (par exemple, « Serveur de production »).

Définir les autorisations

Choisissez les portées API auxquelles la clé peut accéder.

Copier la clé

Copiez immédiatement la clé : elle ne sera plus affichée.

Sécurité des clés

Les clés API ne sont affichées qu’une seule fois, lors de leur création. Conservez-les en sécurité. En cas de perte, vous devrez générer une nouvelle clé.

Méthodes d’authentification

Jeton Bearer (recommandé)

Incluez la clé API comme jeton Bearer dans l’en-tête Authorization :

Authentification par jeton Bearer

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

En-tête X-API-Key

Vous pouvez aussi utiliser l’en-tête X-API-Key :

Authentification X-API-Key

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Autorisations API

Les clés API peuvent être limitées à des autorisations précises :

Portées disponibles

{
  "scopes": {
    "read:upsells": "View upsell configurations",
    "write:upsells": "Create and modify upsells",
    "read:bundles": "View bundle configurations",
    "write:bundles": "Create and modify bundles",
    "read:analytics": "Access analytics data",
    "read:orders": "View order data",
    "write:orders": "Modify orders (edits)",
    "read:settings": "View CheckoutOS settings",
    "write:settings": "Modify settings",
    "webhooks:manage": "Create and manage webhooks"
  }
}

Moindre privilège

N’accordez que les autorisations nécessaires à votre intégration. Une clé destinée aux tableaux de bord d’analyse ne devrait pas avoir d’accès en écriture aux ventes incitatives.

Limitation du débit

Les requêtes API sont limitées pour garantir une utilisation équitable :

Limites de débit

{
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 3600,
    "burst_limit": 20
  },
  "headers": {
    "X-RateLimit-Limit": "120",
    "X-RateLimit-Remaining": "115",
    "X-RateLimit-Reset": "1640000000"
  }
}

Lorsque la limite est atteinte, vous recevez une réponse 429 :

Réponse de limite de débit

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Environnements

CheckoutOS fournit des environnements distincts pour le développement et la production :

Environnements API

{
  "production": {
    "base_url": "https://api.chargezen.com/v1",
    "key_prefix": "live_"
  },
  "sandbox": {
    "base_url": "https://sandbox.api.chargezen.com/v1",
    "key_prefix": "test_"
  }
}

Environnement sandbox

Utilisez la sandbox pour le développement et les tests. Ses données sont séparées de la production et peuvent être réinitialisées à tout moment.

SDK officiels

Les SDK officiels gèrent automatiquement l’authentification :

SDK Node.js

import { CheckoutOS } from '@chargezen/checkoutos-sdk';

const client = new CheckoutOS({
  apiKey: process.env.CHARGEZEN_API_KEY,
  environment: 'production'
});

const upsells = await client.upsells.list();

SDK Python

from chargezen import CheckoutOS

client = CheckoutOS(
    api_key=os.environ['CHARGEZEN_API_KEY'],
    environment='production'
)

upsells = client.upsells.list()

Gestion des clés

Bonnes pratiques

Utiliser des variables d’environnement — Ne jamais coder les clés en dur
Renouveler les clés régulièrement — Au moins chaque trimestre
Utiliser des clés distinctes par environnement — Développement, préproduction, production
Révoquer les clés inutilisées — Supprimer celles qui ne servent plus
Surveiller l’utilisation des clés — Repérer les comportements anormaux
Limiter les portées — N’accorder que les autorisations nécessaires

Révoquer les clés

Accéder aux paramètres API

Accédez à CheckoutOS → Settings → API.

Trouver la clé

Repérez dans la liste la clé à révoquer.

Révoquer

Cliquez sur "Revoke" et confirmez.

Effet immédiat

La révocation d’une clé est immédiate. Toutes les requêtes utilisant cette clé échoueront. Assurez-vous d’avoir mis à jour vos applications avant la révocation.

Référence API

Points de terminaison API

Points de terminaison API disponibles

Webhooks

Notifications d’événements en temps réel