REST API

Aktualna dokumentacja nowoczesnego interfejsu rest api jest dostępna pod adresem https://developers.shoper.pl/

REST API - dokumentacja interfejsu























product.create

Dodaje produkt

        array call(string $session_id, "product.create", array($data))
    

Parametry wejściowe

  • data (array) - tablica asocjacyjna z danymi obiektu o strukturze:
    • producer_id (int) - (opcjonalne) identyfikator producenta
    • tax_id (int) - (wymagane do wersji 5.7.4) identyfikator stawki podatkowej
    • category_id (int) - (wymagane) identyfikator głównej kategorii
    • unit_id (int) - (wymagane do wersji 5.7.4) identyfikator jednostki miary
    • other_price (double) - (opcjonalne) cena produktu w innych sklepach
    • code (string) - (wymagane do wersji 5.7.4 oraz kiedy nie jest podany domyślny sposób generowania) kod produktu
    • ean (string) - (opcjonalne) kod ean produktu
    • unit_price_calculation (int[0/1]) - czy produkt ma włączone obliczanie ceny jednostkowej
    • pkwiu (string) - (opcjonalne) pkwiu produktu
    • is_product_of_day (boolean) - czy produkt jest produktem dnia
    • gauge_id (int) - (opcjonalne) identyfikator gabarytu
    • currency_id (int) - (opcjonalne) identyfikator waluty produktu
    • dimension_w (float) - (opcjanalne) szerokość produktu
    • dimension_h (float) - (opcjonalne) wysokość produktu
    • dimension_l (float) - (opcjonalne) długość produktu
    • vol_weight (float) - (opcjonalne) waga gabarytowa produktu
    • additional_isbn (string) - (opcjonalne) kod ISBN (tylko jeśli jest aktywny w sklepie)
    • additional_kgo (string) - (opcjonalne) kod KGO (tylko jeśli jest aktywny w sklepie)
    • additional_bloz7 (string) - (opcjonalne) kod BLOZ7 (tylko jeśli jest aktywny w sklepie)
    • additional_bloz12 (string) - (opcjonalne) kod BLOZ12 (tylko jeśli jest aktywny w sklepie)
    • additional_producer (string) - (opcjonalne) kod producenta (tylko jeśli jest aktywny w sklepie)
    • specialOffer (array) - (opcjonalne)
      • datefrom (string) - (wymagane) data (w formacie yyyy-mm-dd) rozpoczęcia promocji
      • dateto (string) - (wymagane) data (w formacie yyyy-mm-dd) zakończenia promocji
      • promoprice (float) - (wymagane) cena promocyjna
      • promoprice_wholesale (float) - (opcjonalne) cena promocyjna hurtowa 1
      • promoprice_special (float) - (opcjonalne)cena promocyjna hurtowa 2
    • stock (array) - (wymagane) tablica asocjacyjna z informacjami o magazynie wariantu podstawowego:
      • price (float) - (wymagane) cena wariantu podstawowego
      • price_wholesale (float) - (opcjonalne) cena hurtowa 1 wariantu podstawowego
      • price_special (float) - (opcjonalne) cena hurtowa 2 wariantu podstawowego
      • price_buying (float) - (opcjonalne) cena zakupu
      • stock (float) - (opcjonalne) stan magazynowy
      • stock_relative (float) - (opcjonalne) różnica stanu magazynowego o jaką ma zostać zaktualizowa wartość w sklepie. Jeśli ten parametr występuje, parametr 'stock' nie jest brany pod uwagę podczas aktualizacji danych.
      • warn_level (float) - (opcjonalne) alarm magazynowy
      • sold (float) - (opcjonalne) ilość sprzedanego towaru
      • sold_relative (float) - (opcjonalne) różnica ilości sprzedanego towaru o jaką ma zostać zaktualizowa wartość w sklepie. Jeśli ten parametr występuje, parametr 'sold' nie jest brany pod uwagę podczas aktualizacji danych.
      • weight (float) - (opcjonalne) waga towaru
      • availability_id (int) - (opcjonalne) identyfikator dostępności wariantu
      • delivery_id (int]) - (opcjonalne) identyfikator czasu dostawy wariantu
      • gfx_id (int|null) - (opcjonalne) identyfikator zdjęcia produktu, które przedstawia dany wariant
      • calculation_unit_id (int|null) - identufikator jednostki miary dla przeliczania ceny jednostkowej
      • calculation_unit_ratio (float) - współczynnik przeliczania ceny jednostkowej
      • warehouses (array) - tablica asocjacyjna, której kluczami są identyfikatory magazynów, a wartością jest stan magazynowy w tym magazynie
    • translations (array) - (wymagane) tablica asocjacyjna z istniejącymi tłumaczeniami obiektu. Kluczami tablicy są nazwy lokalizacji, a wartościami tablice asocjacyjne informacji o tłumaczeniach:
      • pl_PL (array) - przykładowa tablica z informacjami o tłumaczeniu w lokalizacji pl_PL
        • name (string) - (wymagane) nazwa produktu
        • short_description (string) - (opcjonalne) krótki opis produktu
        • description (string) - (opcjonalne) opis produktu
        • active (int) - [0/1]) - (wymagane) aktywność produktu
        • seo_title (string) - (opcjonalne) tytuł wyświetlany w tagu <title>
        • seo_description (string) - (opcjonalne) opis wyświetlany w tagu meta description
        • seo_keywords (string) - (opcjonalne) opis wyświetlany w tagu meta keywords
        • seo_url (string|null) - (opcjonalne) względny adres produktu
        • order (int) - (opcjonalne) priorytet brany pod uwagę podczas sortowania listy produktów
        • main_page (int) - [0/1]) - (opcjonalne) czy produkt został wyróżniony na stronie głównej
        • main_page_order (int) - (opcjonalne) priorytet brany pod uwagę podczas sortowania listy produktów na stronie głównej
    • options (array) - (opcjonalne) tablica asocjacyjna, której wartościami są tablice asocjacyjne z danymi wariantu do aktualizacji:
      • price (float) - (wymagane) cena lub różnica ceny w stosunku do ceny wariantu podstawowego - zawsze dodatnia
      • price_type (int) - (wymagane) typ obliczania ceny (**0** - brak ustalonej ceny, **1** - nowa cena wariantu, **2** - cena zostanie dodana do ceny podstawowej, **3** - cena zostanie odjęta od ceny podstawowej)
      • price_wholesale (float) - (opcjonalne) cena hurtowa 1 lub różnica ceny w stosunku do ceny hurtowej 1 wariantu podstawowego - zawsze dodatnia
      • price_wholesale_type (int) - (opcjonalne) typ obliczania ceny hurtowej 1 (**0** - brak ustalonej ceny, **1** - nowa cena wariantu, **2** - cena zostanie dodana do ceny podstawowej, **3** - cena zostanie odjęta od ceny podstawowej)
      • price_special (float) - (opcjonalne) cena hurtowa 2 lub różnica ceny w stosunku do ceny hurtowej 2 wariantu podstawowego - zawsze dodatnia
      • price_special_type (int) - (opcjonalne) typ obliczania ceny hurtowej 2 (**0** - brak ustalonej ceny, **1** - nowa cena wariantu, **2** - cena zostanie dodana do ceny podstawowej, **3** - cena zostanie odjęta od ceny podstawowej)
      • active (int) - [0/1]) - (wymagane) aktywność wariantu produktu
      • default (int) - [0/1]) - (wymagane) czy wariant produktu ma być domyślnie zaznaczonym wariantem przy wyborze
      • stock (float) - (wymagane) stan magazynowy
      • stock_relative (float) - (opcjonalne) różnica stanu magazynowego o jaką ma zostać zaktualizowa wartość w sklepie. Jeśli ten parametr występuje, parametr 'stock' nie jest brany pod uwagę podczas aktualizacji danych.
      • warn_level (float) - (opcjonalne) alarm magazynowy
      • sold (float) - (opcjonalne) ilość sprzedanego towaru
      • sold_relative (float) - (opcjonalne) różnica ilości sprzedanego towaru o jaką ma zostać zaktualizowa wartość w sklepie. Jeśli ten parametr występuje, parametr 'sold' nie jest brany pod uwagę podczas aktualizacji danych.
      • code (string) - (opcjonalne) kod wariantu
      • ean (string) - (opcjonalne) kod ean wariantu
      • weight (float) - (opcjonalne) waga towaru
      • weight_type (int) - (wymagane) typ obliczania wagi (**0** - brak ustalonej wagi, **1** - nowa waga wariantu, **2** - waga zostanie dodana do wagi podstawowej, **3** - waga zostanie odjęta od wagi podstawowej)
      • availability_id (int) - (opcjonalne) identyfikator dostępności wariantu
      • delivery_id (int]) - (opcjonalne) identyfikator czasu dostawy wariantu
      • gfx_id (int) - (opcjonalne) identyfikator zdjęcia produktu, które przedstawia dany wariant
      • calculation_unit_id (int|null) - identufikator jednostki miary dla przeliczania ceny jednostkowej
      • calculation_unit_ratio (float) - współczynnik przeliczania ceny jednostkowej
      • options (array) - (wymagane) tablica zawierająca informacje o zestawie cech, które przedstawia dany wariant. Kluczami tablicy są identyfikatory cech, a wartościami identyfikatory wariantów wybranej cechy
      • warehouses (array) - tablica asocjacyjna, której kluczami są identyfikatory magazynów, a wartością jest stan magazynowy w tym magazynie
    • attributes (array) - (wymagane|opcjonalne) tablica asocjacyjna
      • 0-9+) (int|string) - (wymagane|opcjonalne) - identyfikator atrybutu => wartosc:
        • 0|1) () -
        • ----> dla "pola tekstowego" (string) -
        • ----> dla "pola wyboru" (string) - nazwa pola wyboru

Wartość zwracana

  • dodatni identyfikator dodanego obiektu lub kod błędu: (int)

Rzucane wyjątki SoapFault

  • W przypadku nie podania danych w formie tablicy, rzucany jest wyjątek

Uwagi

  • Istnieje możliwość wystąpienia wyjątku SoapFault w przypadku nieprawidłowego działania modułu aplikacji. (np poprzez modyfikację kodu aplikacji lub poprzez nieoczekiwany błąd po stronie serwera)

Przykład wywołania w PHP

<?php

/**
 * Logowanie do API
 * 
 * @param resource $c cURL resource handle
 * @param string $login Login użytkownika
 * @param string $password Hasło użytkownika
 * @return string Indentyfikatorr sesji użytkownika
 */
function login($c, $login, $password) {
    $params = Array(
        "method" => "login",
        "params" => Array($login, $password)
    );
    curl_setopt($c, CURLOPT_POSTFIELDS, "json=" . json_encode($params));
    $result = (Array) json_decode(curl_exec($c));
    if (isset($result['error'])) {
        return null;
    } else {
        return $result[0];
    }
}

/**
 * Pobranie błędów
 * 
 * @param resource $c cURL resource handle
 * @param string $session Indentyfikatorr sesji użytkownika
 */
function getError($c, $session){
	$params = Array(
        "method" => "call",
        "params" => Array($session, 'internals.validation.errors', null)
    );
    curl_setopt($c, CURLOPT_POSTFIELDS, "json=" . json_encode($params));
    $result = (Array) json_decode(curl_exec($c));
    return $result;
}

$c = curl_init();
curl_setopt($c, CURLOPT_URL, 'http://shop.example.com/webapi/json/');
curl_setopt($c, CURLOPT_POST, true);
curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);

// zalogowanie użytkownika i pobranie identyfikatora sesji
$session = login($c, "api", "test");

if ($session != null) {
    $product = Array(        
        "producer_id" => null,
        "tax_id" => 1,
        "category_id" => 9,
        "unit_id" => 2,
        "other_price" => 9.50,
        "code" => md5(rand()),
        "pkwiu" => null,
        "stock" => Array(
            "price" => 8.99,
            "stock" => 10,
            "warn_level" => 2,
            "sold" => 0,
            "weight" => 1.2,
            "availability_id" => null,
            "delivery_id" => null,
            "gfx_id" => null,
        ),
        "translations" => Array(
            "pl_PL" => Array(
                "name" => "Produkt testowy",
                "short_description" => "Krótki opis",
                "description" => "Opis produktu testowego",
                "active" => 1,
                "seo_title" => "Produkt testowy",
                "seo_description" => "Opis produktu testowego",
                "seo_keywords" => "produkt, test, api",
                "order" => null,
                "main_page" => 0,
                "main_page_order" => null,
            ),
        ),
        "options" => Array( // warianty
            Array(
                "price" => 1.50,
                "price_type" => 2,  // dodanie ceny
                "stock" => 9,
                "warn_level" => 2,
                "weight" => 1.3,
                "weight_type" => 1, // nowa waga
                "active" => 1,
                "default" => 0,
                "availability_id" => null,
                "delivery_id" => null,
                "gfx_id" => null,
                "options" => Array( // id_wariantu => id_wartości
                    1 => 5,
                ),
            ),
            Array(
                "price" => 1.55,
                "price_type" => 2,  // dodanie ceny
                "stock" => 8,
                "warn_level" => 3,
                "weight" => 1.4,
                "weight_type" => 1, // nowa waga
                "active" => 1,
                "default" => 0,
                "availability_id" => null,
                "delivery_id" => null,
                "gfx_id" => null,
                "options" => Array( // id_wariantu => id_wartości
                    1 => 6,
                ),
            ),
            // itp.
        ),
    );
    
    $params = Array(
        "method" => "call",
        "params" => Array($session, "product.create", Array($product))
    );

    // zakodowanie parametrów dla metody POST
    $postParams = "json=" . json_encode($params);
    curl_setopt($c, CURLOPT_POSTFIELDS, $postParams);

    // dekodowanie rezultatu w formacie JSON do tablicy result
    $data = curl_exec($c);
    $result = (Array)json_decode($data);

    // sprawdzenie, czy wystąpił błąd
    if (isset($result['error'])) {
        echo "Wystąpił błąd: " . $result['error'] . ", kod: " . $result['code'];
    } else {
        if ($result[0] == 0) {
            echo "Operacja się nie udała";
            $err = getError($c, $session);
                foreach($err as $error){
					echo PHP_EOL.$error;
				}
        } else if ($result[0] == -1) {
            echo "Podane dane są nieprawidłowe i nie spełniają wymagań walidacji";
            $err = getError($c, $session);
                foreach($err as $error){
					echo PHP_EOL.$error;
				}
        } else {
            echo "Produkt został dodany, id: " . $result[0];
        }
    }
} else {
    echo "Wystąpił błąd logowania";
}

curl_close($c);
?>