diff --git a/api_calls/reference/host_reviews/create-draft-request.json b/api_calls/reference/host_reviews/create-draft-request.json new file mode 100644 index 00000000..904ac7a1 --- /dev/null +++ b/api_calls/reference/host_reviews/create-draft-request.json @@ -0,0 +1,10 @@ +{ + "host_reviews": [ + { + "comment": "It was awesome!", + "expires_at": "2021-06-07T12:00:00Z", + "source_id": 1, + "shareable": false + } + ] +} diff --git a/api_calls/reference/host_reviews/create-submitted-request.json b/api_calls/reference/host_reviews/create-submitted-request.json new file mode 100644 index 00000000..c2b26f13 --- /dev/null +++ b/api_calls/reference/host_reviews/create-submitted-request.json @@ -0,0 +1,29 @@ +{ + "host_reviews": [ + { + "comment": "Awesome guest", + "submitted_at": "2020-06-06T12:00:00Z", + "expires_at": "2020-06-07T12:00:00Z", + "is_guest_recommended": true, + "shareable": false, + "comment": "It was awesome!", + "source_id": 1, + "criteria": { + "cleanliness": { + "rating": "4.5", + "comment": null + }, + "communication": { + "rating": "5.0", + "comment": null + }, + "respect_house_rules": { + "rating": "5.0", + "comment": "Everything great!" + } + } + } + ] +} + + diff --git a/api_calls/reference/host_reviews/create_update_draft_reviews_write-scope-response.json b/api_calls/reference/host_reviews/create_update_draft_reviews_write-scope-response.json new file mode 100644 index 00000000..1d3b1102 --- /dev/null +++ b/api_calls/reference/host_reviews/create_update_draft_reviews_write-scope-response.json @@ -0,0 +1,35 @@ +{ + "links": { + "host_reviews.source": "https://www.bookingsync.com/api/v3/sources/{host_reviews.source}", + "host_reviews.booking": "https://www.bookingsync.com/api/v3/bookings/{host_reviews.booking}", + "host_reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{host_reviews.rental}", + "host_reviews.account": "https://www.bookingsync.com/api/v3/accounts/{host_reviews.account}", + "host_reviews.reply": "https://www.bookingsync.com/api/v3/review_replies/{host_reviews.reply}" + }, + "host_reviews": [ + { + "links": { + "account": 1, + "booking": 96, + "rental": 1, + "reply": null, + "source": 1 + }, + "id": "04356dc9-1349-4e05-b818-09ccdac8d5dd", + "comment": "It was awesome!", + "private_comment": null, + "shareable": false, + "criteria": { + "cleanliness": null, + "communication": null, + "respect_house_rules": null + }, + "submitted_at": null, + "is_guest_recommended": null, + "expires_at": "2021-06-07T12:00:00Z", + "created_at": "CREATED_AT", + "updated_at": "UPDATED_AT" + } + ], + "meta": {} +} diff --git a/api_calls/reference/host_reviews/public-scope-response.json b/api_calls/reference/host_reviews/public-scope-response.json new file mode 100644 index 00000000..8936837f --- /dev/null +++ b/api_calls/reference/host_reviews/public-scope-response.json @@ -0,0 +1,34 @@ +{ + "links": { + "host_reviews.source": "https://www.bookingsync.com/api/v3/sources/{host_reviews.source}", + "host_reviews.booking": "https://www.bookingsync.com/api/v3/bookings/{host_reviews.booking}", + "host_reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{host_reviews.rental}", + "host_reviews.account": "https://www.bookingsync.com/api/v3/accounts/{host_reviews.account}", + "host_reviews.reply": "https://www.bookingsync.com/api/v3/review_replies/{host_reviews.reply}" + }, + "host_reviews": [ + { + "links": { + "account": 1, + "booking": 96, + "rental": 1, + "reply": null, + "source": 1 + }, + "id": "04356dc9-1349-4e05-b818-09ccdac8d5dd", + "comment": "Awesome\n place", + "shareable": true, + "criteria": { + "cleanliness": { "rating": "4.5", "comment": null }, + "communication": null, + "respect_house_rules": { "rating": "5.0", "comment": "Everything great!" } + }, + "submitted_at": null, + "is_guest_recommended": true, + "expires_at": "2021-06-07T12:00:00Z", + "created_at": "CREATED_AT", + "updated_at": "UPDATED_AT" + } + ], + "meta": {} +} diff --git a/api_calls/reference/host_reviews/reviews_write-scope-response.json b/api_calls/reference/host_reviews/reviews_write-scope-response.json new file mode 100644 index 00000000..c09ff410 --- /dev/null +++ b/api_calls/reference/host_reviews/reviews_write-scope-response.json @@ -0,0 +1,35 @@ +{ + "links": { + "host_reviews.source": "https://www.bookingsync.com/api/v3/sources/{host_reviews.source}", + "host_reviews.booking": "https://www.bookingsync.com/api/v3/bookings/{host_reviews.booking}", + "host_reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{host_reviews.rental}", + "host_reviews.account": "https://www.bookingsync.com/api/v3/accounts/{host_reviews.account}", + "host_reviews.reply": "https://www.bookingsync.com/api/v3/review_replies/{host_reviews.reply}" + }, + "host_reviews": [ + { + "links": { + "account": 1, + "booking": 96, + "rental": 1, + "reply": null, + "source": 1 + }, + "id": "04356dc9-1349-4e05-b818-09ccdac8d5dd", + "comment": "Awesome\n place", + "private_comment": null, + "shareable": true, + "criteria": { + "cleanliness": { "rating": "4.5", "comment": null }, + "communication": null, + "respect_house_rules": { "rating": "5.0", "comment": "Everything great!" } + }, + "submitted_at": null, + "is_guest_recommended": true, + "expires_at": "2021-06-07T12:00:00Z", + "created_at": "CREATED_AT", + "updated_at": "UPDATED_AT" + } + ], + "meta": {} +} diff --git a/api_calls/reference/host_reviews/submit-draft-request.json b/api_calls/reference/host_reviews/submit-draft-request.json new file mode 100644 index 00000000..19a6cc3a --- /dev/null +++ b/api_calls/reference/host_reviews/submit-draft-request.json @@ -0,0 +1,27 @@ +{ + "host_reviews": [ + { + "comment": "Awesome guest", + "submitted_at": "2020-06-06T12:00:00Z", + "expires_at": "2020-06-07T12:00:00Z", + "is_guest_recommended": true, + "comment": "It was awesome!", + "criteria": { + "cleanliness": { + "rating": "4.5", + "comment": null + }, + "communication": { + "rating": "5.0", + "comment": null + }, + "respect_house_rules": { + "rating": "5.0", + "comment": "Everything great!" + } + } + } + ] +} + + diff --git a/api_calls/reference/host_reviews/submit_reviews_write-scope-response.json b/api_calls/reference/host_reviews/submit_reviews_write-scope-response.json new file mode 100644 index 00000000..7b871de5 --- /dev/null +++ b/api_calls/reference/host_reviews/submit_reviews_write-scope-response.json @@ -0,0 +1,44 @@ +{ + "links": { + "host_reviews.source": "https://www.bookingsync.com/api/v3/sources/{host_reviews.source}", + "host_reviews.booking": "https://www.bookingsync.com/api/v3/bookings/{host_reviews.booking}", + "host_reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{host_reviews.rental}", + "host_reviews.account": "https://www.bookingsync.com/api/v3/accounts/{host_reviews.account}", + "host_reviews.reply": "https://www.bookingsync.com/api/v3/review_replies/{host_reviews.reply}" + }, + "host_reviews": [ + { + "links": { + "account": 1, + "booking": 96, + "rental": 1, + "reply": null, + "source": 1 + }, + "id": "04356dc9-1349-4e05-b818-09ccdac8d5dd", + "comment": "It was awesome!", + "private_comment": null, + "shareable": false, + "criteria": { + "cleanliness": { + "rating": "4.5", + "comment": null + }, + "communication": { + "rating": "5.0", + "comment": null + }, + "respect_house_rules": { + "rating": "5.0", + "comment": "Everything great!" + } + }, + "submitted_at": "2020-06-06T12:00:00Z", + "is_guest_recommended": true, + "expires_at": "2021-06-07T12:00:00Z", + "created_at": "CREATED_AT", + "updated_at": "UPDATED_AT" + } + ], + "meta": {} +} diff --git a/api_calls/reference/host_reviews/update-draft-request.json b/api_calls/reference/host_reviews/update-draft-request.json new file mode 100644 index 00000000..30113086 --- /dev/null +++ b/api_calls/reference/host_reviews/update-draft-request.json @@ -0,0 +1,9 @@ +{ + "host_reviews": [ + { + "comment": "It was awesome!" + } + ] +} + + diff --git a/api_calls/reference/review_replies/create-request.json b/api_calls/reference/review_replies/create-request.json new file mode 100644 index 00000000..67b44434 --- /dev/null +++ b/api_calls/reference/review_replies/create-request.json @@ -0,0 +1,7 @@ +{ + "review_replies": [ + { + "message": "Merci!" + } + ] +} diff --git a/api_calls/reference/review_replies/public-reviews_write-scope-response.json b/api_calls/reference/review_replies/public-reviews_write-scope-response.json new file mode 100644 index 00000000..062e560f --- /dev/null +++ b/api_calls/reference/review_replies/public-reviews_write-scope-response.json @@ -0,0 +1,23 @@ +{ + "links": { + "review_replies.booking": "https://www.bookingsync.com/api/v3/bookings/{review_replies.booking}", + "review_replies.host_review": "https://www.bookingsync.com/api/v3/rentals/{review_replies.host_review}", + "review_replies.review": "https://www.bookingsync.com/api/v3/rentals/{review_replies.review}", + "review_replies.account": "https://www.bookingsync.com/api/v3/rentals/{review_replies.account}" + }, + "review_replies": [ + { + "links": { + "host_review": "96f9e3f1-ed2a-4c8c-8e2f-1d3e1d0c8356", + "review": null, + "booking": 4, + "account": 1 + }, + "id": "c7bd77d3-0c74-4da8-8a64-5461f80ff81b", + "reply": "Merci!", + "replied_at": "CREATED_AT", + "created_at": "CREATED_AT", + "updated_at": "UPDATED_AT" + } + ] +} diff --git a/api_calls/reference/review_replies/reply_to_guest_public-reviews_write-scope-response.json b/api_calls/reference/review_replies/reply_to_guest_public-reviews_write-scope-response.json new file mode 100644 index 00000000..fd3b85d9 --- /dev/null +++ b/api_calls/reference/review_replies/reply_to_guest_public-reviews_write-scope-response.json @@ -0,0 +1,23 @@ +{ + "links": { + "review_replies.booking": "https://www.bookingsync.com/api/v3/bookings/{review_replies.booking}", + "review_replies.host_review": "https://www.bookingsync.com/api/v3/rentals/{review_replies.host_review}", + "review_replies.review": "https://www.bookingsync.com/api/v3/rentals/{review_replies.review}", + "review_replies.account": "https://www.bookingsync.com/api/v3/rentals/{review_replies.account}" + }, + "review_replies": [ + { + "links": { + "host_review": null, + "review": 14, + "booking": 4, + "account": 1 + }, + "id": "c7bd77d3-0c74-4da8-8a64-5461f80ff81b", + "reply": "Merci!", + "replied_at": "CREATED_AT", + "created_at": "CREATED_AT", + "updated_at": "UPDATED_AT" + } + ] +} diff --git a/api_calls/reference/reviews/create-request.json b/api_calls/reference/reviews/create-request.json index 841efdbb..3b9beb5e 100644 --- a/api_calls/reference/reviews/create-request.json +++ b/api_calls/reference/reviews/create-request.json @@ -1,9 +1,26 @@ { "reviews": [ { - "comment": "It was awesome!", - "rating": 5, - "title": "Awesome" + "comment": "Amazing stay", + "private_comment": "I left my glasses", + "submitted_at": "2020-06-06T12:00:00Z", + "rating": 4.6, + "shareable": false, + "source_id": 1, + "criteria": { + "cleanliness": { + "rating": "4.5", + "comment": null + }, + "communication": { + "rating": "5.0", + "comment": null + }, + "value_for_money": { + "rating": "4.0", + "comment": "A bit too expansive" + } + } } ] } diff --git a/api_calls/reference/reviews/public-reviews_write-scope-response.json b/api_calls/reference/reviews/public-reviews_write-scope-response.json index 5a9d5b08..fadd4964 100644 --- a/api_calls/reference/reviews/public-reviews_write-scope-response.json +++ b/api_calls/reference/reviews/public-reviews_write-scope-response.json @@ -1,22 +1,51 @@ { "links": { + "reviews.source": "https://www.bookingsync.com/api/v3/sources/{reviews.source}", + "reviews.reply": "https://www.bookingsync.com/api/v3/review_replies/{reviews.reply}", "reviews.booking": "https://www.bookingsync.com/api/v3/bookings/{reviews.booking}", - "reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{reviews.rental}" + "reviews.rental": "https://www.bookingsync.com/api/v3/rentals/{reviews.rental}", + "reviews.account": "https://www.bookingsync.com/api/v3/accounts/{reviews.account}" }, "reviews": [ { "links": { - "rental": 87, - "booking": 4 + "account": 11375, + "booking": 15447834, + "rental": 115170, + "reply": null, + "source": 1 }, - "id": 1, + "id": 4211675, "rating": 5, - "comment": "It was awesome!", - "name": "John S.", - "title": "Awesome", - "country_code": "FR", + "comment": "Amazing stay", + "name": null, + "title": "Amazing stay", + "country_code": null, "created_at": "CREATED_AT", - "updated_at": "UPDATED_AT" + "updated_at": "UPDATED_AT", + "rating_accurate": "4.6", + "shareable": false, + "private_comment": "I left my glasses", + "criteria": { + "cleanliness": { + "rating": "4.5", + "comment": null + }, + "checkin": null, + "communication": { + "rating": "5.0", + "comment": null + }, + "location": null, + "facilities": null, + "comfort": null, + "staff": null, + "value_for_money": { + "rating": "4.0", + "comment": "A bit too expansive" + }, + "accuracy": null + } } ] } diff --git a/content/guides/reviews.md b/content/guides/reviews.md new file mode 100644 index 00000000..33bbec63 --- /dev/null +++ b/content/guides/reviews.md @@ -0,0 +1,49 @@ +# Reviews + +## Key concepts + +- HostReview: Host reviews the guest. it may have one of two states: + - draft - either empty shell or review that was filled partially. It has little validation and can be modified any number of times. Identified by: `null` value of a `submitted_at` attribute + - submitted - final version of a review, it can no longer be modified. Identified by: `non-null` value of a `submitted_at` attribute +- Review: Guest reviews the host. +- ReviewReply - response from reviewee to reviewer's comment. + +## Restrictions + +- Both `HostReview` and `Review` may have only **one** reply. +- Each `Booking` can have only one `HostReview`. `HostReview` must have the same source as the `Booking`. +- Each `Booking` can have multiple `Reviews` (one per `source`). +- `Review` left via BookingSync website (called `direct`) will be associated with a source named `Smily`. +- Accounts on the old pricing plan have no access to new features. If that's the case you'll receive a `403` response with a `"Feature not available - insufficient account subscription plan"` message. +- Whenever booking has the `shareable` attribute set to false - it means it's not permitted to display it on any publicly accessible page. + +## Intgeration + +### Application managing reviews coming from other sources + +Possibilities depend on: + +- Installed applications +- Account subscription + +Some OTAs support only Guest Reviews (Booking.com), while others allow both host and guest to leave the review (for example, Airbnb). + +#### 1. Applications supportig only guest reviews. + +Once the booking finishes, the guest is asked to leave a review. Then the application will create the guest review on BookingSync. Depending on other installed applications and settings - guests may also be asked to leave a review directly on BookingSync, or any installed applications. That can result in a booking having multiple reviews, each having a different source. + +Guest reviews can be retrieved using [reviews endpoint](/reference/endpoints/reviews/) + +Once `Review` is created it's possible to reply to it by sending `POST` request to [review replies endpoint](/reference/endpoints/review_replies/). Note that currently, only one reply per review is allowed. + +#### 2. Applications supportig reviews from both parties + +Usually associated OTAs support double-blind reviews - which means both parties cannot see each other review until either: +- both parties fill out their reviews +- one party will not finish their review in time (it expires) + +To comply with this flow, once booking finishes OTA creates an empty shell for a host to fill out. The application will then create a host review on BookingSync in a [draft mode](/reference/endpoints/host_reviews/#create-draft-host-review) (meaning modifications are allowed), with a bare minimum of data filled out. Depending on integration it may have the `expires_at` attribute filled out, indicating the deadline for submission. + +In order to submit host review, a request to [submit draft action](/reference/endpoints/host_reviews/#submit-draft-host-review) has to be made. To satisfy any application requirements, we require all attributes (including all criteria) to be filled out. Once Host Review is submitted, it is no longer possible to modify it. + +Then, submission is handled by the application, and a corresponding guest review will be created (if already left by the guest). diff --git a/content/reference/endpoints/host_reviews.md b/content/reference/endpoints/host_reviews.md new file mode 100644 index 00000000..ca024a08 --- /dev/null +++ b/content/reference/endpoints/host_reviews.md @@ -0,0 +1,139 @@ +# Host reviews + +1. TOC +{:toc} + +### Parameters + +
+
+Group | Subgroup | Name | Type | Read/Write | Description +---------|---------------------|-----------------------|---------|------------|------------ + | | id | UUID | Read | Host Review's id. +---------|---------------------|-----------------------|---------|------------|------------ + | | comment | Text | Read | Host Review's comment. + | | shareable | Boolean | Read | Whether Host Review is permitted for public use. + | | is_guest_recommended | Boolean | Read | Whether the host recommends guest. + | | source_id | Boolean | Read | Source of the Host Review, always equal to the source of the booking. +---------|---------------------|-----------------------|---------|------------|------------ +criteria | | | Object | Read | Guest ratings in specific criteria. + | cleanliness | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Rating of guests' clealiness + | | comment | Text | Read | Comment on guests' clealiness + | communication | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Rating of guests' communication + | | comment | Text | Read | Comment on guests' communication + | respect_house_rules | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Rating of guests' respect of house rules + | | comment | Text | Read | Comment on guests' respect of house rules +---------|---------------------|-----------------------|---------|------------|------------ + | | created_at | [Time](/reference/enums#formats) | Read | Review's create time. + | | updated_at | [Time](/reference/enums#formats) | Read | Review's update time. + | | submitted_at | [Time](/reference/enums#formats) | Read | Host Review's submission time. Once filled, no futher updates are required for given object. + | | expires_at | [Time](/reference/enums#formats) | Read | Host Review's expiry time. Once that time is passed, submission will no longer be possible. +{: class="table table-bordered"} +
+
+Group | Subgroup | Name | Type | Read/Write | Description +---------|---------------------|-----------------------|---------|------------|------------ + | | id | UUID | Read | Host Review's id. + | | source_id | Integer | Write | Id of the source of given host review. It must be equal to the source of the associated booking. +---------|---------------------|-----------------------|---------|------------|------------ + | | comment | Text | Read/Write | Host Review's comment. **Optional** for draft, **required** for submission. + | | private_comment | Text | Read/Write | ** Optional**: Private feedback to the guest, can't be display publicly. + | | shareable | Boolean | Read/Write | Whether Host Review is permitted for public use. **Required**: Has to be set during creation, not possible to modify afterwards. + | | is_guest_recommended | Boolean | Read/Write | Whether the host recommends guest. **Optional** for draft, **required** for submission. + | | source_id | Boolean | Read/Write | Source of the Host Review. **Required**: Has to be set during creation, not possible to modify afterwards. Has to be the same as the source of the booking. +---------|---------------------|-----------------------|---------|------------|------------ +criteria | | | Object | Read/Write | Guest ratings in specific criteria. **Optional** for draft, **required** for submission. + | cleanliness | | Object | Read/Write | Details of given criterion. **Optional** for draft, **required** for submission. + | | rating | Decimal | Read/Write | Rating of guests' clealiness. **Required** if parent element is defined. + | | comment | Text | Read/Write | **Optional**: Comment on guests' cleanliness. + | communication | | Object | Read/Write | Details of given criterion. **Optional** for draft, **required** for submission. + | | rating | Decimal | Read/Write | Rating of guests' communication. **Required** if parent element is defined. + | | comment | Text | Read/Write | **Optional**: Comment on guests' communication. + | respect_house_rules | | Object | Read/Write | Details of given criterion. **Optional** for draft, **required** for submission. + | | rating | Decimal | Read/Write | Rating of guests' respect of house rules. **Required** if parent element is defined. + | | comment | Text | Read/Write | **Optional**: Comment on guests' respect of house rules. +---------|---------------------|-----------------------|---------|------------|------------ + | | created_at | [Time](/reference/enums#formats) | Read | Review's create time. + | | updated_at | [Time](/reference/enums#formats) | Read | Review's update time. + | | submitted_at | [Time](/reference/enums#formats) | Read/Write | Host Review's submission time. Once filled, no futher updates are required for given object. **Required** for submission, for draft it's ignored by the server. + | | expires_at | [Time](/reference/enums#formats) | Read/Write | **Optional**: Host Review's expiry time. Once that time is passed, submission will no longer be possible. +{: class="table table-bordered"} +
+
+ +## List host reviews + +List all host reviews (from host to guest) for a given account(s). + +~~~ +GET /host_reviews +~~~ + +<%= render 'json_response', endpoint: "host_reviews", scopes: [{ public: "public" }, { reviews_write: "reviews_write" }] %> + +## Get a single host review + +Returns a single host review identified by ID. + +~~~ +GET /host_reviews/:host_review_id +~~~ + +<%= render 'json_response', endpoint: "host_reviews", scopes: [{ public: "public" }, { reviews_write: "reviews_write" }] %> + +## Create a new host review + +### Create submitted host review + +Creates a submitted host review for given booking. +Such a host review will be no longer editable and requires all data to be filled (`comment`, `shareable`, `is_guest_recommended`, `source_id`, `submitted_at`, all `criteria` with at least `rating`). + +~~~ +POST /bookings/:booking_id/host_reviews +~~~ + +<%= render 'json_response', endpoint: "host_reviews", request: "create-submitted", + scopes: [{ reviews_write: "submit_reviews_write" }] %> + +### Create draft host review + +Creates a draft host review for given booking. +Such a host review will be editable until submitted, it requires bare minimum for a successful creation (`shareable`, `source_id`) + +~~~ +POST /bookings/:booking_id/host_reviews/draft +~~~ + +<%= render 'json_response', endpoint: "host_reviews", request: "create-draft", + scopes: [{ reviews_write: "create_update_draft_reviews_write" }] %> + +## Edit draft review + +### Submit draft host review + +Submits host review making it final and no longer editable. Apart from `shareable` and `source_id` which can be set only during creation, all other attibutes (`comment`, `is_guest_recommended`, `submitted_at`, all `criteria` with at least `rating`) are required. + +~~~ +PUT /host_reviews/draft/:host_review_id/submit +~~~ + +<%= render 'json_response', endpoint: "host_reviews", request: "submit-draft", + scopes: [{ reviews_write: "submit_reviews_write" }] %> + +### Modify draft host review without submitting + +Updates host review attributes without submitting it, thus allowing for further editions. Apart from `shareable` and `source_id` which can be set only during creation, all other attibutes are optional. + +~~~ +PUT /host_reviews/draft/:host_review_id +~~~ + +<%= render 'json_response', endpoint: "host_reviews", request: "update-draft", + scopes: [{ reviews_write: "create_update_draft_reviews_write" }] %> diff --git a/content/reference/endpoints/review_replies.md b/content/reference/endpoints/review_replies.md new file mode 100644 index 00000000..50947fa6 --- /dev/null +++ b/content/reference/endpoints/review_replies.md @@ -0,0 +1,85 @@ +# Review Replies + +1. TOC +{:toc} + +### Parameters + +
+
+Name | Type | Read/Write | Description +-----------------|---------|------------|------------ +id | UUID | Read | Review Reply id. +-----------------|---------|------------|------------ +message | Text | Read | Reply to given Guest or Host review +-----------------|---------|------------|------------ +submitted_at | [Time](/reference/enums#formats) | Read | Review Reply submission time. +created_at | [Time](/reference/enums#formats) | Read | Review's create time. +updated_at | [Time](/reference/enums#formats) | Read | Review's update time. +{: class="table table-bordered"} +
+
+Name | Type | Read/Write | Description +-----------------|---------|------------|------------ +id | UUID | Read | Review Reply id. +-----------------|---------|------------|------------ +message | Text | Read/Write | **Required** Reply to given Guest or Host review +-----------------|---------|------------|------------ +submitted_at | [Time](/reference/enums#formats) | Read/Write | Review Reply submission time. When not provided it will be set to creation time. +created_at | [Time](/reference/enums#formats) | Read | Review's create time. +updated_at | [Time](/reference/enums#formats) | Read | Review's update time. +{: class="table table-bordered"} +
+
+ +## List review replies + +List all review replies for a given account(s). + +~~~ +GET /review_replies +~~~ + +<%= render 'json_response', endpoint: "review_replies", scopes: [{ public: "public-reviews_write" }] %> + +## Get a single review + +Returns a single review identified by ID. + +~~~ +GET /review_replies/:review_id +~~~ + +<%= render 'json_response', endpoint: "review_replies", scopes: [{ public: "public-reviews_write" }] %> + +## Reply to guest or host review + +
+ As of now, every guest or host review may have only one reply. +
+ +### Reply to guest review + +Replies to a given guest review + +~~~ +POST /reviews/:review_id/reply +~~~ + +<%= render 'json_response', endpoint: "review_replies", request: "create", + scopes: [{ reviews_write: "reply_to_guest_public-reviews_write" }] %> + +### Reply to host review + +Replies to a given host review + +~~~ +POST /host_reviews/:host_review_id/reply +~~~ + +<%= render 'json_response', endpoint: "review_replies", request: "create", + scopes: [{ reviews_write: "public-reviews_write" }] %> diff --git a/content/reference/endpoints/reviews.md b/content/reference/endpoints/reviews.md index f25bb5fe..185bff00 100644 --- a/content/reference/endpoints/reviews.md +++ b/content/reference/endpoints/reviews.md @@ -11,40 +11,106 @@
-Name | Type | Read/Write | Description ------------------|---------|------------|------------ -id | Integer | Read | Review's id. ------------------|---------|------------|------------ -comment | Text | Read | Review's comment. -country_code | String | Read | Reviewer's country code. -name | String | Read | Reviewer's name, cropped to show only the initial of the last name. -rating | Integer | Read | Review's rating. -title | String | Read | Review's title. ------------------|---------|------------|------------ -created_at | [Time](/reference/enums#formats) | Read | Review's create time. -updated_at | [Time](/reference/enums#formats) | Read | Review's update time. +Group | Subgroup | Name | Type | Read/Write | Description +---------|---------------------|-----------------------|---------|------------|------------ + | | id | Integer | Read | Guest Review's id. +---------|---------------------|-----------------------|---------|------------|------------ + | | title | Text | Read | Title/Summary of the review. + | | comment | Text | Read | Guest Review's comment. + | | rating | Integer | Read | Guest Review's rating (between 1 and 5, inclusive). + | | rating_accurate | Text | Read | Non rounded rating. + | | name | Text | Read | Reviewer's name, cropped to show only the initial of the last name. + | | country_code | Text | Read | Reviewer's country code. + | | shareable | Boolean | Read | Whether Guest Review is permitted for public use. +---------|---------------------|-----------------------|---------|------------|------------ +criteria | | | Object | Read | Host ratings in specific criteria. + | cleanliness | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Was the cleanliness up to the standards? + | | comment | Text | Read | Additional feedback for a given criterion. + | communication | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | How fast/easy the communication with the host was. + | | comment | Text | Read | Additional feedback for a given criterion. + | checkin | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | How smooth was the checkin process? + | | comment | Text | Read | Additional feedback for a given criterion. + | location | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Was the guest aware of any location dependent factors that could affect the stay (such as noise, safety, transportation etc.)? + | | comment | Text | Read | Additional feedback for a given criterion. + | facilities | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Whare facilities working and matching description? XXX + | | comment | Text | Read | Additional feedback for a given criterion. + | comfort | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Was the property warm enough, with enough lights. Were the beds and/or sofa comfy? + | | comment | Text | Read | Additional feedback for a given criterion. + | staff | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Was the staff friendly, attentive and respectful? + | | comment | Text | Read | Additional feedback for a given criterion. + | value_for_money | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Was it worth the price? + | | comment | Text | Read | Additional feedback for a given criterion. + | accuracy | | Object | Read | Details of given criterion. + | | rating | Decimal | Read | Was the property accurately represented on a website? + | | comment | Text | Read | Additional feedback for a given criterion. +---------|---------------------|-----------------------|---------|------------|------------ + | | created_at | [Time](/reference/enums#formats) | Read | Review's create time. + | | updated_at | [Time](/reference/enums#formats) | Read | Review's update time. + | | submitted_at | [Time](/reference/enums#formats) | Read | Review's submission time. When not specified, defaults to creation time. {: class="table table-bordered"}
-Name | Type | Read/Write | Description ------------------|---------|------------|------------ -id | Integer | Read | Review's id. ------------------|---------|------------|------------ -comment | Text | Read/Write | **Required**. Review's comment. (10 min, 2000 max characters) -country_code | String | Read | Reviewer's country code. e.g: FR -name | String | Read | Reviewer's name, cropped to show only the initial of the last name. -rating | Integer | Read/Write | **Required**. Review's rating. (between 1 and 6) -title | String | Read/Write | Review's title. (3 min, 100 max characters) ------------------|---------|------------|------------ -created_at | [Time](/reference/enums#formats) | Read | Review's create time. -updated_at | [Time](/reference/enums#formats) | Read | Review's update time. +Group | Subgroup | Name | Type | Read/Write | Description +---------|---------------------|-----------------------|---------|------------|------------ + | | id | Integer | Read | Guest Review's id. + | | source_id | Integer | Write | Id of the source of this review +---------|---------------------|-----------------------|---------|------------|------------ + | | title | Text | Read/Write | Title/Summary of the review. + | | comment | Text | Read/Write | **Required**: Comment from guest. + | | private_comment | Text | Read/Write | Private comment from guest (not meant to be exposed publicly). + | | rating | Integer | Read/Write | **Required**: Overall rating of a stay (between 1 and 5, inclusive). + | | rating_accurate | Text | Read | Non rounded rating. + | | name | Text | Read | Reviewer's name, cropped to show only the initial of the last name. + | | country_code | Text | Read | Reviewer's country code. + | | shareable | Boolean | Read/Write | Whether Guest Review is permitted for public use. +---------|---------------------|-----------------------|---------|------------|------------ +criteria | | | Object | Read/Write | Host ratings in specific criteria. + | cleanliness | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | Was the cleanliness up to the standards? **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | communication | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | How fast/easy the communication with the host was. **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | checkin | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | How smooth was the checkin process? **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | location | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | Was the guest aware of any location dependent factors that could affect the stay (such as noise, safety, transportation etc.)? **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | facilities | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | Were facilities working and matching description? XXX **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | comfort | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | Was the property warm enough, with enough lights. Were the beds and/or sofa comfy? **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | staff | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | Was the staff friendly, attentive and respectful? **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | value_for_money | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | Was it worth the price? **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. + | accuracy | | Object | Read/Write | Details of given criterion. + | | rating | Decimal | Read/Write | Was the property accurately represented on a website? **Required** only when sending parent node. + | | comment | Text | Read/Write | Additional feedback for a given criterion. +---------|---------------------|-----------------------|---------|------------|------------ + | | created_at | [Time](/reference/enums#formats) | Read | Review's create time. + | | updated_at | [Time](/reference/enums#formats) | Read | Review's update time. + | | submitted_at | [Time](/reference/enums#formats) | Read/Write | Host Review's submission time. Once filled, no futher updates are required for given object. {: class="table table-bordered"}
## List reviews -List all reviews for a given account(s). +List all guest reviews (from guest to host) for a given account(s). ~~~ GET /reviews diff --git a/layouts/reference.html b/layouts/reference.html index ee5450b3..c895fe16 100644 --- a/layouts/reference.html +++ b/layouts/reference.html @@ -62,6 +62,8 @@

Endpoints

class: "list-group-item") %> <%= link_to_with_current("Fees Taxes", "/reference/endpoints/fees_taxes/", class: "list-group-item") %> + <%= link_to_with_current("Host Reviews", "/reference/endpoints/host_reviews/", + class: "list-group-item") %> <%= link_to_with_current("Hosts", "/reference/endpoints/hosts/", class: "list-group-item") %> <%= link_to_with_current("Inbox Attachments", "/reference/endpoints/inbox_attachments/", @@ -124,6 +126,8 @@

Endpoints

class: "list-group-item") %> <%= link_to_with_current("Rental URLs", "/reference/endpoints/rental_urls/", class: "list-group-item") %> + <%= link_to_with_current("Review Replies", "/reference/endpoints/review_replies/", + class: "list-group-item") %> <%= link_to_with_current("Reviews", "/reference/endpoints/reviews/", class: "list-group-item") %> <%= link_to_with_current("Seasons", "/reference/endpoints/seasons/",