Przesyłanie partii produktów#

POST https://sdkapi.ideal.house/product-import/products

Ciało żądania#

Przesyłaj processImages jako wartość logiczną JSON (true lub false), a nie jako ciąg znaków, np. "true" lub "false". Istniejące integracje wymagające wstępnej obróbki obrazów muszą teraz wprost przesyłać processImages: true.

Pola produktu#

Ponowny import istniejących produktów#

Aby zaktualizować dane produktu, prześlij produkt ponownie przez POST /product-import/products. Produkty są dopasowywane po shopId i sku. Gdy ten sam SKU już istnieje w sklepie, istniejący rekord produktu jest aktualizowany zamiast tworzenia duplikatu, a wartości dostarczone przez najnowszy import nadpisują odpowiadające im zapisane wartości, w tym pola takie jak name, URLs produktu, status i wymiary.

Punkt końcowy importu partii nie jest punktem końcowym częściowej aktualizacji. Każdy przesłany element musi spełniać wszystkie wymagane reguły pól produktu, nawet gdy SKU już istnieje.

SKU jest tożsamością importu i nie można go zmienić przez ponowny import. Przesłanie innego SKU tworzy lub aktualizuje inny produkt. Aby zastąpić SKU, logicznie usuń stary produkt i zaimportuj produkt pod nowym SKU.

Informacje o produkcie są aktualizowane nawet, gdy obraz się nie zmienił. Przetwarzanie obrazów jest opcjonalne przy każdym przesłaniu: ustaw processImages: true, gdy jest to potrzebne. Produkt wcześniej zaimportowany bez przetwarzania obrazów może zostać przesłany ponownie z tą opcją włączoną.

Obsługiwane typy produktów#

API akceptuje następujące dokładne, wrażliwe na wielkość liter wartości productType. Wiele nazw w jednym wierszu to aliasy tego samego typu produktu Ideal House.

Na przykład "Rugs", "Area Rugs" i "Area Rug" są wszystkie poprawne i są traktowane jako ten sam typ produktu. Każda wartość niewymieniona powyżej zwraca 400 Bad Request.

Status importu#

Opcjonalne pole status akceptuje następujące dokładne wartości:

Każda inna wartość, w tym sold_out, zwraca 400 Bad Request.

Dla mebli, przesłania nieaktywne zwracają produkt status: inactive. Przesłanie aktywne może zwrócić unprocessed, co oznacza, że produkt nie jest jeszcze gotowy do wyświetlenia. Nie oznacza to, że zlecono generowanie 3D.

Generowanie modeli 3D dla mebli#

Generowanie modeli 3D mebli jest czasochłonne i zużywa kredyty, dlatego nie odbywa się podczas importu produktów, nawet gdy processImages ma wartość true. W przyszłości planujemy udostępnić opcję generowania w interfejsie lub osobne API do generowania 3D. Jeśli potrzebujesz modeli 3D już teraz, napisz do swojej osoby kontaktowej w Ideal House, aby ustalić generowanie osobno.

SKU i zachowanie aktualizacji#

Ideal House identyfikuje produkt po kombinacji shopId i sku:

• Jeśli SKU nie istnieje dla sklepu, tworzony jest nowy produkt.
• Jeśli SKU już istnieje dla sklepu, istniejący produkt jest aktualizowany.

Dzięki temu bezpieczne jest ponowne przesłanie produktu z tym samym SKU po niepewnym wyniku sieciowym. Używaj stabilnych SKU i nie generuj nowego SKU przy ponownej próbie tego samego produktu. Unikaj wysyłania tego samego SKU więcej niż raz w jednej partii.

Wymagania dotyczące obrazów#

• URL musi być dostępny dla serwerów Ideal House bez plików cookie, sesji logowania lub niestandardowych nagłówków żądania.
• Używaj stabilnego URL, który zwraca obraz bezpośrednio.
• Utrzymuj dostępność źródłowego obrazu do momentu, aż zadanie importu osiągnie status końcowy.
• Problemy z pobieraniem lub przetwarzaniem obrazów są raportowane jako błędy na poziomie elementu.
• Aby tworzyć obrazy desek podłogowych, ustaw zarówno processImages: true, jak i processFloorImages: true.

Opcjonalne przetwarzanie obrazów i kredyty#

Wstępna obróbka obrazów jest domyślnie wyłączona:

• Przy processImages: false lub gdy pole jest pominięte, aktywne produkty używają swoich oryginalnych obrazów bez usuwania tła, optymalizacji tekstury ani segmentacji podłogi. Informacje o produkcie są nadal importowane lub aktualizowane, a nie jest pobierany kredyt za przetwarzanie obrazów. Produkty nieaktywne podlegają regułom statusu opisanym powyżej.
• Przy processImages: true, obsługiwane aktywne produkty otrzymują przetwarzanie obrazów opisane poniżej. Generowanie 3D dla mebli nie jest wliczone.

Główne zachowania przetwarzania to:

Mural i Wall Mural otrzymują te same ulepszenia obrazów co Wall. Aby uzyskać najlepsze wyniki, dostarczaj kompletnych i wyraźnych obrazów produktów; dywany i regularne obrazy na ścianę powinny mieć białe lub prawie białe tło, a obrazy ścienne powinny unikać poważnych zniekształceń perspektywy.

Opisane powyżej przetwarzanie obrazów kosztuje 1 kredyt za każdy nowo przetworzony obraz, w tym optymalizację tekstury ściany. Jeśli można użyć istniejącego wyniku przetwarzania, nie jest pobierany dodatkowy kredyt za przetwarzanie. Upewnij się, że masz wystarczające kredyty przed włączeniem tej opcji. Przy niewystarczających kredytach przetwarzanie obrazów nie zostanie wykonane, a produkt może pozostać w stanie unprocessed. Partia importu completed sama w sobie nie potwierdza, że każdy obraz produktu został pomyślnie przetworzony.

Wymagania dotyczące wymiarów#

API nie ma osobnego pola jednostki wymiarów. width jest wymagane. height jest normalnie wymagane, podczas gdy produkt typu Floor może podać length zamiast niego; gdy oba są obecne, length jest używany jako długość deski podłogowej. Liczby bez jednostki i ciągi liczbowe są interpretowane jako cale. Ciągi mogą zawierać in, ft, cm, mm lub m; wartości są walidowane jako dodatnie wymiary i normalizowane do cali przed zapisem. thickness jest opcjonalne i akceptuje również zakres, np. "3-4 mm", który jest normalizowany do "0.1-0.2 in".

dimension_display jest opcjonalną etykietą wyświetlania i nie jest używana do walidacji rozmiaru ani konwersji jednostek. Może używać jednostki i formatu skierowanego do klienta, który chcesz wyświetlić, np. "24 in x 36 in" lub "26 cm x 36 cm".

Przykład żądania#

{
  "shopId": "shop_123",
  "processImages": false,
  "processFloorImages": false,
  "products": [
    {
      "sku": "SKU-10001",
      "name": "Gold Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
      "productUrl": "https://www.example.com/products/SKU-10001",
      "width": "24.0 in",
      "height": "36.0 in",
      "thickness": "2.0 in",
      "dimension_display": "24 in x 36 in",
      "category": "Mirror",
      "color": "Gold",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "active",
      "groupId": "mirror-series-01"
    },
    {
      "sku": "SKU-10002",
      "name": "Black Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10002.png",
      "productUrl": "https://www.example.com/products/SKU-10002",
      "width": "2 ft",
      "height": "3 ft",
      "thickness": "3-4 mm",
      "dimension_display": "2 ft x 3 ft",
      "category": "Mirror",
      "color": "Black",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "out_of_stock",
      "groupId": "mirror-series-01"
    }
  ]
}

Przykład cURL (Przetwarzanie obrazów włączone)#

Ten przykład wprost włącza wstępną obróbkę obrazów. Nowy wynik usuwania tła zużywa 1 kredyt.

curl --request POST \
  'https://sdkapi.ideal.house/product-import/products' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
  --header 'X-Client-Secret: <YOUR_CLIENT_SECRET>' \
  --data-raw '{
    "shopId": "shop_123",
    "processImages": true,
    "products": [
      {
        "sku": "SKU-10001",
        "name": "Gold Wall Mirror",
        "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
        "productUrl": "https://www.example.com/products/SKU-10001",
        "width": 24,
        "height": 36,
        "thickness": 2,
        "dimension_display": "24 in x 36 in",
        "category": "Mirror",
        "color": "Gold",
        "brand": "Example Brand",
        "productType": "Wall Art",
        "status": "active",
        "groupId": "mirror-series-01"
      }
    ]
  }'

Zaakceptowana odpowiedź#

Poprawne żądanie zwraca 202 Accepted. Przetwarzanie kontynuowane jest asynchronicznie.

{
  "jobId": "1930000000000000000",
  "shopId": "shop_123",
  "status": "pending",
  "totalCount": 1,
  "processedCount": 0,
  "successCount": 0,
  "failedCount": 0,
  "failures": [],
  "createdAt": "2026-07-21T06:30:00.000Z",
  "startedAt": null,
  "updatedAt": "2026-07-21T06:30:00.000Z",
  "completedAt": null,
  "error": null
}

Jeśli sklep ma już zadanie pending lub running, API zwraca 409 Conflict. Poczekaj, aż bieżące zadanie się zakończy, zanim prześlesz kolejną partię.