Shopadvizor API France 🇫🇷

The following document provides an overview of Shopadvizor API for developers. It describes principals, authentication details and the data available to fetch from the API.

Urls

	Production environment	Pre-production environment
Gateway	https://graphql-gateway.public.shopadvizor.com	https://graphql-gateway.prepro-public.shopadvizor.net
Oauth2	https://oauth2-service.public.shopadvizor.com/token	https://oauth2-service.prepro-public.shopadvizor.net/token

Authorization flows

To fetch the token and be able to use the API, the client must send some parameters:

1. grant_type → client_credentials
2. client_id → Provided by Shopadvizor.
3. client_secret → Provided by Shopadvizor.
4. scope → read:reviews read:rating_counters
5. user-agent → Provided by Shopadvizor.

Once the client gets the token, it will be able to use the Shopadvizor API through GraphQL request, adding this header:

Authorization: { access_token }

This token will be available during the answer. It expires in 3600 seconds from the request timestamp, once this token has expired, the request must be done again to obtain a new valid token.

Request Parameters

Shopadvizor will provide the parameters needed to make requests. If the same token is needed to access multiple scopes you can add multiple ones, leaving a space between them.

Once this data is retrieved and a POST request is sent to Shopadvizor oAuth2 service, the access token will be received to fetch data from the API:

curl --location --request POST 'https://oauth2-service.public.shopadvizor.com/token' \
  --header 'Content-Type: multipart/form-data' \
  --header 'User-Agent: #YOUR_USER_AGENT#' \
  --form 'grant_type=client_credentials' \
  --form 'client_id=#YOUR_SECRET_ID#' \
  --form 'client_secret=#YOUR_CLIENT_SECRET#' \
  --form 'scope=read:reviews read:rating_counters'

Responses

The Saz OAuth2 Service can return the following HTTP codes:

• 200 (OK) → everything was OK. Client credentials grant:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "#YOUR_ACCESS_TOKEN#"
}

• 400 (Bad Request) → the parameters sent are invalid.
• 401 (Unauthorized) → the credentials provided are invalid.

GraphQL

GraphQL is the query language used by Shopadvizor to build its API. It allows clients to get exactly what they need in each query.

With GraphQL, the client sends a query to Shopadvizor API to fetch exactly the necessary data for each query. This allows fetching different data for each view needed (mobile, desktop, etc), making applications faster and stable.

For more information about GraphQL queries and mutations, you can read the official documentation here: https://graphql.org/learn/queries/

Using GraphQL and CURL

To get the resources from Shopadvizor API, you must pass the User Agent and access token obtained previously.

Example:

curl --location --request POST 'https://graphql-gateway.public.shopadvizor.com' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer #YOUR_ACCESS_TOKEN#' \
  --header 'User-Agent: #YOUR_USER_AGENT#' \
  --data '{"query": "#YOUR_GRAPHQL_QUERY#", "variables": {#YOUR_VARIABLES#}'

Resources

Reviews

By using the publicReviews query the following data can be fetched per product´s EAN.

Information is grouped by:

• rating: Corresponds to the product rating. Also includes the NPS Net Promoter Score.
• comment: Includes the title (optional) and comment text. The product purchase date is also included.
• author: The first and last name of the comment author. For privacy reasons, the email is not returned. And only the initial of the last name is shown.

Request

GraphQL

query PublicReviews(
  $pagination: PaginationInput
  $filter: ReviewFilterInput
) {
  publicReviews(
    pagination: $pagination
    filter: $filter
  ) {
    pagination {
      count
      pages
      next
      prev
    }
    results {
      id
      rating {
        value
        nps
      }
      comment {
        title
        text
        createdAt
        updatedAt
        purchasedAt
      }
      author {
        id
        firstName
        lastName
        email
      }
    }
  }
}

Variables

{
  "pagination": {
    "page": 1,
    "limit": 10
  },
  "filter": {
    "ean": "1234567890128"
  }
}

The ean field for filter is mandatory. Results are sorted by createdAt in descending order.

Response

(it only includes the first item):

{
  "data": {
    "publicReviews": {
      "pagination": {
        "count": 15,
        "pages": 2,
        "next": 2,
        "prev": null
      },
      "results": [
        {
          "id": "8a550076-9b17-4997-ab64-29726d84f181",
          "rating": {
            "value": 4,
            "nps": 10
          },
          "comment": {
            "id": "ee5b4cdc-2ef5-4377-bc14-a4ecb29f2a99",
            "title": "Trés bon produit",
            "text": "J'ai beaucoup aimé ce produit. C'est le plus savoureux que j'ai goûté.",
            "createdAt": "2022-05-24T15:56:30+00:00",
            "updatedAt": "2022-05-24T15:56:30+00:00",
            "purchasedAt": "2019-09-02",
            "status": "PUBLISHED"
          },
          "author": {
            "id": "b02669d9-0b90-43da-b1be-8b341ab25d50",
            "firstName": "Caroline",
            "lastName": "Y.",
            "email": "c***n@shopadvizor.com"
          }
        }
      ]
    }
  }
}

Rating counters

The ratingCountersByProduct query returns the ratings of a product grouped by the rating value, that is a number between 1 and 5.

Each node includes:

• total: Total number of ratings.
• average: Average rating. Is null when the product has no ratings.
• counters: It is composed by:
  • name: The rating value: 1, 2, 3, 4 or 5.
  • ratio: Ratio of ratings.
  • count: Number of ratings.

Request

GraphQL

query RatingCountersByProduct($ean: String!) {
  ratingCountersByProduct(ean: $ean) {
    total
    average
    counters {
      name
      ratio
      count
    }
  }
}

Variables

{
  "ean": "3289196040503"
}

Only the ean field for filter is mandatory.

Response

{
  "data": {
    "ratingCountersByProduct": {
      "total": 15,
      "average": 4.4,
      "counters": [
        {
          "name": "4",
          "ratio": 0.6,
          "count": 9
        },
        {
          "name": "5",
          "ratio": 0.4,
          "count": 6
        }
      ]
    }
  }
}