search

allegro / allegro-api

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

[NEWS] Parametr GTIN w ofertach oraz produktach / GTIN parameter in offers and products #3373

Open MaciejFrackowiak opened 4 years ago

MaciejFrackowiak commented 4 years ago

Zgodnie z wcześniejszą zapowiedzią dzisiaj udostępniliśmy parametr globalny numer jednostki handlowej tzw. GTIN. W większości kategorii oznaczyliśmy go jako parametr podstawowy, czyli taki, który identyfikuje produkt w ofercie. Jeżeli chcesz określić lub zmienić GTIN, w zależności od kategorii, skorzystaj z dostępnych parametrów:

Pamiętaj, że parametry dostępne w danej kategorii sprawdzisz za pomocą GET /sale/categories/{categoryId}/parameters.

GTIN w ofertach W ofertach parametr GTIN jest nadrzędny wobec pola “ean”, którego wartości przenieśliśmy do nowego parametru. Wartość EAN, ISBN lub ISSN możesz uzupełnić jedynie w parametrze GTIN, aby to zrobić pobierz aktualny stan oferty poprzez GET /sale/offers/{offerId}, a następnie edytuj poprzez PUT /sale/offers/{offerId}. Jeśli spróbujesz zmienić wartość pola “ean” w ofercie, otrzymasz komunikat błędu: “Pole ean jest tylko do odczytu. Wartość z pola ean podaj w parametrze o id: {id}.”

Jeżeli dotychczas w integracji używasz pola “ean” by rozpoznać swoje oferty (jako sygnaturę), wykorzystaj w tym celu dedykowane dla sygnatury pole “external.id”.

GTIN w produktach Parametr GTIN dla produktów funkcjonuje równolegle z dotychczasową tablicą “eans”. Aktualne wartości “eans” przenieśliśmy do nowego parametru. Zgłaszając propozycję produktu przez POST /sale/product-proposals możesz przekazać wartość EAN, ISBN lub ISSN tylko w parametrze GTIN.

Parametr GTIN zyskał flagę “isGTIN” w strukturze “options” parametrów produktu. Dzięki temu podczas dodawania oferty na podstawie produktu rozpoznasz, że jeśli parametr ma wiele wartości, to możesz przekazać tylko jedną z nich.

Przykładowy request:

curl -X GET \
‘https://api.allegro.pl/sale/products/0ca14fc3-7084-4fa2-83da-d04104e8b162’ \
-H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

...
"parameters": [
{
    "id": "225693",
    "name": "EAN",
    "valuesLabels": [
        "0901362561720"
    ],
    "values": [
        "0901362561720"
    ],
    "unit": null,
    "options": {
        "identifiesProduct": true,
        "isGTIN": true
    }
}
],
...

Ważne! W przyszłości pole “ean” w ofercie oraz tablicę “eans” w produkcie usuniemy. Wartość GTIN (czyli EAN, ISBN, ISSN) zmienisz tylko korzystając z parametru, dlatego już dzisiaj rozpocznij prace nad ich poprawną obsługą w swojej aplikacji.

According to our previous announcement today we have introduced the Global Trade Item Number (GTIN) parameter. In most categories, we marked it as a basic parameter, which identifies the product in an offer. If you want to add or change GTIN parameter use the available parameters (depending on category):

You can check parameters available in a given category by GET /sale/categories/{categoryId}/parameters.

GTIN in offers In offers, GTIN parameter overrode “ean” field, whose values were transferred to the new parameter. You can only fill in the EAN, ISBN, ISSN value in the GTIN parameter. To do so retrieve an offer via GET /sale/offers/{offerId} and then edit it by PUT /sale/offers/{offerId}. If you try to change the value of the "ean" field in the offer, you will receive an error message: "Ean field is read-only. Set this value in parameter with id: {id}."

If you use in your integration the "ean" to recognize your offers (as so-called signature), switch to the "external.id" field, which is dedicated to the signature.

GTIN in products The GTIN parameter for products functions in parallel with the existing "eans" array. We transferred the current values of "eans" to the new parameter. If you propose a product via POST /sale/product-proposals you can submit EAN, ISBN or ISSN value only in the GTIN parameter.

The GTIN parameter received the "isGTIN" flag in the "options" structure of the product parameters. Owing to it, when you will add an offer based on a product, you will recognize if a parameter has many values, you can only use one of them.

Sample request:

curl -X GET \
‘https://api.allegro.pl/sale/products/0ca14fc3-7084-4fa2-83da-d04104e8b162’ \
-H 'Accept: application/vnd.allegro.public.v1+json'

Sample response:

...
"parameters": [
{
    "id": "225693",
    "name": "EAN",
    "valuesLabels": [
        "0901362561720"
    ],
    "values": [
        "0901362561720"
    ],
    "unit": null,
    "options": {
        "identifiesProduct": true,
        "isGTIN": true
    }
}
],
...

Note! In the future, we will remove the "ean" field in the offer and the "eans" array in the product. You will change the GTIN value (i.e. EAN, ISBN, ISSN) only using the parameter, so start working on their correct implementation in your application today.

Onixarts commented 4 years ago

Jeśli spróbujesz zmienić wartość pola “ean” w ofercie, otrzymasz komunikat błędu: “Pole ean jest tylko do odczytu. Wartość z pola ean podaj w parametrze o id: {id}.”

Co rozumiecie pod pojęciem "spróbujesz zmienić" - ja zrozumiałem, że wysłanie kodu w polu ean takiego samego jak był w ofercie powinno przejść (no bo nie jest zmieniany), tymczasem nie przechodzi i API wali błędem, że ean jest tylko do odczytu. Tak miało być?

MaciejFrackowiak commented 4 years ago

@Onixarts Tak, tak miało być.

Wartość EAN, ISBN lub ISSN możesz uzupełnić jedynie w parametrze GTIN, aby to zrobić pobierz aktualny stan oferty poprzez GET /sale/offers/{offerId}, a następnie edytuj poprzez PUT /sale/offers/{offerId}

Onixarts commented 4 years ago

To w takim razie źle zrozumiałem intencje ;)

MariuszPol commented 4 years ago

Czy pole GTIN jako parametr podstawowy jest wymagany, wiec jak wystawiac produkty bez kodu EAN? Sa np. kategorie, w ktorych wyswietla sie kod EAN do uzupelnienia, a produkty nie maja ich (np. rzezby, sztuka itp).

MaciejFrackowiak commented 4 years ago

@SellyPL Parametr GTIN w ofertach w większości kategorii nie jest obecnie obowiązkowy.

MariuszPol commented 4 years ago

Tak sadzilem, ale wystawiajac aukcje otrzymuje blad:

[1] => Array ( [code] => VALIDATION_ERROR [message] => Kod EAN jest niepoprawny. [details] => [path] => [userMessage] => Kod EAN jest niepoprawny. )

W kategorii 26274 gdzie jest to kategoria z nieobowiazkowym EAN (mowie o Sandbox).

MaciejFrackowiak commented 4 years ago

@MariuszPol Proszę podaj mi wartość EAN, którą przesyłasz (o ile ją dodajesz) - przekazujesz ją w polu "ean" czy już w ramach parametru?

MariuszPol commented 4 years ago

@MaciejFrackowiak ok opisze dokladnie. Na sandboxie pobieram formularze kategorii dla kategorii ID 111852 (akcesoria dekarskie, ale takze w innych tak jest). JEst tam pole EAN (ID 225693) jako wymagane (8-18 znakow). Bez wpisania poprawnej wartosci EAN nie mozna wystawic aukcji. Zaczelo sie tak dziac wlaansie jak wprowadziliscie GTIN, czyli od poniedzialku rano.

MaciejFrackowiak commented 4 years ago

@MariuszPol Parametr EAN w podanej przez Ciebie kategorii nie jest wymagany:

{
            "id": "225693",
            "name": "EAN",
            "type": "string",
            "required": false,
            "requiredForProduct": false,
            "unit": null,
            "options": {
                "variantsAllowed": false,
                "variantsEqual": false,
                "ambiguousValueId": null,
                "dependsOnParameterId": null,
                "describesProduct": true
            },
            "restrictions": {
                "minLength": 8,
                "maxLength": 18,
                "allowedNumberOfValues": 1
            }
        },

Bez przeszkód wystawiłem właśnie testową ofertę bez uzupełnionego EAN.

MariuszPol commented 4 years ago

OK rozwiazaniem bylo nie wysylanie pola id 225693 jak jest puste.

imper86 commented 4 years ago

Cześć, ja mam problem z błędem Ean field is read-only. Set this value in parameter with id: 225693, pomimo tego, że pole EAN nie jest modyfikowane, tylko pobierane z body oferty GET /sale/offers/{id}... Czy w takim razie w requestach PUT /sale/offers/{id} wyrzucać całkowicie pole ean pomimo tego, że się nie zmienia?

Przykładowy request PUT https://api.allegro.pl/sale/offers/9388997115:

{"id":"9388997115","name":"Buty Puma REBOUND LAYUP SL 36957311","category":{"id":"257929"},"product":null,"parameters":[{"id":"11323","valuesIds":["11323_1"],"values":[],"rangeValue":null},{"id":"127048","valuesIds":["127048_1024"],"values":[],"rangeValue":null},{"id":"127848","valuesIds":["127848_2"],"values":[],"rangeValue":null},{"id":"203085","valuesIds":["203085_4"],"values":[],"rangeValue":null},{"id":"203093","valuesIds":[],"values":["26.5"],"rangeValue":null},{"id":"219629","valuesIds":["219629_286869"],"values":[],"rangeValue":null},{"id":"22728","valuesIds":["22728_3"],"values":[],"rangeValue":null},{"id":"451","valuesIds":["451_2"],"values":[],"rangeValue":null},{"id":"64","valuesIds":["64_1"],"values":[],"rangeValue":null},{"id":"7108","valuesIds":["7108_37"],"values":[],"rangeValue":null},{"id":"203097","valuesIds":["203097_215233"],"values":[],"rangeValue":null},{"id":"203101","valuesIds":["203101_215321"],"values":[],"rangeValue":null}],"ean":"4062451678876","description":{"sections":[{"items":[{"type":"IMAGE","url":"https:\/\/a.allegroimg.com\/original\/116a27\/bb3c257f4b20a74e9958c2337b5a"},{"type":"TEXT","content":"<h1>Puma REBOUND LAYUP SL 36957311<\/h1><h2>Rozmiar: 41<\/h2><ul><li>Stan: <b>nowy<\/b><\/li><li>Producent: <b>Puma<\/b><\/li><li>Numer katalogowy: <b>36957311<\/b><\/li><\/ul>"}]},{"items":[{"type":"IMAGE","url":"https:\/\/a.allegroimg.com\/original\/11229d\/650634364ac88b4221798685e16c"}]},{"items":[{"type":"IMAGE","url":"https:\/\/a.allegroimg.com\/original\/119d2f\/38ed98994b8f916e78b99e69c671"}]},{"items":[{"type":"IMAGE","url":"https:\/\/a.allegroimg.com\/original\/11f812\/f4391a054585930b83a49fa51e7d"}]},{"items":[{"type":"IMAGE","url":"https:\/\/a.allegroimg.com\/original\/119a04\/5d48a49f41b9b25ccc2e3796f70f"}]},{"items":[{"type":"IMAGE","url":"https:\/\/a.allegroimg.com\/original\/1182f3\/2db0b0494b6ba9efa47370a1e7d9"}]}]},"compatibilityList":null,"tecdocSpecification":null,"images":[{"url":"https:\/\/a.allegroimg.com\/original\/116a27\/bb3c257f4b20a74e9958c2337b5a"},{"url":"https:\/\/a.allegroimg.com\/original\/11229d\/650634364ac88b4221798685e16c"},{"url":"https:\/\/a.allegroimg.com\/original\/119d2f\/38ed98994b8f916e78b99e69c671"},{"url":"https:\/\/a.allegroimg.com\/original\/11f812\/f4391a054585930b83a49fa51e7d"},{"url":"https:\/\/a.allegroimg.com\/original\/119a04\/5d48a49f41b9b25ccc2e3796f70f"},{"url":"https:\/\/a.allegroimg.com\/original\/1182f3\/2db0b0494b6ba9efa47370a1e7d9"}],"sellingMode":{"format":"BUY_NOW","price":{"amount":211,"currency":"PLN"},"startingPrice":null,"minimalPrice":null,"netPrice":null},"tax":null,"stock":{"available":6,"unit":"UNIT"},"publication":{"duration":null,"status":"ACTIVE","startingAt":null,"endingAt":null,"endedBy":null,"republish":false},"delivery":{"shippingRates":{"id":"225ffcb3-bec5-4e93-bbd3-1ffa0f74eccf"},"handlingTime":"PT24H","additionalInfo":null,"shipmentDate":null},"payments":{"invoice":"VAT"},"afterSalesServices":{"impliedWarranty":{"id":"f9657b7a-4c0d-45dd-9bb5-d88fa947f9d6"},"returnPolicy":{"id":"0d7661e0-412e-4818-b643-7a91bc8a98a4"},"warranty":{"id":"cc84754a-58c9-40ab-ab74-2d682d32c0f7"}},"additionalServices":null,"sizeTable":null,"fundraisingCampaign":null,"promotion":{"emphasized":false,"bold":false,"highlight":false,"departmentPage":false,"emphasizedHighlightBoldPackage":false},"location":{"countryCode":"PL","province":"LODZKIE","city":"\u0141\u00f3d\u017a","postCode":"90-516"},"external":{"id":"106580"},"attachments":[],"contact":null,"validation":{"errors":[],"validatedAt":"2020-06-29T05:12:55.271Z"},"createdAt":"2020-06-15T11:05:30.000Z","updatedAt":"2020-06-29T05:12:55.771Z"}

response body:

{"errors":[{"code":"VALIDATION_ERROR","message":"Ean field is read-only. Set this value in parameter with id: 225693.","details":"","path":"","userMessage":"Ean field is read-only. Set this value in parameter with id: 225693."}]}

traceid: c5c776a0e6b549aa

edit jeszcze GET na tej samej ofercie:

{
  "id": "9388997115",
  "name": "Buty Puma REBOUND LAYUP SL 36957311",
  "category": {
    "id": "257929"
  },
  "product": null,
  "parameters": [
    {
      "id": "11323",
      "valuesIds": [
        "11323_1"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "127048",
      "valuesIds": [
        "127048_1024"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "127848",
      "valuesIds": [
        "127848_2"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "203085",
      "valuesIds": [
        "203085_4"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "203093",
      "valuesIds": [],
      "values": [
        "26.5"
      ],
      "rangeValue": null
    },
    {
      "id": "219629",
      "valuesIds": [
        "219629_286869"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "22728",
      "valuesIds": [
        "22728_3"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "451",
      "valuesIds": [
        "451_2"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "64",
      "valuesIds": [
        "64_1"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "7108",
      "valuesIds": [
        "7108_37"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "203097",
      "valuesIds": [
        "203097_215233"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "203101",
      "valuesIds": [
        "203101_215321"
      ],
      "values": [],
      "rangeValue": null
    },
    {
      "id": "225693",
      "valuesIds": [],
      "values": [
        "4062451678876"
      ],
      "rangeValue": null
    }
  ],
  "ean": "4062451678876",
  "description": {
    "sections": [
      {
        "items": [
          {
            "type": "IMAGE",
            "url": "https://a.allegroimg.com/original/116a27/bb3c257f4b20a74e9958c2337b5a"
          },
          {
            "type": "TEXT",
            "content": "<h1>Puma REBOUND LAYUP SL 36957311</h1><h2>Rozmiar: 41</h2><ul><li>Stan: <b>nowy</b></li><li>Producent: <b>Puma</b></li><li>Numer katalogowy: <b>36957311</b></li></ul>"
          }
        ]
      },
      {
        "items": [
          {
            "type": "IMAGE",
            "url": "https://a.allegroimg.com/original/11229d/650634364ac88b4221798685e16c"
          }
        ]
      },
      {
        "items": [
          {
            "type": "IMAGE",
            "url": "https://a.allegroimg.com/original/119d2f/38ed98994b8f916e78b99e69c671"
          }
        ]
      },
      {
        "items": [
          {
            "type": "IMAGE",
            "url": "https://a.allegroimg.com/original/11f812/f4391a054585930b83a49fa51e7d"
          }
        ]
      },
      {
        "items": [
          {
            "type": "IMAGE",
            "url": "https://a.allegroimg.com/original/119a04/5d48a49f41b9b25ccc2e3796f70f"
          }
        ]
      },
      {
        "items": [
          {
            "type": "IMAGE",
            "url": "https://a.allegroimg.com/original/1182f3/2db0b0494b6ba9efa47370a1e7d9"
          }
        ]
      }
    ]
  },
  "compatibilityList": null,
  "tecdocSpecification": null,
  "images": [
    {
      "url": "https://a.allegroimg.com/original/116a27/bb3c257f4b20a74e9958c2337b5a"
    },
    {
      "url": "https://a.allegroimg.com/original/11229d/650634364ac88b4221798685e16c"
    },
    {
      "url": "https://a.allegroimg.com/original/119d2f/38ed98994b8f916e78b99e69c671"
    },
    {
      "url": "https://a.allegroimg.com/original/11f812/f4391a054585930b83a49fa51e7d"
    },
    {
      "url": "https://a.allegroimg.com/original/119a04/5d48a49f41b9b25ccc2e3796f70f"
    },
    {
      "url": "https://a.allegroimg.com/original/1182f3/2db0b0494b6ba9efa47370a1e7d9"
    }
  ],
  "sellingMode": {
    "format": "BUY_NOW",
    "price": {
      "amount": "211",
      "currency": "PLN"
    },
    "startingPrice": null,
    "minimalPrice": null,
    "netPrice": null
  },
  "tax": null,
  "stock": {
    "available": 6,
    "unit": "UNIT"
  },
  "publication": {
    "duration": null,
    "status": "ACTIVE",
    "startingAt": null,
    "endingAt": null,
    "endedBy": null,
    "republish": false
  },
  "delivery": {
    "shippingRates": {
      "id": "225ffcb3-bec5-4e93-bbd3-1ffa0f74eccf"
    },
    "handlingTime": "PT24H",
    "additionalInfo": null,
    "shipmentDate": null
  },
  "payments": {
    "invoice": "VAT"
  },
  "afterSalesServices": {
    "impliedWarranty": {
      "id": "f9657b7a-4c0d-45dd-9bb5-d88fa947f9d6"
    },
    "returnPolicy": {
      "id": "0d7661e0-412e-4818-b643-7a91bc8a98a4"
    },
    "warranty": {
      "id": "cc84754a-58c9-40ab-ab74-2d682d32c0f7"
    }
  },
  "additionalServices": null,
  "sizeTable": null,
  "fundraisingCampaign": null,
  "promotion": {
    "emphasized": false,
    "bold": false,
    "highlight": false,
    "departmentPage": false,
    "emphasizedHighlightBoldPackage": false
  },
  "location": {
    "countryCode": "PL",
    "province": "LODZKIE",
    "city": "Łódź",
    "postCode": "90-516"
  },
  "external": {
    "id": "106580"
  },
  "attachments": [],
  "contact": null,
  "validation": {
    "errors": [],
    "validatedAt": "2020-06-29T05:12:55.271Z"
  },
  "createdAt": "2020-06-15T11:05:30.000Z",
  "updatedAt": "2020-06-29T05:12:55.771Z"
}
MaciejFrackowiak commented 4 years ago

@imper86 Pobierając ofertę poprzez GET /sale/offers/{offerId} otrzymujesz wartość EAN w parametrze 225693 - i w takim samym układzie musisz wysłać PUT - wraz z uzupełnionym parametrem. Jeżeli tego nie zrobisz i będziesz przekazywać EAN tylko w polu "ean" to wówczas zwracamy komunikat ""Ean field is read-only...."

imper86 commented 4 years ago

@MaciejFrackowiak ok, wygląda na to, że teraz jest ok

jcudzich commented 4 years ago

@MaciejFrackowiak Czy ta zmiana nie jest trochę zbyt inwazyjna jak na stabilne api?

MaciejFrackowiak commented 4 years ago

@jcudzich Nie, zapowiedzieliśmy ją z odpowiednim wyprzedzeniem. Co kluczowe, wartości z pola "ean" przenieśliśmy automatycznie do nowego parametru GTIN, zatem pobierając ofertę GET /sale/offers/{offerId} otrzymujesz uzupełniony parametr, gdzie następnie wysłany PUT /sale/offers/{offerId} przyjmie zawartość GETa.

walec51 commented 3 years ago

1) w których kategoriach można obecnie robić wyszukiwanie po ean w stylu

/offers/listing?category.id=...&parameter.225693=5900512320618

2) czy Allegro będzie docelowo wspierać ten parametr we wszystkich kategoriach?

jeżeli tak to mam propozycje aby umożliwić szukania ofert na danych EAN we wszystkich kategoriach\:

/offers/listing?parameter.225693=5900512320618

MaciejFrackowiak commented 3 years ago

@walec51 Nie, filtrowanie z użyciem parametru GTIN nie jest dostępne. Obecnie wprowadzając kod GTIN jako phrase otrzymasz oferty, które mają podaną daną wartość GTIN.

walec51 commented 3 years ago

@MaciejFrackowiak słabe to rozwiązanie bo np. https://api.allegro.pl/offers/listing?phrase=5900541000031 zwraca mi nie tylko oferty produktowe na ten konkretny produkt (zgrzewka wody żywiec 6 x 1,5 L) - na pierwszym miejscu jest np. usługa dostawy wody gdzie między wieloma oferowanymi produktami jest też 5900541000031

a jako że w publicznych danych nie zwracacie product id to nie mam jak tego odfiltrować

gdybyście umożliwili pobranie ofert produktowych pod konkretny product id to można by Wasze oferty zacząć integrować z porównywarkami cen produktów, które opierają się na kodach GTIN

MaciejFrackowiak commented 3 years ago

@walec51 Za prawidłowość przypisania GTIN do oferty odpowiada sprzedający - w tym konkretnym przypadku sprzedający dodał dany EAN do usługi dostawy produktu, której przedmiotem jest produkt z konkretnym EAN - nie sposób nam to weryfikować w ujęciu milionów trwających ofert. Korzystając z GET /sale/products?ean=5900541000031 otrzymasz id produktu, który następnie można przypisać do oferty. Obecnie dla części kategorii wymagamy przypisania 1% ofert do produktów - z biegiem czasu zakres procentowy będziemy podnosić, a to w rezultacie spowoduje przypisanie właściwych produktów do ofert.