search

allegro / allegro-api

Issue tracker and wiki for Allegro REST API
https://developer.allegro.pl/
217 stars 39 forks source link

[NEWS] Zasoby /sale/product-offers oraz /sale/product-offers/{offerId} - wprowadziliśmy nowy obiekt "warnings" / /sale/product-offers and /sale/product-offers/{offerId} resources - we have introduced a new "warnings" object #9808

Open AureliuszBrussy opened 3 months ago

AureliuszBrussy commented 3 months ago

Dzisiaj wprowadziliśmy nową tablicę obiektów "warnings", którą zwracamy w odpowiedzi dla:

Jakie informacje zwracamy w nowym obiekcie?

W nowym obiekcie zwrócimy informacje o wszelkich problemach, które wystąpiły podczas procesowania żądania. Może zdarzyć się sytuacja, że żądanie zostanie zrealizowane częściowo i ze względu na niekrytyczny charakter części pól modelu oferty, zapiszemy (metody POST i PATCH) lub zwrócimy (metoda GET) dla nich wartość domyślną.

Które z pól modelu oferty uznajemy za niekrytyczne?

Zbiór pól niekrytycznych zdefiniujemy w przyszłości. Aktualnie tablica ta zawsze będzie pusta. Przygotuj się jednak do jej prawidłowej obsługi przez Twoje oprogramowanie.

Informacje o polach niekrytycznych umieścimy bezpośrednio w dokumentacji:

Będziemy informować o przyszłych zmianach dla poszczególnych pól.

Jaki skutek przyniesie zmiana?

Dla danych, które uznajemy za niekrytyczne (tylko określonych przypadków), zamiast błędu z grupy 5xx, zwrócimy prawidłową odpowiedź 200, 201 lub 202:

Przykładowa zawartość obiektu warnings:

 {
   "code": "RequestPartiallyComplete",
   "message": "Some of the data provided in the request was not saved",
   "details": null,
   "path": "messageToSellerSettings",
   "userMessage": "Some of the data provided in the request was not saved. It will default to OPTIONAL",
   "metadata": {
     "savedDefaultValue": "OPTIONAL"
   }
 }
]

Zwróć uwagę, że jest to całkowicie nowy obiekt i różni się od istniejącej już w modelu oferty tablicy "validation.warnings". Obiekt ten służy innemu celowi - aby przekazywać użytkownikowi końcowemu ostrzeżenia dla zwalidowanej oferty.

Co zmienić w swoim oprogramowaniu?

Uznajemy, że błędy te powinny być przekazywane użytkownikowi końcowemu oprogramowania. Na przykład, mogą być one mapowane do odpowiednich pól wejściowych w oprogramowaniu (przy użyciu parametru "path") i prezentowane jako błędy lub ostrzeżenia. Dzięki temu użytkownik będzie mógł zdecydować, czy chce ponowić żądanie lub edytować ofertę później.

Więcej o wystawianiu oferty produktu oraz zarządzaniu ofertami znajdziesz w naszych poradnikach:

Today we introduced a new array of "warnings" objects, which we return in the response for:

What information do we return in the new object?

In the new object, we return information about any problems that occurred during the processing of the request. The request may be partially processed and due to the non-critical nature of some of the fields of the offer model, we will save (POST and PATCH methods) or return (GET method) a default value for them.

Which fields of the offer model do we consider non-critical?

We will define the set of non-critical fields in the future. Currently, this array will always be empty. However, prepare for its proper handling by your software.

We will put information about non-critical fields directly in the documentation:

We will also inform you of future changes for specific fields.

What effect will the change have?

For data that we consider non-critical (only certain cases), instead of an error from the 5xx group, we will return the correct answer 200, 201 or 202:

Example content of the warnings object:

 {
   "code": "RequestPartiallyComplete",
   "message": "Some of the data provided in the request was not saved",
   "details": null,
   "path": "messageToSellerSettings",
   "userMessage": "Some of the data provided in the request was not saved. It will default to OPTIONAL",
   "metadata": {
     "savedDefaultValue": "OPTIONAL"
   }
 }
]

Note that this is a completely new object and differs from the existing "validation.warnings" array in the offer model. This object serves a different purpose - to pass warnings to the end user for a validated offer.

What to change in your software?

We recognize that these errors should be communicated to the end user of the software. For example, they can be mapped to the appropriate input fields in the software (using the "path" parameter) and presented as errors or warnings. This would allow the user to decide whether to repeat the request or to edit the offer later.

You can find more about listing a product and managing offers in our tutorials:

ZakuroPL commented 2 months ago

Chcę zgłosić błędny komunikat warnings dla: POST /sale/product-offers za każdym razem gdy przekazujemy zgodnie z dokumentacją API: 'publication': {'status': 'INACTIVE', 'republish': False} to otrzymujemy w response: 'warnings': [ {'code': 'UnknownJSONProperty', 'message': 'Unknown properties found in the request.', 'details': None, 'path': None, 'userMessage': 'Unknown parameters found in the query.', 'metadata': {'unknownProperties': 'publication'}}]

Według waszej dokumentacji obiekt publication jest dostępny, nie jest deprecated. Najprawdopodobniej błedny komunikat warnings?

AureliuszBrussy commented 2 months ago

@ZakuroPL czy możesz podesłać przykładowe trace-id, gdzie zwróciliśmy ten warning? Trace-id znajdziesz w nagłówku naszego response'a. Sprawdzę to.

ZakuroPL commented 2 months ago

@AureliuszBrussy okazało się, że przez przypadek przekazywaliśmy wewnątrz obiektu product ['product']['publication'].