@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Reviews and Ratings API
@base https://storecomponents.myvtex.com
@version 1.0
@auth ApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header
@common_fields {Content-Type: str=application/json # Describes the type of the content being sent., Accept: str=application/json # HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.}
@endpoints 8
@toc reviews-and-ratings(8)

@endpoint GET /reviews-and-ratings/api/rating/{productId}
@desc Get product rating
@required {productId: str # Product ID.}
@returns(200) {average: num, totalCount: num, starsFive: num, starsFour: num, starsThree: num, starsTwo: num, starsOne: num} # OK
@errors {404: Not Found}

@endpoint GET /reviews-and-ratings/api/review/{reviewId}
@desc Get product review by review ID
@required {reviewId: str # Review ID.}
@returns(200) {id: str, productId: str, rating: num, title: str, text: str, reviewerName: str, shopperId: str, reviewDateTime: str, searchDate: str, verifiedPurchaser: bool, sku: str?, approved: bool, location: str?, locale: str?, pastReviews: str?} # OK
@errors {404: Not Found, 500: Internal Server Error}

@endpoint DELETE /reviews-and-ratings/api/review/{reviewId}
@desc Delete review
@required {reviewId: str # Review ID.}
@returns(200) OK

@endpoint PATCH /reviews-and-ratings/api/review/{reviewId}
@desc Update a review
@required {reviewId: str # Review ID., productId: str # Product ID., rating: num # Customer rating., title: str # Review's title., text: str # Review's text., reviewerName: str # Reviewer name.}
@optional {shopperId: str # Shopper email., verifiedPurchaser: bool # Indicates if the reviewer is a verified purchaser (`true`) or not (`false`)., locale: str # Review's locale.}
@returns(200) {id: str, productId: str, rating: num, title: str, text: str, reviewerName: str, shopperId: str, reviewDateTime: str, searchDate: str, verifiedPurchaser: bool, sku: str?, approved: bool, location: str?, locale: str?, pastReviews: str?} # OK
@example_request {"productId":"1","rating":5,"title":"Great product","text":"Great product.","reviewerName":"Arturo","shopperId":"user@email.com","verifiedPurchaser":false,"locale":"en-US"}

@endpoint GET /reviews-and-ratings/api/reviews
@desc Get list of reviews
@optional {search_term: str # Returns Reviews that contain the search term in `productId`, `sku`, `shopperId`, or `reviewerName`., from: str # Zero base starting record number, `0` is the default value., to: str # Zero base ending record number, `3` is the default value., order_by: str # Field name to order records. The field name must have the first letter uppercase. Allowed field names: `ProductId`, `ShopperId`, `Approved`, `ReviewDateTime`, `SearchDate`, `Rating`, `Locale`. Optionally add `:asc` or `:desc`., status: bool # Status of the review, approved (`true`) or not (`false`)., product_id: str # Filter the reviews by product ID.}
@returns(200) {data: [map], range: map{total: num, from: num, to: num}} # OK

@endpoint POST /reviews-and-ratings/api/reviews
@desc Create multiple reviews
@returns(200) OK
@example_request [{"id":"1","productId":"65444","rating":4,"title":"Great product","text":"Great product!","reviewerName":"Arturo","approved":true},{"id":"2","productId":"65444","rating":4,"title":"Great product","text":"Great product!","reviewerName":"Arturo","approved":true}]

@endpoint DELETE /reviews-and-ratings/api/reviews
@desc Delete multiple reviews
@returns(200) OK
@example_request ["babefcf4-e0f7-11ec-835d-16c4e59c4351","c123def5-e0f7-11ec-835d-16c4e59c4352"]

@endpoint POST /reviews-and-ratings/api/review
@desc Create a review
@required {productId: str # Product ID., rating: int(int32) # Customer rating., title: str # Review's title., text: str # Review's text., reviewerName: str # Reviewer name., approved: bool # Indicates if the review was approved (`true`) or not (`false`).}
@returns(200) {id: str, productId: str, rating: num, title: str, text: str, reviewerName: str, shopperId: str, reviewDateTime: str, searchDate: str, verifiedPurchaser: bool, sku: str?, approved: bool, location: str?, locale: str?, pastReviews: str?} # OK
@example_request {"productId":"65444","rating":5,"title":"Good Product","text":"It is the best product that I have seen","reviewerName":"Arturo","approved":true}

@end