Przejdź do głównej zawartości

Pobieranie katalogu

OpenApp pobiera katalog produktów z endpointu udostępnionego przez merchanta i skonfigurowanego w panelu merchanta. Pierwsze pobranie importuje pełny katalog; kolejne pobrania są przyrostowe i zwracają tylko produkty zmienione od ostatniej synchronizacji.

Po początkowej pełnej synchronizacji OpenApp może również przeprowadzać pełne odświeżenie w godzinach niskiego ruchu, aby uzupełnić ewentualne luki powstałe w synchronizacjach przyrostowych.

Żądanie​

OpenApp wykonuje żądanie HTTP GET do skonfigurowanego endpointu:

GET <catalogue-url>?checkpoint=<checkpoint>&limit=<limit>
ParametrOpis
checkpointNieprzejrzysty string (patrz niżej) kodujący pozycję w katalogu, od której należy kontynuować. Nieobecny przy pełnej synchronizacji - w takim przypadku należy zwrócić wszystkie produkty.
limitMaksymalna liczba produktów, którą OpenApp chce otrzymać na jednej stronie.

Format checkpointu​

Checkpoint to string zakodowany w Base64 zawierający epoch milisekundy updatedAt oraz id ostatniego produktu zwróconego na poprzedniej stronie, oddzielone dwukropkiem:

Base64("<updatedAt epoch millis>:<last product id>")

Każdy produkt musi zawierać wartość updatedAt, ponieważ OpenApp używa jej do tworzenia i dekodowania checkpointów.

Produkty muszą być zwracane w rosnącej kolejności (updatedAt, id). Merchant musi zwrócić wszystkie produkty, których updatedAt jest ściśle większe niż zakodowany znacznik czasu, oraz wszystkie produkty, których updatedAt jest równe zakodowanemu znacznikowi czasu i których id jest leksykograficznie większe niż zakodowane id (w celu obsługi remisów). To porządkowanie zapewnia przesuwanie checkpointu z każdą stroną.

Na przykład, jeśli ostatni produkt na poprzedniej stronie miał updatedAt = 2026-06-09T11:48:12.000Z i id = id123 (epoch millis 1781005692000):

MTc4MTAwNTY5MjAwMDppZDEyMw==

Zatem jeśli skonfigurowano adres https://shop.example.com/api/openapp/catalogue, żądanie wykonane przez OpenApp dla drugiej strony będzie wyglądać następująco:

GET https://shop.example.com/api/openapp/catalogue?checkpoint=MTc4MTAwNTY5MjAwMDppZDEyMw%3D%3D&limit=500

Odpowiedź​

W odpowiedzi merchant zwraca stronę produktów wraz z nextCheckpoint kodującym pozycję ostatniego produktu na stronie. Merchant musi uwzględnić nextCheckpoint, gdy products jest niepuste. OpenApp wysyła kolejne żądania stron, dopóki nie otrzyma strony z pustą tablicą products - wtedy ostatni otrzymany nextCheckpoint jest zapisywany jako checkpoint dla następnej synchronizacji przyrostowej.

Produkty są zwracane w rosnącej kolejności (updatedAt, id). W poniższym przykładzie wycofany produkt był ostatnio aktualizowany najwcześniej i dlatego pojawia się pierwszy; dwa aktywne produkty następują w kolejności chronologicznej.

{
  "currency": "PLN",
  "products": [
    {
      "id": "id125",
      "updatedAt": "2026-06-07T16:30:00.000Z",
      "name": "Discontinued product",
      "status": "DELISTED",
      "variants": [
        {
          "id": "id125",
          "unitPrice": 4500,
          "stock": {
            "isAvailable": false
          }
        }
      ]
    },
    {
      "id": "id124",
      "updatedAt": "2026-06-08T09:15:00.000Z",
      "name": "Superb product 2",
      "categories": [
        "Home",
        "Kitchen",
        "Cookware"
      ],
      "images": [
        "http://cdn.merchant.com/static/products/id124/1"
      ],
      "url": "https://shop.example.com/products/id124",
      "status": "ACTIVE",
      "variants": [
        {
          "id": "id124",
          "ean": "5901234123464",
          "unitPrice": 6000,
          "stock": {
            "isAvailable": true,
            "availableQuantity": 3
          },
          "measurement": {
            "type": "VOLUME",
            "quantityValue": 500,
            "quantityUnit": "ML"
          }
        }
      ]
    },
    {
      "id": "id123",
      "updatedAt": "2026-06-09T11:48:12.000Z",
      "name": "Superb product",
      "description": "A superb product that makes everyday cooking easier.",
      "brandName": "SuperBrand",
      "categories": [
        "Home",
        "Kitchen",
        "Cookware"
      ],
      "images": [
        "http://cdn.merchant.com/static/products/id123/1",
        "http://cdn.merchant.com/static/products/id123/2"
      ],
      "url": "https://shop.example.com/products/id123",
      "status": "ACTIVE",
      "variants": [
        {
          "id": "id123-red",
          "name": "Red",
          "ean": "5901234123457",
          "unitPrice": 6000,
          "originalUnitPrice": 7000,
          "stock": {
            "isAvailable": true,
            "availableQuantity": 5
          },
          "measurement": {
            "type": "WEIGHT",
            "quantityValue": 0.3,
            "quantityUnit": "KG",
            "referenceValue": 100,
            "referenceUnit": "G"
          }
        },
        {
          "id": "id123-blue",
          "name": "Blue",
          "ean": "5901234123471",
          "unitPrice": 7000,
          "stock": {
            "isAvailable": true
          },
          "measurement": {
            "type": "WEIGHT",
            "quantityValue": 0.3,
            "quantityUnit": "KG",
            "referenceValue": 100,
            "referenceUnit": "G"
          }
        }
      ]
    }
  ],
  "nextCheckpoint": "MTc4MTAwNTY5MjAwMDppZDEyMw=="
}

Produkty i warianty​

Każdy produkt zawiera co najmniej jeden wariant. Dla produktów z pojedynczym wariantem należy podać dokładnie jeden wariant - jego id może być takie samo jak id produktu. Ceny, stan magazynowy, jednostka miary i kod kreskowy są przypisane do wariantu, nie do produktu.

id wariantu to identyfikator używany we wszystkich pozostałych API: pobieraniu koszyka, składaniu zamówienia, feedzie zamówień rekomendacji, feedzie wishlisty i odpowiedziach rekomendacji.

Każda zmiana wariantu - cena, stan magazynowy, EAN - musi zaktualizować updatedAt produktu, ponieważ synchronizacja przyrostowa i checkpointy działają na poziomie produktu.

Stan magazynowy jest wyrażony jako { isAvailable, availableQuantity? }. availableQuantity jest obecne tylko wtedy, gdy merchant śledzi stany magazynowe. isAvailable: true bez availableQuantity oznacza, że wariant jest dostępny, ale stany nie są śledzone.

wskazówka

Pola ean wariantu, images produktu i brandName produktu są opcjonalne, ale ich uwzględnienie znacząco poprawia algorytm rekomendacji. Podanie tych pól jest zalecane.

Jeśli endpoint merchanta zwróci błąd lub przekroczy czas oczekiwania podczas zaplanowanego pobierania, OpenApp ponowi próbę przy następnym cyklu synchronizacji. Nie jest wymagane żadne działanie ze strony merchanta.

informacja

Produkty usunięte z systemu merchanta nie mogą pojawić się w odpowiedzi synchronizacji przyrostowej. Aby poinformować OpenApp o usunięciu, należy:

  • Oznaczyć produkt jako DELISTED i nadal zwracać go w odpowiedziach przyrostowych tak długo, jak system merchanta przechowuje jego zapis, lub
  • Pozwolić OpenApp obsłużyć to automatycznie: podczas każdego okresowego pełnego odświeżenia wszystkie produkty wcześniej znane OpenApp, nieobecne w odpowiedzi merchanta, zostaną automatycznie wycofane.