[NEWS] Udostępniliśmy nową wersję zasobu /users/{userId}/ratings-summary / We have introduced a new version of the resource /users/{userId}/ratings-summary

[Lukasz-Zurek]

Od dziś skorzystasz z wersji beta.v1 zasobu /users/{userId}/ratings-summary, za pomocą którego pobierzesz podsumowanie statystyk ocen sprzedaży dla dowolnego użytkownika. Nową strukturę dostosowaliśmy do aktualnych warunków i zasad wystawiania oceny sprzedaży.

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

1. W wersji beta.v1 wdrożyliśmy nową strukturę, w której zwrócimy dwa nowe obiekty:

• “statistics” - podsumowanie statystyk ocen sprzedaży, z rozróżnieniem na pola:
  • “received” - oceny otrzymane,
  • “excluded” - wykluczone,
  • “removed” - usunięte (w zależności od przyczyny usunięcia, wartości zwracamy w polach: "total", "byAdmin", "byBuyer", "byBuyerDueToCompensation"),
• “user” - informacje o użytkowniku, gdzie w polu:
  • “numberOfProductsSoldWithin30Days” - zwracamy liczbę produktów sprzedanych przez użytkownika w ciągu ostatnich 30 dni,
  • "createdAt" - zwracamy datę utworzenia konta.

2. Usunęliśmy obiekt "averageRates", ponieważ ze względu na brak ocen gwiazdkowych w nowej ocenie sprzedaży, nie jest on już potrzebny.

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:

curl -X GET \
'https://api.allegro.pl/users/106888486/ratings-summary’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' \

Przykładowy response:

{
    "recommended": { - liczba polecających użytkowników
        "unique": 2,
        "total": 4
    },
    "notRecommended": { - liczba nie polecających użytkowników
        "unique": 0,
        "total": 0
    },
    "recommendedPercentage": "100,0",- Procent unikalnych kupujących polecających sprzedawcę
    "statistics": { - podsumowanie statystyk ocen sprzedaży,
        "received": { - otrzymane
            "total": 4
        },
        "excluded": { - wykluczone
            "total": 0
        },
        "removed": { - usunięte
            "total": 0,
            "byAdmin": 0, - liczba ocen usuniętych przez administratora
            "byBuyer": 0, - liczba ocen usuniętych przez kupującego
            "byBuyerDueToCompensation": 0 - liczba ocen usuniętych przez kupującego z powodu rekompensaty
        }
    },
    "user": {
        "numberOfProductsSoldWithin30Days": 32, - liczba produktów sprzedanych przez użytkownika w ciągu ostatnich 30 dni

        "createdAt": "2024-02-07" - data utworzenia konta
    }
}

Dlaczego wprowadzamy tę zmianę?

Zasób /users/{userId}/ratings-summary funkcjonuje obecnie w wersji public.v1, jednak struktura odpowiedzi nie jest dostosowana do aktualnych warunków i zasad wystawiania ocen sprzedaży. 18 lutego 2025 usunęliśmy gwiazdki z oceny sprzedaży, co oznacza, że kupujący nie mogą już oceniać zgodności z opisem i obsługi kupującego.

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.

---

Starting today, you will be able to use the beta.v1 version of the /users/{userId}/ratings-summary resource, which will allow you to download a summary of sales rating statistics for any user. We have adapted the new structure to the current conditions and rules for issuing sales ratings.

What changes have we implemented in beta.v1?

1. In beta.v1, we have implemented a new structure in which we will return two new objects:

• “statistics” - summary of sales rating statistics, with a distinction between the fields:
  • “received” - received ratings,
  • “excluded” - excluded,
  • “removed” - removed (depending on the reason for removal, we return values in the fields: "total", "byAdmin", "byBuyer", "byBuyerDueToCompensation"),
• “user” - information about the user, where in the field:
  • “numberOfProductsSoldWithin30Days” - we return the number of products sold by the user in the last 30 days,
  • "createdAt" - we return the date the account was created.

2. We have removed the "averageRates" object, because it is no longer needed due to the lack of star ratings in the new sales rating.

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:

curl -X GET \
'https://api.allegro.pl/users/106888486/ratings-summary’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v1+json' \

Sample response:

{
    "recommended": { - number of recommending users
        "unique": 2,
        "total": 4
    },
    "notRecommended": { - number of not recommending users
        "unique": 0,
        "total": 0
    },
    "recommendedPercentage": "100,0", - Percentage of unique buyers recommending a seller
    "statistics": { - sales ratings statistics summary
        "received": { - received sales ratings
            "total": 4
        },
        "excluded": { - excluded
            "total": 0
        },
        "removed": { - removed
            "total": 0,
            "byAdmin": 0, - number of ratings deleted by the admin
            "byBuyer": 0, - number of ratings deleted by buyer
            "byBuyerDueToCompensation": 0 - number of ratings removed by buyer due to compensation
        }
    },
    "user": {
        "numberOfProductsSoldWithin30Days": 32, - number of products sold by the user in the last 30 days
        "createdAt": "2024-02-07" - the date when the user account was created
    }
}

Why are we making this change?

The /users/{userId}/ratings-summary resource is currently public.v1, but the structure of the response is not adapted to the current terms and conditions of sales ratings. On February 18, 2025, we removed stars from sales ratings, meaning buyers can no longer rate the compliance with the description and the buyer's service.

What are the next steps?

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