Документация по API Youseller

Взаимодействие торговых площадок с API YouSeller происходит по протоколу SOAP который работает поверх протокола HTTP. Все сообщения должны иметь кодировку UTF-8.

Обработка ошибок

При SOAP-запросах к API YouSeller могут возникать различные ошибки и исключительные ситуации. При этом клиенту возвращается SOAP-сообщение c элементом env:Fault, которое содержит код ошибки и краткое сообщение:

        
        try {
            ... // Некоторый код
        } catch(SoapFault $e) {
            echo $e->getCode();    // Вывод кода ошибки
            echo $e->getMessage(); // Вывод сообщения об ошибке
        }
        
        

Ниже перечислены коды ошибок возвращаемые API YouSeller:

  • 900 - не найдены SOAP-заголовки содержащие идентификатор торговой площадки и секретный ключ для доступа к API;

  • 901 - торговая площадка отключена;

  • 902 - торговая площадка не прошла процедуру подтверждения доменного имени;

  • 903 - торговая площадка заблокирована администрацией YouSeller;

  • 904 - торговая площадка не найдена. В случае возникновения данной исключительной ситуации продавцу следует убедиться что в настройках скрипта верно указан идентификатор торговой площадки;

  • 905 - указан неверный секретный ключ для доступа к API.

Данные ошибки являются "внутренними" и вывод их посетителю не желателен. Рекомендуется вывести сообщение о недоступности торговой площадки в данный момент времени.

  • 400 - некорректный SOAP-запрос. Появление данной ошибки означает что клиентом был отправлен синтаксически некорректный SOAP-запрос;

  • 404 - объект не найден. Интерпритация данной ошибки зависит от контекста в котором происходил запрос. Например, если клиент запрашивал информацию о товаре и товар не был найден в системе YouSeller:

                    
                    $goodsId = (int) $_GET['goodsId'];
                    try {
                        $goods = $soapClient->getGoodsInfo($goodsId); // Запращивается информация о товаре 
                    } catch(SoapFault $e) {
                        if ($e->getCode() == 404) die('Товар не найден');
                        else throw $e; // Передача исключения на обработку в верхний уровень
                    }
                    
                    
  • 500 - внутренняя ошибка системы YouSeller;

  • 503 - сервис API YouSeller не доступен.

Заголовки SOAP

API YouSeller принимает следующие SOAP-заголовки:

  • shopId - идентификатор торговой площадки. Данный заголовок является обязательным;

  • secret - секретный ключ для доступа к API. Данный заголовок является обязательным;

  • lang - двухсимвольный идентификатор языка в формате ISO 639-1.

Для заголовков можно указывать произвольное пространство имен

Методы экспортируемые API YouSeller

Получить список доступных методов можно подключив WSDL-файл расположенный по адресу http://www.youseller.ru/soap/wsdl:

        
        $shopId     = 505050;                // Идентификатор торговой площадки
        $headerNs   = 'http://youseller.ru'; // Простарнство имен заголовков (можно указать любое)
        $secret     = 'blablablablablabla';  // Ключ для доступа к API

        $wsdl       = 'http://www.youseller.ru/soap/wsdl';
        $soapClient = new SoapClient($wsdl, array('trace' => 1, 'exceptions' => 1));

        // Заголовки для аутентификации
        $headers[] = new SoapHeader($headerNs, 'shopId', $shopId, false);
        $headers[] = new SoapHeader($headerNs, 'secret', $secret, false);

        // Заголовок указывающий язык клиента
        $headers[] = new SoapHeader($headerNs, 'lang',   'ru',    false);
        $soapClient->__setSoapHeaders($headers);

        // Получение списка категорий товаров
        try {
            $goodsCategories = $soapClient->getGoodsCategories();
        } catch(SoapFault $e) {
            echo $e->getCode().': '.$e->getMessage();
            ... // Обработка исключительной ситуации
        }
        
        
  • Метод array getShopInfo()

    Назначение: получение информации о торговой площадкe.

    Входные параметры: нет.

    Возвращаемое значение: массив с ключами.

    • title - наименование торговой площадки в виде строки;
    • goodsCount - количество размещенных товаров в виде целого числа;
    • shopLink - URL на информацию о магазине в системе Youseller;
    • sellerLink - URL для пользователей желающих разместить свои товары на данной площадке.

    Пример использования:

                    
                    $shopInfo = $soapClient->getShopInfo();
                    echo $shopInfo['title'];
                    echo $shopInfo["goodsCount"];
                    
                    
  • Метод array getGoodsCategories()

    Назначение: получение информации о категориях товаров.

    Входные параметры: нет.

    Возвращаемое значение: многомерный ассоциативвный массив.

  • Метод getCurrencies()

    Назначение: получение валют доступных в системе.

    Входные параметры: нет.

    Возвращаемое значение: ассоциативный массив вида "код валюты" => "строка" (например, 840 => USD).

  • Метод array getGoodsList(array params, array pagination, array sort, bool returnCount)

    Назначение: получение списка товаров размещенных на торговой площадкe.

    Входные параметры: три ассоциативных массива и булевская переменная.

    Массив "params" (не обязательный):

    • categoryId - идентификатор категории товара; Не обязательный;
    • currencyId - идентификатор валюты (согласно стандарту ISO 4217) в которой тербуется получить цены товаров. Не обязательный, по умолчанию система вернет цены товаров в рублях. Для того чтобы узнать валюты доступные в системе нужно воспользоваться методом getCurrencies;
    • userId - идентификатор продавца (владельца товара). Не обязательный;
    • searchString - строка для поиска в виде ключевых слов разделенных пробелами. Не обязательный. Должна содержать только символы алфавита, цифры, знак дефиса и пробелы;
    • minPrice - минимальная цена товара; Не обязательный;
    • maxPrice - максимальная цена товара; Не обязательный;
    • minBrokerFee - минимальный процент агентского вознаграждения; Не обязательный;
    • withDescription - флаг указывающий что для каждого товара требуется вернуть описание; Не обязательный;
    • withPicture - флаг указывающий что для каждого товара требуется вернуть ссылку на его изображение; Не обязательный;

    Массив "pagination" (не обязательный):

    • page - номер страницы;
    • pageSize - размер страницы (количество товаров отображаемых на странице);

    Массив "sort" (не обязательный): представляет собой список полей (см. возвращаемое значение) по которым должна проводится сортировка результата в виде "field" => asc | desc (asc - по возрастанию, desc - по убыванию).

    Параметр "returnCount" (не обязательный) указывает что нужно вернуть только количество найденных товаров. Бывает полезно, например при постраничном выводе.

    Пример использования:

    
                    $goodsList = $soapClient->getGoodsList(array(
                        'searchString' => 'антивирус касперского годовая лицензия',
                        'maxPrice'     => 100,
                        'currencyId'   => 840), // 840 - код USD
                        array('page' => 3, 'pageSize' => 10),
                        array('rate' => 'desc', 'price' => 'asc'));// Сортировка рейтингу товара и цене
                    

    Возвращаемое значение: массив с полями

    • id - идентификатор товара;
    • title - наименование товара;
    • category_id - идентификатор категории товара (deprecated);
    • categories - список категорий которым принадлежит товар;
    • price - цена товара в запращиваемой валюте;
    • broker_fee - процент агентского вознаграждения;
    • quantity - количество товара в наличии;
    • sold - количество проданного товара;
    • user_id - идентифкатор продавца;
    • user_alias - псевдоним продавца;
    • user_rate - рейтинг продавца товара;
    • good_comments - количество положительных отзывов о товаре;
    • bad_comments - количество отрицательных отзывов о товаре;
    • placed - дата размещения на площадке;
    • picture - ссылка на изображение товара;
  • Метод getGoodsInfo(int goodsId)

    Назначение: возвращает полную информацию о товаре.

    Входные параметры: "goodsId" - идентификатор товара;

    Возвращаемое значение: массив с полями

    • id - идентификатор товара;
    • title - наименование товара;
    • description - описание товара;
    • category_id - идентификатор категории товара (deprecated);
    • categories - список категорий которым принадлежит товар;
    • prices - ассоциативный массив с ценами товара в доступных валютах;
    • broker_fee - процент агентского вознаграждения;
    • quantity - количество товара в наличии;
    • sold - количество проданного товара;
    • user_id - идентифкатор продавца;
    • user_alias - псевдоним продавца;
    • user_rate - рейтинг продавца товара;
    • good_comments - количество положительных отзывов о товаре;
    • bad_comments - количество отрицательных отзывов о товаре;
    • sold - количество проданного товара;
    • buying_url - адрес для перехода на покупку товара;
    • picture - ссылка на изображение товара;

    Если товар не будет найден в системе API вернет исключительную ситуацию с кодом 404.

  • Метод getGoodsComments(array params, array pagination, bool returnCount)

    Назначение: получение отзывов о товаре.

    Входные параметры:

    • params - ассоциативный массив с ключами: goodsId - идентификатор товара, commentsType - категория отзывов, одно из двух значений: good (положительные) и bad (отрицательные);
    • pagination - аналогично рассмотренному в методе getGoodsList;
    • returnCount - аналогично рассмотренному в методе getGoodsList.
  • Метод getUserInfo(int userId)

    Назначение: получение информации о пользователе (продавце).

    Входные параметры: userId - идентификатор продавца

    Возвращаемое значение: ассоциативный массив с полями

    • id - идентификатор пользователя;
    • name - имя пользователя;
    • surname - фамилия пользователя;
    • alias - псевдоним;
    • email - адрес электронной почты;
    • rate - рейтинг пользователя;
    • register_date - дата регистрации;
    • last_visit - дата последнего входа в систему.
  • Если пользователь не будет найден в системе API Youseller вернет исключительную ситуацию с кодом 404.

  • Метод getUserComments(array params, array pagination, bool returnCount)

    Назначение: получение отзывов о пользователе (продавце).

    Входные параметры:

    • params - ассоциативный массив с ключами: userId - идентификатор пользователя (продавца), commentsType - категория отзывов, одно из двух значений: good (положительные) и bad (отрицательные);
    • pagination - аналогично рассмотренному в методе getGoodsList;
    • returnCount - аналогично рассмотренному в методе getGoodsList.

Ссылка для скачивания php-класса для работы с Youseller API: скачать

Для работы класса требуется PHP не ниже 5-й версии с установленныым расширением soap.