Authentification à l'API

Pour utiliser l'API REST de StoreLinkr, vous devez authentifier vos requêtes à l'aide de deux en-têtes HTTP personnalisés. Ces en-têtes identifient votre application et garantissent que vous avez l'autorisation d'accéder aux données demandées.

En-têtes obligatoires

Chaque requête envoyée à l'API StoreLinkr doit contenir les en-têtes suivants :

En-tête	Description
`X-StoreLinkr-Api-Key`	Votre jeton d'API unique.
`X-StoreLinkr-Api-Secret`	Votre secret d'API privé.

Obtenir vos identifiants

Vous gérez vos identifiants d'API dans le tableau de bord StoreLinkr.

Allez dans Paramètres > Clés API.
Créez un nouveau jeu de clés ou utilisez un jeu existant.
Votre jeton d'API correspond à X-StoreLinkr-Api-Key.
Votre secret d'API correspond à X-StoreLinkr-Api-Secret.

attention

Protégez votre secret d'API ! Le secret ne doit jamais être partagé publiquement, versionné dans un dépôt de code ni exposé dans du code côté client (comme du JavaScript exécuté dans un navigateur). Si vous pensez que votre secret a été compromis, révoquez immédiatement la clé dans le tableau de bord.

Portées des clés API

Chaque clé API peut être limitée à un ensemble de portées (scopes), c'est-à-dire les actions qu'elle est autorisée à effectuer. Vous pouvez ainsi remettre une clé qui peut, par exemple, uniquement lire le stock, sans lui donner l'autorisation de modifier votre catalogue ou de lire vos commandes.

Par défaut, une nouvelle clé peut tout faire. Si vous laissez les portées vides (« Toutes les actions »), la clé a un accès complet à l'API.
Dès que vous sélectionnez une ou plusieurs portées, la clé est limitée à ces seules actions. Toute requête en dehors de ses portées est rejetée avec une erreur 403 Forbidden.

Vous gérez les portées par clé sous Paramètres > Clés API : cliquez sur une clé et cochez les actions qu'elle peut effectuer.

Portées disponibles

Portée	Autorise
`catalog:read`	Lire les produits, les catégories, les variantes et les flux.
`catalog:write`	Créer, modifier et archiver des produits et des catégories.
`ecommerce:read`	Lire les produits des canaux de vente et les règles de produit.
`ecommerce:write`	Créer, modifier et supprimer des règles de produit.
`orders:read`	Lire les commandes.
`orders:write`	Créer des commandes.
`stock:read`	Lire les informations de stock et les mouvements de stock.

astuce

Accordez à une clé le minimum d'accès dont elle a besoin. Une clé utilisée uniquement pour lire les niveaux de stock ne devrait avoir que stock:read.

Authentification de base

Au lieu des deux en-têtes, vous pouvez aussi utiliser l'authentification HTTP Basic, avec le jeton d'API comme nom d'utilisateur et le secret d'API comme mot de passe.

Pagination, limites de débit et erreurs

Pagination : les points de terminaison de liste acceptent limit et page et renvoient un objet pagination avec pages, page, limit, offset et totalRecords. Continuez à demander des pages jusqu'à atteindre pages.
Limites de débit : les requêtes sont limitées par projet. Vous pouvez envoyer une rafale de 120 requêtes au maximum, après quoi le quota se reconstitue à raison de 10 requêtes par minute. Lorsqu'il est épuisé, l'API répond 429 Too Many Requests avec un en-tête Retry-After qui contient le nombre de secondes à attendre. Utilisez des valeurs de limit plus élevées et des filtres plutôt que de nombreux petits appels.
Erreurs : une erreur a la même forme qu'une réponse réussie, avec "status": "failed", un message et un statut HTTP correspondant : 400 requête invalide, 401 clé manquante ou invalide, 403 la clé n'a pas la portée requise, 404 introuvable dans votre projet, 409 conflit avec l'état actuel, 429 limite de débit atteinte.

La documentation interactive de l'API propose un guide de démarrage rapide, tous les points de terminaison regroupés par domaine (Catalogue, eCommerce, Stock, Commandes et Flux de produits) et un bouton Télécharger pour le fichier OpenAPI, que vous pouvez utiliser pour générer un client dans votre propre langage. Elle suit le même réglage jour et nuit que le portail.

Exemples de requêtes

Avec cURL

curl -X GET "https://api.storelinkr.com/api/public/v2/catalog/products" \
     -H "X-StoreLinkr-Api-Key: your_api_token_here" \
     -H "X-StoreLinkr-Api-Secret: your_api_secret_here" \
     -H "Accept: application/json"

Avec PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('GET', 'https://api.storelinkr.com/api/public/v2/catalog/products', [
    'headers' => [
        'X-StoreLinkr-Api-Key' => 'your_api_token_here',
        'X-StoreLinkr-Api-Secret' => 'your_api_secret_here',
        'Accept' => 'application/json',
    ]
]);

$body = json_decode($response->getBody(), true);

Dépannage de l'authentification

Si vous recevez une réponse 401 Unauthorized :

Vérifiez que les deux en-têtes X-StoreLinkr-Api-Key et X-StoreLinkr-Api-Secret sont présents et correctement orthographiés.
Vérifiez que les valeurs correspondent exactement à celles affichées dans le tableau de bord StoreLinkr.
Assurez-vous que la clé API n'a pas été révoquée.
Vérifiez que vous envoyez les en-têtes avec la bonne casse (les en-têtes HTTP ne tiennent généralement pas compte de la casse, mais il est recommandé de respecter la casse standard).

En-têtes obligatoires​

Obtenir vos identifiants​

Portées des clés API​

Portées disponibles​

Authentification de base​

Pagination, limites de débit et erreurs​

Exemples de requêtes​

Avec cURL​

Avec PHP (Guzzle)​

Dépannage de l'authentification​