Dodawanie pojedynczego produktu

Sposób działania

Import produktów to proces dwuetapowy (ładowanie wsadowe):

1. POST /import/products/v2/load_data — wgrywa zbiór definicji produktów (plik JSON) do bufora danych. Można go wywołać wielokrotnie z parametrem continueUpload=1, aby doklejać kolejne paczki do bufora (continueUpload=0 czyści bufor przed wgraniem).

2. POST /import/products/v2/run — przenosi dane z bufora do bazy produkcyjnej (jednorazowo, dla całej zawartości bufora).

Podczas przenoszenia system sprawdza, czy dany kod produktu (pole code) już istnieje. Jeśli produkt o tym kodzie już istnieje — zostaje pominięty (import nie nadpisuje istniejących produktów).

Jak wysłać request

Endpoint load_data przyjmuje dane jako multipart/form-data — NIE jako surowe body JSON. Tablica produktów (JSON) jest wysyłana jako plik w polu formularza file. {instancja} = adres API Twojej instancji Saly (np. https://twoja-domena/api).

Krok 1 — token. Wyślij POST na /user/token w formacie application/x-www-form-urlencoded z polami username oraz hasłem. W odpowiedzi otrzymasz access_token — wstaw go do nagłówka autoryzacji (typ Bearer) w kolejnych żądaniach.

Krok 2 — load_data (POST /import/products/v2/load_data), żądanie typu multipart/form-data:

Krok 3 — run (POST /import/products/v2/run): nagłówek Bearer, parametry w query string: truncate_all_products oraz truncate_all_categories (zwykle oba 0). Odpowiedź zawiera report (patrz „Odpowiedź i raport").

Typy produktów

Tym endpointem można dodać dwa typy produktów:

• Produkt pojedynczy

• Rodzina produktów (warianty)

Produkt pojedynczy — dokumentacja pól

Legenda kolumny typ: * pole wymagane · X dowolne znaki · [0-1] tylko 0 lub 1 · [0-9] liczby · R2 liczba dziesiętna z 2 miejscami · JSON obiekt/tablica JSON · (x) limit znaków · date (YYYY-mm-dd) data.

code wymagane

additional_code

information

metadata

categories

price

manufacturer

energy_class

stock — stany magazynowe i flaga "stock impact"

delivery_date — czas dostawy zapisywany do magazynów (tablica wpisów per magazyn):

units — jednostki sprzedażowe i ich ceny

Sekcja units to tablica jednostek sprzedażowych produktu. Każda jednostka musi odwoływać się (przez external_id) do jednostki wcześniej zdefiniowanej w Słownikach → Jednostki sprzedażowe w panelu administratora.

Model i ceny jednostek

• Jednostka podstawowa (primary) — baza wszystkich przeliczeń i jednostka, w której śledzony jest stan magazynowy. Jej rate jest zawsze 1 (niezmienny).

• rate (przelicznik) — ile jednostek podstawowych mieści jedna ta jednostka. Cena tej jednostki = cena katalogowa (srp_netto) × rate.

• discount (rabat %) — rabat naliczany, gdy wybrana jest ta jednostka.

• minimum_sales_quantity — minimalna ilość zamówienia w tej jednostce (liczba całkowita > 0).

• Jednostka domyślna (default) — wstępnie wybrana przy wyświetlaniu; musi być aktywna.

• active — czy jednostka jest widoczna i wybieralna przez klienta.

Brak sekcji units — zachowanie słownikowe

Dodanie sekcji units jest opcjonalne. Gdy jej nie podasz, jednostki nowego produktu zostaną ustawione zgodnie z flagami domyślności w Słowniku. Trzy flagi słownika są honorowane niezależnie:

Niezależność oznacza, że np. jednostka z Domyślnie aktywna = ON i Domyślnie prezentowana = OFF będzie na produkcie aktywna, ale NIE domyślna. Jednostka bez żadnej z flag pozostanie nieaktywna.

Pola jednostki

package

attributes

Parametry techniczne produktu pogrupowane i w docelowej kolejności wyświetlania, w językach (JSON). Format jak w przykładzie poniżej.

multimedia

Odpowiedź i raport importu

Import jest nieblokujący — poprawne produkty zostaną zaimportowane, a o problemach z poszczególnymi jednostkami dowiesz się z odpowiedzi (batch nie jest odrzucany).

• /load_data zwraca m.in. liczniki wgranych wierszy oraz stock_unit_ignored — listę kodów produktów, które przysłały nieobsługiwane pole stock.unit (przypomnienie: jednostki definiuj w bloku units).

• /run zwraca {"status":"ok","report":{...}}, gdzie report zawiera:

  • invalid_units — lista {product_code, external_id, reason} jednostek odrzuconych (np. nieznany external_id, nie-całkowite/ujemne minimum_sales_quantity, ujemny rate/discount, wiele jednostek domyślnych);

  • products_without_primary_fallback_applied — produkty, dla których importer musiał automatycznie ustalić jednostkę podstawową (gdy payload jej nie wskazał);

  • proc_errors — błędy procedury (jeśli wystąpiły).

Dzięki temu masz pewność, które jednostki zostały przyjęte, a które wymagają poprawy w kolejnym imporcie.

Aktualizacja istniejących produktów

Endpoint /import/products/v2/* tylko dodaje nowe produkty. Aby zmienić dane istniejącego produktu — w tym stock_enabled, ceny i jednostki sprzedażowe — użyj:

POST /import/product/update

• Aktualizuje wskazane pola istniejących produktów (m.in. stock_enabled, ceny, jednostki).

• Dla jednostek sterowanie trybem przez units_increase: 0 = zastąp komplet jednostek nowym zestawem; 1 = aktualizacja częściowa (modyfikuje/dodaje przesłane jednostki, resetując konkurujące primary/default). Pusta tablica units → istniejące jednostki pozostają bez zmian.

• Reguły integralności jednostek (dokładnie 1 primary, 1 aktywna default) obowiązują tak samo.

Przykładowy plik

[
  {
    "code": "5907595646406",
    "additional_code": {
      "ean": "5907595646406",
      "sku": "Mac Book Air 13,3",
      "supplier_product_code": "5907595646406"
    },
    "information": {
      "name": { "pl": "MacBook Air 13 gwiezdna szarość", "en": "MacBook Air 13 Space Gray" },
      "description": { "pl": "<h4>MacBook Air 13</h4><p>opis</p>" },
      "is_active": "1",
      "is_promoted": "0"
    },
    "metadata": {
      "metatitle": { "pl": "MacBook Air 13 gwiezdna szarość" },
      "keywords": { "pl": "MacBook,Air,13" },
      "metadescription": { "pl": "MacBook Air 13 - najlepsza cena" },
      "slug": { "pl": "MacBook_Air_13_gwiezdna_szarosc" }
    },
    "categories": {
      "paths": [ { "pl": "Laptopy/Apple/MacBook Air 13" } ]
    },
    "price": {
      "base_netto": "4000.00",
      "purchase_netto": "3300.99",
      "srp_netto": "4499.99",
      "vat": "23"
    },
    "manufacturer": { "name": "Apple", "logo": "https://www.apple.com/logo.png" },
    "energy_class": {
      "energy_class": "A",
      "energy_label_link": "https://link.pdf",
      "energy_card_information_link": "https://link.pdf"
    },
    "stock": {
      "stock_enabled": "1",
      "delivery_date": [
        { "delivery_format": {"pl": "7 dni"}, "delivery_hour": "168", "warehouse_external_id": "1", "restocking_date": "2025-02-02" }
      ]
    },
    "package": {
      "name": "Euro-pallet",
      "dimensions": { "height": "100.00", "width": "100.00", "length": "100.00", "weight": "10.00" }
    },
    "attributes": {
      "pl": [ { "Dane techniczne": [ ["Kolor", "czerwony"], ["Rozmiar", "średni"] ] } ]
    },
    "multimedia": {
      "photos": [ "https://example.com/photo1.jpg" ],
      "files": [ ["file1.pdf", "https://example.com/file1.pdf"] ]
    },
    "units": [
      { "external_id": "szt.", "primary_unit": "1", "default_unit": "1", "active": "1", "rate": "1.0",  "discount": "0",  "minimum_sales_quantity": "1" },
      { "external_id": "opk",  "primary_unit": "0", "default_unit": "0", "active": "1", "rate": "10.0", "discount": "10", "minimum_sales_quantity": "1" }
    ]
  }
]