Как известно начать изучать что либо труднее всего, eBay API даже при том что у него нормальная документация не исключение. Я сам только недавно начал его изучать и пришлось плотно полазить по доке и сторонним ресурсам прежде чем в голове начала складываться нужная картина.
Этот пост предназначен для тех, кому нужно быстро начать работать с eBay API ну и для меня самого, что бы в будущем ничего не забыть.
В принципе у eBay есть так называемый "Quick Start Guide", так что пройдемся сперва по нему:
1. Регистрация нового девелопера — все запросы к API сопровождаются передачей некоторых уникальных параметров девелопера. Как их получить читайте во втором пункте;
2. После успешной регистрации и авторизации на developer.ebay.com можно приступить к генерации «Application Keys», которые понадобятся для выполнения запросов к API. Для этого переходим в раздел "My Account" и в блоке «Application Keys» генерируем 2-а набора ключей:
2.1 Sandbox Keys — ключи для запросов к тестовой API;
2.2 Production Keys — ключи для запросов к рабочей API.
3. В этом пункте дается ссылка на "Sample Application", с помощью которого можно потестировать запросы к одному из видов API (да как оказалось их много :)) под названием «Finding API» (подробнее об основных видах API я напишу ниже). На странице этого «Sample Application» расположены 3-и блока:
3.1 Sample Application Source Code — содержит HTML/JS код, в самом низу которого подключается JS либа, урлом на которую и служит URL «Finding API» с уже подставленными необходимыми параметрами;
3.2 Parsed Sample Result — содержит результат выполнения запроса в виде HTML страницы;
3.3 Call Response — содержит результат выполнения запроса в виде XML.
4. Ссылки на разделы девелоперов сгруппированных по языкам программирования.
1. Finding API — предназначено для получения списка товаров eBay. Это API предоставляет возможность поиска товаров по следующим критериям:
1.1 findItemsByCategory — поиск товаров по категориям;
1.2 findItemsByKeywords — поиск товаров по ключевым словам;
1.3 findItemsAdvanced — позволяет создавать смешанный поиск по категориям и ключевым словам;
1.4 findItemsByProduct — поиск товаров по идентификаторам продуктов. Продуктами могут быть например: телефоны, видео игры, книги и т.д.
2. Shopping API — в основном предназначено для получения детальной информации о товаре. Для получения любой информации о товаре нужно знать его ID, который можно получить из списка найденных товаров в ответе на запрос к Finding API. Это API позволяет выполнить следующие запросы:
2.1 GetSingleItem — возвращает всю публичную информацию об одном товаре по его ID;
2.2 GetItemStatus — возвращает информацию о текущих ставках товара, одновременно можно запрашивать информацию о 10 товарах;
2.3 GetShippingCosts — позволяет рассчитать стоимость доставки товара покупателю. Для расчета нужно передать ID товара, код страны, в которую будет произведена доставка, почтовый индекс покупателя и количество единиц товара, которые будут/были куплены. Перед выполнением этого запроса сперва нужно убедится что у товара проставлена цена доставки;
2.4 GetMultipleItems — то же самое что и GetSingleItem но можно запрашивать информацию о нескольких товарах сразу (максимум 20 товаров).
Рассмотрим работу с этой api на основе простейшего примера. Я выбрал для себя формат общения с api посредством XML, запросы к api я отправляю методом POST. Но для начала приведу список обязательных параметров:
1. X-EBAY-SOA-OPERATION-NAME — значением этого параметра должно быть название действия, которое Вы собираетесь совершить. Например: findItemsByKeywords, findItemsByCategory;
2. X-EBAY-SOA-SECURITY-APPNAME — в этот параметр нужно подставить Ваш AppID, который можно найти/сгенерировать в разделе "My Account".
Оба эти параметра, при использовании метода POST, нужно передавать в заголовке запроса. Более подробно о общих параметрах для Finding API можно почитать на странице Making an API Call.
Теперь рассмотрим пример поиска товаров при помощи действия «findItemsByKeywords».
Где:
1. Http_Client — мой небольшой класс для отправки запросов к api при помощи cURL. Он есть в архиве кода;
2. URL запроса полностью будет выглядеть так: svcs.sandbox.ebay.com/services/search/FindingService/v1, но так как в доке пишут что «v1» (версия api) может меняться, то я вынес его в константу;
3. Метод setHeaders() устанавливает заголовки запроса. В константе APP_ID хранится мой AppID;
4. Метод setBody() устанавливает тело запроса. Как не сложно догадаться в теге keywords передаем ключевые слова. Параметр entriesPerPage говорит api, что нам нужно вернуть 10 товаров (подробнее о параметрах действия findItemsByKeywords можно прочесть тут);
5. Ну и метод send() отправляет запрос к api и возвращает ее ответ, который в виде XML будет помещен в переменную $result.
Дополню свое небольшое приложение возможностью просмотра расширенной информации о товаре с помощью запросов к действию GetSingleItem Shopping API. Сперва перечислю необходимые параметры:
1. X-EBAY-API-CALL-NAME — параметр задает имя действия в пределах Shopping API. Например: GetSingleItem, GetItemStatus;
2. X-EBAY-API-APP-ID — параметр передает Ваш AppID;
3. X-EBAY-API-REQUEST-ENCODING — формат запроса к api. Для метода POST нужно указать «XML»;
4. X-EBAY-API-VERSION — версия api, которую поддерживает ваше приложение. Для тестов я указывал 699.
Все параметры, при использовании метода POST, нужно передавать в заголовке запроса. Более подробно о общих параметрах для Shopping API можно почитать на странице Making an API Call.
Вот мой небольшой код, который запрашивает развернутую информацию по товару:
Здесь как и в предыдущем примере я задаю URL, для тестовой области Shopping API он будет «open.api.sandbox.ebay.com/shopping». Затем формирую массив заголовков и тело запроса. В теле запроса я указал идентификатор товара в теге ItemID (кстати не советую приводить его к типу int, т.к. размер ID товаров на eBay давно перевалил за его размер) и в качестве дополнительных данных я запросил TextDescription (текстовое описание товара, подробнее об всех параметрах действия GetSingleItem можно прочесть тут).
Надеюсь что этот пост позволит кому-нибудь сократить время на ознакомление с API eBay.
Архив моего тестового приложения
Страница со списком URL для всех API
Этот пост предназначен для тех, кому нужно быстро начать работать с eBay API ну и для меня самого, что бы в будущем ничего не забыть.
Quick Start Guide
В принципе у eBay есть так называемый "Quick Start Guide", так что пройдемся сперва по нему:
1. Регистрация нового девелопера — все запросы к API сопровождаются передачей некоторых уникальных параметров девелопера. Как их получить читайте во втором пункте;
2. После успешной регистрации и авторизации на developer.ebay.com можно приступить к генерации «Application Keys», которые понадобятся для выполнения запросов к API. Для этого переходим в раздел "My Account" и в блоке «Application Keys» генерируем 2-а набора ключей:
2.1 Sandbox Keys — ключи для запросов к тестовой API;
2.2 Production Keys — ключи для запросов к рабочей API.
3. В этом пункте дается ссылка на "Sample Application", с помощью которого можно потестировать запросы к одному из видов API (да как оказалось их много :)) под названием «Finding API» (подробнее об основных видах API я напишу ниже). На странице этого «Sample Application» расположены 3-и блока:
3.1 Sample Application Source Code — содержит HTML/JS код, в самом низу которого подключается JS либа, урлом на которую и служит URL «Finding API» с уже подставленными необходимыми параметрами;
3.2 Parsed Sample Result — содержит результат выполнения запроса в виде HTML страницы;
3.3 Call Response — содержит результат выполнения запроса в виде XML.
4. Ссылки на разделы девелоперов сгруппированных по языкам программирования.
API для работы с товарами
1. Finding API — предназначено для получения списка товаров eBay. Это API предоставляет возможность поиска товаров по следующим критериям:
1.1 findItemsByCategory — поиск товаров по категориям;
1.2 findItemsByKeywords — поиск товаров по ключевым словам;
1.3 findItemsAdvanced — позволяет создавать смешанный поиск по категориям и ключевым словам;
1.4 findItemsByProduct — поиск товаров по идентификаторам продуктов. Продуктами могут быть например: телефоны, видео игры, книги и т.д.
2. Shopping API — в основном предназначено для получения детальной информации о товаре. Для получения любой информации о товаре нужно знать его ID, который можно получить из списка найденных товаров в ответе на запрос к Finding API. Это API позволяет выполнить следующие запросы:
2.1 GetSingleItem — возвращает всю публичную информацию об одном товаре по его ID;
2.2 GetItemStatus — возвращает информацию о текущих ставках товара, одновременно можно запрашивать информацию о 10 товарах;
2.3 GetShippingCosts — позволяет рассчитать стоимость доставки товара покупателю. Для расчета нужно передать ID товара, код страны, в которую будет произведена доставка, почтовый индекс покупателя и количество единиц товара, которые будут/были куплены. Перед выполнением этого запроса сперва нужно убедится что у товара проставлена цена доставки;
2.4 GetMultipleItems — то же самое что и GetSingleItem но можно запрашивать информацию о нескольких товарах сразу (максимум 20 товаров).
Finding API
Рассмотрим работу с этой api на основе простейшего примера. Я выбрал для себя формат общения с api посредством XML, запросы к api я отправляю методом POST. Но для начала приведу список обязательных параметров:
1. X-EBAY-SOA-OPERATION-NAME — значением этого параметра должно быть название действия, которое Вы собираетесь совершить. Например: findItemsByKeywords, findItemsByCategory;
2. X-EBAY-SOA-SECURITY-APPNAME — в этот параметр нужно подставить Ваш AppID, который можно найти/сгенерировать в разделе "My Account".
Оба эти параметра, при использовании метода POST, нужно передавать в заголовке запроса. Более подробно о общих параметрах для Finding API можно почитать на странице Making an API Call.
Теперь рассмотрим пример поиска товаров при помощи действия «findItemsByKeywords».
// Get entity of http client
$httpClient = new Http_Client('http://svcs.sandbox.ebay.com/services/search/FindingService/' . FINDING_API_VERSION);
// Prepare headers
$httpClient->setHeaders(
array(
'X-EBAY-SOA-OPERATION-NAME: findItemsByKeywords',
'X-EBAY-SOA-SECURITY-APPNAME: ' . APP_ID
)
);
// Prepare body
$httpClient->setBody(
'<?xml version="1.0" encoding="utf-8"?>
<findItemsByKeywordsRequest xmlns="http://www.ebay.com/marketplace/search/v1/services">
<keywords>' . htmlspecialchars($keywords) . '</keywords>
<paginationInput>
<entriesPerPage>10</entriesPerPage>
</paginationInput>
</findItemsByKeywordsRequest>'
);
// Send request
$result = $httpClient->send();
Где:
1. Http_Client — мой небольшой класс для отправки запросов к api при помощи cURL. Он есть в архиве кода;
2. URL запроса полностью будет выглядеть так: svcs.sandbox.ebay.com/services/search/FindingService/v1, но так как в доке пишут что «v1» (версия api) может меняться, то я вынес его в константу;
3. Метод setHeaders() устанавливает заголовки запроса. В константе APP_ID хранится мой AppID;
4. Метод setBody() устанавливает тело запроса. Как не сложно догадаться в теге keywords передаем ключевые слова. Параметр entriesPerPage говорит api, что нам нужно вернуть 10 товаров (подробнее о параметрах действия findItemsByKeywords можно прочесть тут);
5. Ну и метод send() отправляет запрос к api и возвращает ее ответ, который в виде XML будет помещен в переменную $result.
Shopping API
Дополню свое небольшое приложение возможностью просмотра расширенной информации о товаре с помощью запросов к действию GetSingleItem Shopping API. Сперва перечислю необходимые параметры:
1. X-EBAY-API-CALL-NAME — параметр задает имя действия в пределах Shopping API. Например: GetSingleItem, GetItemStatus;
2. X-EBAY-API-APP-ID — параметр передает Ваш AppID;
3. X-EBAY-API-REQUEST-ENCODING — формат запроса к api. Для метода POST нужно указать «XML»;
4. X-EBAY-API-VERSION — версия api, которую поддерживает ваше приложение. Для тестов я указывал 699.
Все параметры, при использовании метода POST, нужно передавать в заголовке запроса. Более подробно о общих параметрах для Shopping API можно почитать на странице Making an API Call.
Вот мой небольшой код, который запрашивает развернутую информацию по товару:
// Get entity of http client
$httpClient = new Http_Client('http://open.api.sandbox.ebay.com/shopping');
// Prepare headers
$httpClient->setHeaders(
array(
'X-EBAY-API-CALL-NAME: GetSingleItem',
'X-EBAY-API-APP-ID: ' . APP_ID,
'X-EBAY-API-REQUEST-ENCODING: ' . SHOPPING_API_DATA_FORMAT,
'X-EBAY-API-VERSION: ' . SHOPPING_API_VERSION
)
);
// Prepare body
$httpClient->setBody(
'<?xml version="1.0" encoding="utf-8"?>
<GetSingleItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
<ItemID>' . $id . '</ItemID>
<IncludeSelector>TextDescription</IncludeSelector>
</GetSingleItemRequest>'
);
// Send request
$result = $httpClient->send();
Здесь как и в предыдущем примере я задаю URL, для тестовой области Shopping API он будет «open.api.sandbox.ebay.com/shopping». Затем формирую массив заголовков и тело запроса. В теле запроса я указал идентификатор товара в теге ItemID (кстати не советую приводить его к типу int, т.к. размер ID товаров на eBay давно перевалил за его размер) и в качестве дополнительных данных я запросил TextDescription (текстовое описание товара, подробнее об всех параметрах действия GetSingleItem можно прочесть тут).
Итого
Надеюсь что этот пост позволит кому-нибудь сократить время на ознакомление с API eBay.
Архив моего тестового приложения
Страница со списком URL для всех API