API partenaire

Authentification OAuth 2.0

📘

OAuth 2.0 est disponible uniquement sur le point de terminaison /ads

Lors de l'intégration des rapports sur les commandes par l'API, vous devez intégrer le point de terminaison /orders à l'aide de l'authentification de base et votre clé API secrète.

ID client et clé secrète client

L'AD_ID client_id et client_secret seront fournis par votre responsable de compte technique. La clé secrète client est privée et ne doit pas être partagée.

Émettre une requête de jetons d'accès

Pour obtenir un jeton d'accès, vous devez envoyer une requête contenant les éléments client_id et client_secret. Pour ce faire, le détaillant doit émettre une requête POST au point de terminaison du serveur d'autorisation CitrusAd :

https://$BASE_URL/v1/oauth2/token

📘

/oauth2/token ne fournit que le jeton correspondant. Ces jetons vous permettront d'interagir avec les différents points de terminaison d'intégration.

Votre demande nécessitera une autorisation de base envoyée via l'en-tête de requête d'autorisation contenant les éléments client_id et client_secret du détaillant, encodés en Base64 :

Authorization: "Basic" + base64encode(client_id + ":" + client_secret)

Vous devrez ajouter le paramètre suivant à l'aide du format application/x-www-form-urlencoded dans le corps de la requête HTTP :

grant_type=client_credentials

La requête ressemblera à ceci :

POST https://$BASE_URL/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded id+key>
grant_type=client_credentials

Recevoir un jeton d'accès

La réponse contiendra les informations suivantes

  • access_token: le jeton d'accès à utiliser lorsque vous appelez les API CitrusAd.
  • expires_in: le volume, en secondes, avant expiration du jeton d'accès.
  • token_type: le type de jeton renvoyé. Dans ce cas, le type sera toujours Bearer (Porteur).

Voici un exemple de réponse

{
  "access_token": "xxxxx.yyyyy.zzzzz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Utiliser un jeton

Pour passer des appels aux points de terminaison de l'API CitrusAd, il vous suffit d'ajouter à l'en-tête d'autorisation de la requête le jeton d'accès généré.
Authorization: “Bearer “ <access_token>

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Bearer <access_token>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["category:Cupboard/Snacks"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

Erreurs liées à la requête

Client non valide

Si les éléments client_id ou client_secret envoyés au sein de la requête sont erronés, vous recevrez la réponse suivante :

{
  "error": "invalid_client"
}

Vérifiez que les identifiants que vous utilisez sont corrects. Vérifiez de nouveau votre client_id et client_secret et assurez-vous d'utiliser correctement l'autorisation de base lorsque vous appelez le point de terminaison /token.
##Requête non valide
Une erreur de requête non valide sera renvoyée par le serveur d'autorisation si un paramètre requis est absent de la requête, ou si cette dernière contient une valeur de paramètre non valide, un paramètre présent plusieurs fois ou un paramètre malformé.

{
  "error": "invalid_request"
}

Assurez-vous de :

  • Inclure uniquement grant_type=client_credentials au corps de la requête
  • Définir le bon Content-Type pour l'en-tête de la requête