[NEWS] Udostępniliśmy nowe wersje zasobów na ścieżce /sale/user-ratings / We have introduced new versions of /sale/user-ratings resources

Od dziś skorzystasz z wersji **beta.v1** zasobów:

- [GET /sale/user-ratings](https://developer.allegro.pl/documentation#tag/Information-about-user) - pobierz listę ocen sprzedaży,
- [GET /sale/user-ratings/{ratingId}](https://developer.allegro.pl/documentation#tag/Information-about-user/operation/getUserRatingUsingGET) - pobierz szczegółowe informacje dotyczące wybranej [oceny sprzedaży](https://help.allegro.com/sell/pl/a/czym-jest-ocena-sprzedazy-Wv067d4WdTB).

Nową strukturę dostosowaliśmy do [aktualnych warunków i zasad wystawiania oceny sprzedaży](https://help.allegro.com/sell/pl/a/czym-jest-ocena-sprzedazy-Wv067d4WdTB).

**Jakie zmiany wdrożyliśmy w wersji beta.v1?**

1. W wersji **beta.v1** wdrożyliśmy nową strukturę, gdzie:

- dotychczasowe pola **“comment”** jest obiektem, w którym zwracamy dwa nowe pola:
- **“text”** - treść komentarza do oceny,
- **“language”** - język, w którym komentarz został wystawiony oryginalnie, przed automatycznym tłumaczeniem,
- w obiekcie **“answer”** dodaliśmy dwa nowe pola:
- **“text”** - treść odpowiedzi do oceny,
- **“language”** - język, w którym odpowiedź do oceny została wystawiona, przed automatycznym tłumaczeniem,
- dodaliśmy nowy obiekt **“exclusion”** - wykluczenie oceny, w którym zwracamy:
- **“reason”** - powód, dla którego ocena została wyłączona z obliczania średniej oceny użytkowników,
- dodaliśmy nowy obiekt **“justifications”** - lista uzasadnień wybranych przez kupującego podczas tworzenia oceny:
- **"text"** - uzasadnienie dla oceny sprzedaży,
- **"visibleForBuyer"** - widoczność uzasadnienia dla kupującego,
- usunęliśmy obiekt **"rates"**, gdzie dotychczas zwracaliśmy oceny gwiazdkowe,
- usunęliśmy pola **"excludedFromAverageRates"** i **"excludedFromAverageRatesReason"**.

2. Dodaliśmy **Accept-Language** - za pomocą którego ustawisz oczekiwany język komunikatów. Nagłówek jest dostępny tylko dla wersji treści **“application/vnd.allegro.beta.v1+json”.** Dostępne wartości: en-US, pl-PL, uk-UA, sk-SK, cs-CZ, hu-HU. Jeśli jej nie przekażesz, domyślnie zwrócimy wyniki z wartością: pl-PL.

3. Aby dostosować się do zmian, wystarczy, że zmienisz wartość w nagłówku Accept z “application/vnd.allegro.public.v1+json” na **“application/vnd.allegro.beta.v1+json”**.

**Przykładowy request dla /sale/user-ratings:**

```
curl -X GET \
'https://api.allegro.pl/sale/user-ratings’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' \
-H 'Accept-Language: pl-PL \

```
**Przykładowy response dla /sale/user-ratings:**

```
{
"ratings": [
{
"id": "67a078f6d2446c059c6e44e9",
"createdAt": "2025-05-03T08:06:14.462Z",
"lastChangedAt": "2025-05-03T08:06:14.462Z",
"recommended": false,
"buyer": {
"id": "104778524",
"login": "Buyer-test-account"
},
"comment": { // komentarz do oceny sprzedaży
"text": "Good transaction", // treść komentarza do oceny
"language": "en" // język, w którym komentarz został wystawiony oryginalnie, przed automatycznym tłumaczeniem
},
"exclusion": { // wykluczenie oceny sprzedaży
"reason": "test" // powód, dla którego ocena została wyłączona z obliczania średniej oceny użytkowników
},
"order": {
"id": "7f315620-b857-11ef-9529-1b1ca444b49b",
"offers": [
{
"id": "7775984789",
"title": "Lego Star Wars Statek Rycerzy Ren 75284"
}
]
},
"answer": {
"text": "Dziękuję za ocenę", // treść odpowiedzi do oceny,
"createdAt": "2025-02-03T08:07:32.822Z",
"language": "pl" // język, w którym odpowiedź do oceny została wystawiona, przed automatycznym tłumaczeniem
},
"removal": {
"possibleTo": "2025-06-12T07:07:41.580Z"
},
"justifications": [ // lista uzasadnień wybranych przez kupującego podczas tworzenia oceny
{
"text": "Nieuprzejma obsługa", // uzasadnienie dla oceny sprzedaży
"visibleForBuyer": true // widoczność uzasadnienia dla kupującego
}
]
}
]
}
```

**Dlaczego wprowadzamy tę zmianę?**

Zasoby:

- [GET /sale/user-ratings](https://developer.allegro.pl/documentation#tag/Information-about-user),
- [GET /sale/user-ratings/{ratingId}](https://developer.allegro.pl/documentation#tag/Information-about-user/operation/getUserRatingUsingGET),

funkcjonują obecnie w wersji public.v1, jednak struktura odpowiedzi nie jest dostosowana do [aktualnych warunków i zasad wystawiania ocen sprzedaży](https://help.allegro.com/sell/pl/a/czym-jest-ocena-sprzedazy-Wv067d4WdTB). [18 lutego 2025 usunęliśmy gwiazdki z oceny sprzedaży](https://help.allegro.com/sell/pl/a/nowosci-i-zmiany-dla-sprzedajacych-w-najblizszych-miesiacach-x5bOve03gUY#z-oceny-sprzedajacego-usuniemy-zgodnosc-z-opisem-i-obsluge-kupujacego-czyli-obszary-oceniane-gwiazdkami), co oznacza, że kupujący nie mogą już oceniać zgodności z opisem i obsługi kupującego. Ponadto w ostatnim czasie wdrożone zostały tzw. uzasadnienia do oceny, których obecna struktura dostępna na public.v1 nie uwzględnia.

**Jakie są kolejne kroki?**

W przyszłości planujemy przenieść strukturę zasobu w wersji beta.v1 na wersję public.v1, poinformujemy o tym z odpowiednim wyprzedzeniem.

--------

From today, you can use the **beta.v1** version of the resources:

- [GET /sale/user-ratings](https://developer.allegro.pl/documentation#tag/Information-about-user) - retrieve sales ratings list,
- [GET /sale/user-ratings/{ratingId}](https://developer.allegro.pl/documentation#tag/Information-about-user/operation/getUserRatingUsingGET) - retrieve detailed information about your selected sales rating.

We have adapted the new structure to the [current conditions and principles of creating sales ratings](https://help.allegro.com/en/sell/a/what-a-sales-rating-is-K6Vzj9D79Sa).

**What changes have we implemented in beta.v1?**

1. In **beta.v1** we have implemented a new structure where:

- the current **“comment”** field is an object in which we return two new fields:
- **“text”** - content of the sales rating comment,
- **“language”** - the language in which the comment was originally posted, before automatic translation,
- in the **“answer”** object we added two new fields:
- **“text”** - sales rating comment’s response content
- **“language”** - the language in which the response to the comment was submitted, before automatic translation,
- we added a new **“exclusion”** object - exclusion of sales rating in which we return:
- **“reason”** - the reason why the rating was excluded from calculating the average user rating,
- we added a new **“justifications”** object - a list of justifications selected by the buyer when creating the rating:
- **"text"** - justification for sales rating,
- **"visibleForBuyer"** - visibility of the justification for the buyer,
- we removed the **"rates"**, object, where we previously returned star ratings,
- we removed **"excludedFromAverageRates"** and **"excludedFromAverageRatesReason"** fields.

2. We added the **Accept-Language** - with which you can set the desired language for messages. The header is only available for the content version **“application/vnd.allegro.beta.v1+json”** and available values are: en-US, pl-PL, uk-UA, sk-SK, cs-CZ, hu-HU. If you do not provide it, we will return results with the value: pl-PL by default.

3. To adapt to the changes, simply change the value in the **Accept** header from “application/vnd.allegro.public.v1+json” to **“application/vnd.allegro.beta.v1+json”**.

**Sample request for /sale/user-ratings:**

```
curl -X GET \
'https://api.allegro.pl/sale/user-ratings’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' \
-H 'Accept-Language: en-US \
```

**Sample response for /sale/user-ratings:**

```
{
"ratings" : [ {
"id" : "68394cb0f3e44475cb17853b",
"createdAt" : "2025-05-05T10:25:00.000Z",
"editedAt" : "2025-05-08T10:25:00.000Z",
"lastChangedAt" : "2025-05-08T10:25:00.000Z",
"recommended" : true,
"buyer" : {
"id" : "author-id-2"
},
"comment" : {
"text" : "comment", // content of the sales rating comment
"language" : "en" // the language in which the comment was originally posted, before automatic translation
},
"order" : {
"id" : "5702af61-ac25-11e6-ada3-6b1b2d1f7af1",
"offers" : [ {
"id" : "id",
"title" : "title"
} ]
},
"answer": {
"text": "Thank you.", // content of the sales rating comment response,
"createdAt": "2025-05-10T08:07:32.822Z",
"language": "en" // the language in which the response to the assessment was submitted, before automatic translation
},
"removal" : {
"possibleTo" : "2025-05-11T11:35:00.000Z",
"request" : {
"createdAt" : "2025-05-10T10:25:00.000Z",
"message" : "Removal request",
"source" : "ADMIN"
}
},
"exclusion" : { // exclusion of sales rating
"reason" : "The buyer has already rated their purchase from you in the last 7 days." // reason why the rating was excluded from calculating the average user rating
},
"justifications" : [ { // list of justifications selected by the buyer when creating the rating
"text" : "Delivery before estimated time", // justification for sales rating
"visibleForBuyer" : false // visibility of the justification for the buyer
}, {
"text" : "Delivery on time",
"visibleForBuyer" : true
} ]
}
…
```

**Why are we making this change?**

Endpoints:

- [GET /sale/user-ratings](https://developer.allegro.pl/documentation#tag/Information-about-user),
- [GET /sale/user-ratings/{ratingId}](https://developer.allegro.pl/documentation#tag/Information-about-user/operation/getUserRatingUsingGET),

currently exist in public.v1, however, the structure of the responses is not adapted to [the current conditions and rules for issuing sales ratings](https://help.allegro.com/en/sell/a/what-a-sales-rating-is-K6Vzj9D79Sa). [On February 18, 2025, we removed stars from the sales rating](https://help.allegro.com/en/sell/a/changes-for-sellers-in-the-coming-months-6MEOVaK1Yf9#we-will-remove-two-areas-rated-with-stars-compliance-with-the-description-and-customer-service-from-the-seller-s-rating), which means that buyers can no longer evaluate compliance with the description and customer service. In addition, so-called justifications for rating have recently been implemented, which the current structure available on the public.v1 does not take into account.

**What are the next steps?**

In the future, we plan to move the beta.v1 resource structure to the public.v1, we will inform you about it in due time.