ShopAdvizor API
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
Authentication
Access to the Shopadvizor API requires an authorization token. Shopadvizor authentication process uses OAuth2 Services following OAuth2 Standards.
- OAuth2 official documentation: https://oauth.net/2/
- Helpful documentation to understand OAuth2 flow: https://auth0.com/docs/authorization
Authorization flows
To fetch the token and be able to use the API, the client must send some parameters:
grant_type→client_credentialsclient_id→ Provided by Shopadvizor.client_secret→ Provided by Shopadvizor.scope→read:reviews read:rating_countersuser-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
}
}
}
}
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."
}
}
]
}
}
}
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. Isnullwhen the product has no ratings.counters: It is composed by:name: The rating value:1,2,3,4or5.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
}
]
}
}
}