openapi: 3.0.3
info:
title: 'Rec.Reviews API Documentation'
description: 'This API allows for the usage of the Rec.Reviews service in a custom integration. All fields are required unless stated otherwise.'
version: 1.0.0
servers:
-
url: 'https://dashboard.recreviews.com'
paths:
/api/shop:
get:
summary: 'Get current ID'
operationId: getCurrentID
description: 'Returns the shop ID for the currently authentified subscription, if any'
parameters: []
responses:
500:
description: ''
content:
application/json:
schema:
type: object
example:
message: 'Server Error'
properties:
message:
type: string
example: 'Server Error'
tags:
- Shop
/api/shop/configuration:
get:
summary: 'Get configuration'
operationId: getConfiguration
description: 'Returns the configuration of the authentified shop'
parameters: []
responses:
500:
description: ''
content:
application/json:
schema:
type: object
example:
message: 'Server Error'
properties:
message:
type: string
example: 'Server Error'
tags:
- Shop
/api/module/configuration:
post:
summary: 'Update configuration'
operationId: updateConfiguration
description: "Updates the shop's stored configuration. Must be called on each configuration update on your side."
parameters: []
responses:
500:
description: ''
content:
application/json:
schema:
type: object
example:
message: 'Server Error'
properties:
message:
type: string
example: 'Server Error'
tags:
- Shop
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
configuration:
type: object
description: 'An object containing the configuration of the shop.'
example: []
properties:
name:
type: string
description: 'The name of the shop. This value will be used for both display and emails content.'
example: 'My shop'
cmsName:
type: string
description: 'The name of the CMS, if any.'
example: PrestaShop
enum:
- PrestaShop
- Magento
- WooCommerce
- Shopify
- 'PrestaShop (RBM)'
cmsVersion:
type: string
description: 'The version of the CMS, if any.'
example: 8.1.1
websiteUrl:
type: string
description: 'The URL of the website. Must be a valid URL.'
example: 'https://recreviews.com'
logoUrl:
type: string
description: 'The direct URL to the shop logo. Must be a valid URL.'
example: 'https://recreviews.com/img/logo_bleu.png'
initialDelay:
type: integer
description: 'The number of days to wait after a command has been marked as valid before we send the initial rating invitation. Must be at least 1.'
example: 3
reminderDelay:
type: integer
description: 'The number of days to wait after the initial invitation before we send a reminder (0 to disable reminder). Must be at least 0.'
example: 5
color:
type: string
description: 'The HEX color code of the shop. This color will be used for the border of video reviews, and cannot be modified on already recorded reviews.'
example: '#ff0000'
PVR_STATUS_SELECTION:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 1
PVR_ENABLE_VOUCHER:
type: boolean
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: false
PVR_VOUCHER_PREFIX:
type: string
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: molestias
PVR_VOUCHER_TYPE:
type: string
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: itaque
PVR_VOUCHER_AMOUNT:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 3
PVR_VOUCHER_PERCENT:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 10
PVR_VOUCHER_CURRENCY:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magentod.'
example: 6
PVR_VOUCHER_CURRENCY_CODE:
type: string
description: 'This field is required when configuration.cmsName is PrestaShop or Magento. Must be 3 characters.'
example: elm
PVR_VOUCHER_TAX:
type: boolean
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: true
PVR_VOUCHER_DESC:
type: string
description: ''
example: ut
PVR_VOUCHER_GENERATE:
type: string
description: ''
example: eos
PVR_VOUCHER_QTY:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 10
PVR_VOUCHER_MIN_AMOUNT:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 4
PVR_VOUCHER_MIN_AMOUNT_DESC:
type: array
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example:
- ipsam
items:
type: string
PVR_VOUCHER_VALIDITY:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 19
PVR_VOUCHER_HIGHLIGHT:
type: boolean
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: true
PVR_VOUCHER_CUMULATE:
type: boolean
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: true
PVR_VOUCHER_INCENTIVE_TEXT:
type: array
description: ''
example:
- velit
items:
type: string
PVR_PRODUCT_REVIEW_LINES:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 19
PVR_PRODUCT_NB_LOAD_ITEM:
type: integer
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: 11
PVR_ENABLE_BATTLE:
type: boolean
description: 'This field is required when configuration.cmsName is PrestaShop or Magento.'
example: false
required:
- configuration
/api/orders:
post:
summary: 'Create an order'
operationId: createAnOrder
description: 'Creates a new order and its associated customer and products with the provided data'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
order:
type: object
description: 'An object describing the order.'
example: []
properties:
reference:
type: string
description: 'The reference of the order.'
example: AZE001
validStatus:
type: boolean
description: 'Whether this order should be considered as valid, meaning we can start notifying the customer to get a rating after the configured delay has elapsed. If this value is set to true, the "Update order status" call is not required to mark the order as ready.'
example: true
order_date:
type: string
description: 'The order date in the "Y-m-d H:i:s" format. Must be a valid date.'
example: '1970-01-01 12:00:00'
products:
type: array
description: ''
example:
- []
items:
type: object
properties:
id:
type: integer
description: 'The product ID, as an integer.'
example: 7
name:
type: string
description: 'The name of the product.'
example: 'My product name'
image:
type: string
description: 'The URL to the main image of the product. Must be a valid URL.'
example: 'https://mywebsite.com/myproductpage/myimage.png'
price:
type: number
description: "The price of the product, as a numeric value. The format must comply with PHP's `is_numeric`."
example: 777.0
currency:
type: string
description: 'The currency of the order, in the ISO 4217 format (EUR, USD, etc...).'
example: EUR
ratingUrl:
type: string
description: 'An URL pointing to the page where the product can be rated. Must be a valid URL.'
example: 'https://mywebsite.com/myproductpage'
required:
- id
- name
- image
- price
- currency
customer:
type: object
description: 'An object describing the customer.'
example: []
properties:
id:
type: integer
description: 'The ID of the customer, as an integer.'
example: 7
first_name:
type: string
description: 'The first name of the customer.'
example: Sylvester
last_name:
type: string
description: 'The last name of the customer.'
example: Stallone
email:
type: string
description: 'The email address of the customer. Must be a valid email address.'
example: example@recreviews.com
birthdate:
type: string
description: 'The customer birthdate, in the "Y-m-d" format. Must be a valid date.'
example: '1970-01-01'
gender:
type: string
description: 'The gender of the customer. Accepted values: M, F.'
example: M
enum:
- M
- F
lang:
type: string
description: "The lang in which we'll contact the customer. Accepted values: fr, en."
example: en
id_shop_lang:
type: integer
description: 'The ID lang of the customer in the shop, if available.'
example: 1
phone:
type: string
description: 'The phone number of the customer.'
example: '+33699999999'
required:
- order
- customer
get:
summary: 'Get orders without reviews'
operationId: getOrdersWithoutReviews
description: 'Returns the orders of a shop that have no reviews'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Orders
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
idCustomer:
type: integer
description: ''
example: 12
minDate:
type: string
description: 'Must be a valid date.'
example: '2025-01-22T14:38:12'
/api/orders/status:
post:
summary: 'Update order status'
operationId: updateOrderStatus
description: "Updates the status of the order to allow for rating reminders to be sent\nIf the status is valid, this call will automatically create a review for each product in the order, making the\nrecorder URL available when fetching reviews right away\nIf the order was already created with the `validStatus` field set to true, this request is not required."
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
error: 'Unknown order'
properties:
result:
type: boolean
example: false
error:
type: string
example: 'Unknown order'
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
order:
type: object
description: 'An object containing the order details we need.'
example: []
properties:
reference:
type: string
description: 'The reference of the order.'
example: AZE001
validStatus:
type: boolean
description: 'Whether this order should be considered as valid, meaning we can start notifying the customer for a rating.'
example: false
required:
- order
/api/orders/vouchers:
get:
summary: 'Get vouchers'
operationId: getVouchers
description: 'Returns the vouchers associated to the orders of the shop'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Orders
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
idCustomer:
type: integer
description: ''
example: 11
minDate:
type: string
description: 'Must be a valid date.'
example: '2025-01-22T14:38:12'
/api/orders/voucher:
post:
summary: 'Update order voucher'
operationId: updateOrderVoucher
description: 'Updates the voucher information of the orders to be sent'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
error: 'Unknown order'
properties:
result:
type: boolean
example: false
error:
type: string
example: 'Unknown order'
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
order:
type: object
description: ''
example: []
properties:
reference:
type: string
description: ''
example: repellendus
voucher:
type: object
description: ''
example: null
properties:
code:
type: string
description: 'This field is required when voucher is present.'
example: quam
percentage:
type: string
description: 'This field is required when voucher.amount is not present.'
example: voluptas
amount:
type: number
description: 'This field is required when voucher.percentage is not present.'
example: 546.477
currency:
type: string
description: 'This field is required when voucher is present.'
example: nesciunt
tax:
type: boolean
description: 'This field is required when voucher is present.'
example: true
min_amount:
type: number
description: 'This field is required when voucher is present.'
example: 16216.2
validity:
type: string
description: 'Must be a valid date. This field is required when voucher is present.'
example: '2025-01-22T14:38:12'
mode:
type: string
description: 'The type of voucher (`customer`, `order` or `product`)'
example: customer
required:
- order
/api/reviews:
get:
summary: 'Get reviews'
operationId: getReviews
description: "Returns all of the shop's reviews that have a video"
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: true
reviews:
-
id: 59ff99be-4c2b-4687-b152-2f3061bfe50b
date: '2021-06-24T13:26:41.000000Z'
published_at: null
unpublished_at: null
previous_id_review: null
recorder_url: 'https://recorder_url'
video_url: 'https://video_url.mp4'
thumbnail_url: 'https://thumbnail_url.png'
preview_url: 'https://preview_url.mp4'
rating: 5
is_demo_review: true
id_order_product: 2
order_reference: JYQFCSHDW
id_customer: 144
product:
name: 'Product name'
author:
email: test@test.com
first_name: Jean
last_name: Bon
properties:
result:
type: boolean
example: true
reviews:
type: array
example:
-
id: 59ff99be-4c2b-4687-b152-2f3061bfe50b
date: '2021-06-24T13:26:41.000000Z'
published_at: null
unpublished_at: null
previous_id_review: null
recorder_url: 'https://recorder_url'
video_url: 'https://video_url.mp4'
thumbnail_url: 'https://thumbnail_url.png'
preview_url: 'https://preview_url.mp4'
rating: 5
is_demo_review: true
id_order_product: 2
order_reference: JYQFCSHDW
id_customer: 144
product:
name: 'Product name'
author:
email: test@test.com
first_name: Jean
last_name: Bon
items:
type: object
properties:
id:
type: string
example: 59ff99be-4c2b-4687-b152-2f3061bfe50b
date:
type: string
example: '2021-06-24T13:26:41.000000Z'
published_at:
type: string
example: null
unpublished_at:
type: string
example: null
previous_id_review:
type: string
example: null
recorder_url:
type: string
example: 'https://recorder_url'
video_url:
type: string
example: 'https://video_url.mp4'
thumbnail_url:
type: string
example: 'https://thumbnail_url.png'
preview_url:
type: string
example: 'https://preview_url.mp4'
rating:
type: integer
example: 5
is_demo_review:
type: boolean
example: true
id_order_product:
type: integer
example: 2
order_reference:
type: string
example: JYQFCSHDW
id_customer:
type: integer
example: 144
product:
type: object
properties:
name:
type: string
example: 'Product name'
author:
type: object
properties:
email:
type: string
example: test@test.com
first_name:
type: string
example: Jean
last_name:
type: string
example: Bon
tags:
- Reviews
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
min_date:
type: string
description: 'Must be a valid date.'
example: '2025-01-22T14:38:12'
id_customer:
type: integer
description: ''
example: 11
published:
type: boolean
description: ''
example: false
deleted:
type: boolean
description: ''
example: true
post:
summary: 'Create a review'
operationId: createAReview
description: 'Creates a new review entry and returns the URL to use to record the video review'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
error: 'Unknown product'
properties:
result:
type: boolean
example: false
error:
type: string
example: 'Unknown product'
tags:
- Reviews
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id_customer:
type: integer
description: ''
example: 6
order_reference:
type: string
description: ''
example: qui
id_product:
type: integer
description: ''
example: 10
rating:
type: integer
description: 'Must be between 0 and 5.'
example: 0
previous_id_review:
type: string
description: 'Must be a valid UUID.'
example: 382e9ec5-b690-3074-81d0-5103386dfd03
required:
- id_customer
- order_reference
- id_product
- rating
parameters:
-
in: path
name: min_date
description: 'Optional parameter. Minimal creation date for the reviews to retrieve'
required: true
schema:
type: string
examples:
omitted:
summary: 'When the value is omitted'
value: ''
present:
summary: 'When the value is present'
value: libero
-
in: path
name: id_customer
description: 'Optional parameter. The customer ID to retrieve the reviews of'
required: true
schema:
type: integer
examples:
omitted:
summary: 'When the value is omitted'
value: ''
present:
summary: 'When the value is present'
value: 19
-
in: path
name: published
description: 'Optional parameter. boolean Provide this value to get only published or unpublished reviews. Leave to null to fetch whatever their status might be.'
required: true
schema:
type: string
examples:
omitted:
summary: 'When the value is omitted'
value: ''
present:
summary: 'When the value is present'
value: velit
-
in: path
name: deleted
description: 'Optional parameter. boolean Provide this value to get only deleted/declined reviews. Leave to null to fetch whatever their status might be.'
required: true
schema:
type: string
examples:
omitted:
summary: 'When the value is omitted'
value: ''
present:
summary: 'When the value is present'
value: in
'/api/reviews/{deleted_review}/publish-deleted':
post:
summary: 'Publish a deleted review'
operationId: publishADeletedReview
description: 'Marks the received review as published again, restores the video.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Reviews
parameters:
-
in: path
name: deleted_review
description: ''
example: 00011578-dcde-4a7e-a8ed-ff5ec221a8b1
required: true
schema:
type: string
-
in: path
name: review
description: 'The ID of the review to re-publish'
example: 59ff99be-4c2b-4687-b152-2f3061bfe50b
required: true
schema:
type: string
'/api/reviews/{review_id}/publish':
post:
summary: 'Publish a review'
operationId: publishAReview
description: 'Marks the received review as published, setting the required fields on the entity.'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Reviews
parameters:
-
in: path
name: review_id
description: 'The ID of the review.'
example: 00011578-dcde-4a7e-a8ed-ff5ec221a8b1
required: true
schema:
type: string
-
in: path
name: review
description: 'The ID of the review to publish'
example: 59ff99be-4c2b-4687-b152-2f3061bfe50b
required: true
schema:
type: string
'/api/reviews/{review_id}/unpublish':
post:
summary: 'Unpublish a review'
operationId: unpublishAReview
description: 'Unpublishes the received review'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Reviews
parameters:
-
in: path
name: review_id
description: 'The ID of the review.'
example: 00011578-dcde-4a7e-a8ed-ff5ec221a8b1
required: true
schema:
type: string
-
in: path
name: review
description: 'The ID of the review to unpublish'
example: 59ff99be-4c2b-4687-b152-2f3061bfe50b
required: true
schema:
type: string
'/api/reviews/{review_id}/decline':
post:
summary: 'Decline a review'
operationId: declineAReview
description: 'Declines a review and remove its associated video'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Reviews
parameters:
-
in: path
name: review_id
description: 'The ID of the review.'
example: 00011578-dcde-4a7e-a8ed-ff5ec221a8b1
required: true
schema:
type: string
-
in: path
name: review
description: 'The ID of the review to decline'
example: 59ff99be-4c2b-4687-b152-2f3061bfe50b
required: true
schema:
type: string
'/api/reviews/{review_id}':
get:
summary: 'Get a review'
operationId: getAReview
description: 'Returns the details of the review having the provided ID'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Reviews
post:
summary: 'Update a rating'
operationId: updateARating
description: 'Updates the rating of a review'
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Reviews
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rating:
type: integer
description: 'The new rating, on a scale from 0 to 5.'
example: 5
required:
- rating
parameters:
-
in: path
name: review_id
description: 'The ID of the review.'
example: 00011578-dcde-4a7e-a8ed-ff5ec221a8b1
required: true
schema:
type: string
-
in: path
name: review
description: 'The ID of the review for which we want details'
example: 59ff99be-4c2b-4687-b152-2f3061bfe50b
required: true
schema:
type: string
'/api/reviews/updated/{review_id}':
get:
summary: 'Get an updated review'
operationId: getAnUpdatedReview
description: "Returns the new review details based on the previous review's ID.\nThis endpoint can be used to retrieve the details of the review that replaces a previous one\n(e.g. when a customer changes their review)"
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
result: false
properties:
result:
type: boolean
example: false
tags:
- Reviews
parameters:
-
in: path
name: review_id
description: 'The ID of the review.'
example: 00011578-dcde-4a7e-a8ed-ff5ec221a8b1
required: true
schema:
type: string
-
in: path
name: review
description: 'The ID of the old review'
example: unde
required: true
schema:
type: string
tags:
-
name: Shop
description: ''
-
name: Orders
description: ''
-
name: Reviews
description: ''
components:
securitySchemes:
default:
type: http
scheme: bearer
description: "You can create an API token on your subscription's details page, by enabling Custom Integration."
security:
-
default: []