Authentification

Toutes les requêtes API doivent être authentifiées à l'aide de clés API. Incluez votre clé API dans l'en-tête de requête pour accéder aux points de terminaison protégés.

Authentification par clé API

Incluez votre clé API dans l'en-tête X-API-Key avec chaque requête:

En-tête d'authentification

X-API-Key: your_api_key_here

Génération de clés API

Avant de pouvoir effectuer des requêtes API, vous devez générer une clé API à partir des paramètres de votre application. Suivez ces étapes pour créer votre première clé API:

Connectez-vous à votre tableau de bord Ultimate Custom Order Status
Accédez à Paramètres > Clés API
Cliquez sur "Générer une nouvelle clé API"
Configurez les permissions pour votre clé API
Enregistrez la clé API en toute sécurité (elle ne sera affichée qu'une seule fois)

💡 Important: Stockez votre clé API dans un emplacement sécurisé immédiatement après la génération. Pour des raisons de sécurité, la clé ne sera affichée qu'une seule fois et ne pourra pas être récupérée ultérieurement. Si vous perdez votre clé API, vous devrez en générer une nouvelle.

Permissions de clé API

Chaque clé API peut être configurée avec des permissions spécifiques. Les permissions disponibles incluent:

Permission	Description
`canViewOrders`	Accès en lecture aux commandes
`canUpdateOrders`	Mettre à jour les informations et les statuts des commandes
`canSendNotifications`	Envoyer des notifications aux clients (email, SMS, WhatsApp)
`canChangeOrderStatus`	Mettre à jour le statut et le sous-statut de la commande
`canOverrideProductChainEnforcement`	Contourner les règles d'application de la chaîne de produits lors de la mise à jour du statut
`canViewStatuses`	Accès en lecture aux statuts personnalisés
`canManageStatuses`	Créer, mettre à jour et supprimer des statuts personnalisés

Limitation de débit

Les requêtes API sont limitées en débit par clé API en utilisant deux fenêtres séparées:

Limite par minute: Configurable par clé (par défaut: 60 requêtes/minute)
Limite par jour: Configurable par clé (par défaut: 10 000 requêtes/jour)

Les deux limites doivent être satisfaites pour qu'une requête soit autorisée. Si l'une ou l'autre limite est dépassée, la requête sera rejetée avec un code d'état 429.

Les informations de limite de débit sont incluses dans tous les en-têtes de réponse API:

X-RateLimit-Limit-Minute: Nombre maximum de requêtes par minute
X-RateLimit-Remaining-Minute: Requêtes restantes dans la minute en cours
X-RateLimit-Reset-Minute: Horodatage Unix (secondes) de réinitialisation de la minute
X-RateLimit-Limit-Day: Nombre maximum de requêtes par jour
X-RateLimit-Remaining-Day: Requêtes restantes dans le jour en cours
X-RateLimit-Reset-Day: Horodatage Unix (secondes) de réinitialisation du jour
Retry-After: Secondes à attendre avant de réessayer (présent en cas de limitation)

Meilleures pratiques de sécurité

⚠️ Directives de sécurité importantes

Ne jamais commiter les clés API dans le contrôle de version
Stocker les clés API dans des variables d'environnement ou des systèmes de gestion de clés sécurisés
Faire une rotation des clés API régulièrement
Utiliser des clés API différentes pour différents environnements (développement, staging, production)
Révoquer immédiatement toute clé API qui pourrait avoir été compromise
Utiliser les permissions minimales nécessaires pour chaque clé API
Surveiller l'utilisation de l'API pour détecter des modèles inhabituels

Exemple de requête

Voici un exemple complet d'une requête API authentifiée:

Requête cURL authentifiée

curl -X GET "https://ultimate-custom-order-status.app.msmtech.ca/api/v1/orders?page=1&limit=25" \
  -H "X-API-Key: sk_live_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Réponses d'erreur

401 Non autorisé

Retourné lorsque la clé API est manquante ou invalide:

401 Non autorisé

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Interdit

Retourné lorsque la clé API manque de permissions requises:

403 Interdit

{
  "error": "Forbidden",
  "message": "API key does not have required permission: canViewOrders"
}