ePN API для разработчиков

Если вы не нашли здесь ответ на свой вопрос, то обратитесь за помощью в саппорт ePN.

Описание API

Все запросы к API отправляются в виде POST-запроса по протоколу HTTP на URL-адрес http://api.epn.bz/json. Параметры запроса передаются в виде JSON-строки как данные RAW POST DATA. Ответ отдаётся так же в формате JSON.

Структура запроса имеет вид:

	{
		user_api_key = $your_api_key
		user_hash = $your_deep_link_hash
		api_version = $client_library_version
		requests = $requests_to_process
	}

Все параметры обязательны. Данные 'user_api_key' и 'user_hash' берутся в личном кабинете партнёрской программы (первый в профиле пользователя, а второй - в списке креативов), 'api_version' описывает версию клиентской библиотеки (текущее описание соответствует версии "2").

Структура $requests_to_process содержит список запросов, которые надо обработать в пакетном режиме и имеет вид:

	{
		$req_name_1 = $req_data_1
		$req_name_2 = $req_data_2
		// ... //
		$req_name_n = $req_data_n
	}

Таким образом, при отправке пакета для каждого запроса нужно указать уникальное имя блока, а в возвращаемом результате искать необходимые данные по этому имени. Каждое описание запроса имеет вид:

	{
		action = $action
		$param_1 = $value_1
		$param_2 = $value_2
		// ... //
		$param_n = $value_n
	}

Список доступных параметров зависит от значения 'action'. Параметры, которые не поддерживаются для данного действия 'action', будут просто проигнорированы.

Возможные значения 'action':

list_categories
offer_info
search
count_for_categories
list_currencies
top_monthly

Возвращаемый результат

Структура результата имеет вид:

	{
		identified_as = vasya
		error = some error
		results = {
			req_name_1 = {
				// data 1 //
			}
			req_name_2 = {
				// data 2 //
			}
			// ... //
			req_name_n = {
				// data n //
			}
		}
	}

Здесь:

identified_as: имя пользователя, чей ключ используется для доступа к API. Присутствует только в случае успешной авторизации.
error: сообщение об ошибке. Присутствует если не подошёл 'user_api_key' или 'user_hash'.
results: массив результатов. В случае проблем с авторизацией он будет пуст.

Таким образом после получения отклика надо убедиться, что в нём отсутствует поле 'error' и присутствует поле 'identified_as'. После этого можно приступать к разбору поля 'results'.

Поле 'results' является ассоциативным массивом. В качестве ключей используются имена запросов из 'requests', а в качестве значений - результат выполнения соответствующего запроса.

Рассмотрим подробнее параметры запросов и возможные ответы:

action = list_categories

Запрос 'list_categories' возвращает список категорий и их идентификаторов. Он имеет только один параметр: 'lang', с помощью которого можно передать двухбуквенный код языка.

В настоящий момент поддерживаются значения 'en' и 'ru'. Любое другое значение, равно как и отсутствие параметра расценивается как 'en'.

Результат выглядит примерно так:

	{
		categories = {
			{
				id = 2
				title = Food
			}
			
			{
				id = 6
				title = Home Appliances
			}
			
			{
				id = 1501
				title = Baby Products
			}
		}
	}

action = offer_info

Запрос "offer_info" позволяет получить информацию о товаре по идентификатору и коду языа. Единственный обязательный параметр - 'id'. Необязательные параметры - 'lang' и 'currency'. Если 'lang' не указан то считается что передано значение 'en'. Если не указан 'currency' то подразумевается 'USD'. Допустимо передавать несколько валют, перечисленных через запятую. Пример запроса:

	{
		action = offer_info
		lang = en
		id = 2164021
		currency = RUR,USD
	}

В случае если такой товар не существует или больше не продаётся, ответ будет иметь вид:

	{
		error = Offer not found
	}

В случае же успеха ответ будет такой:

	{
		offer = {
			id = 2164021
			id_category = 509
			name = Samsung Galaxy S3 Stand and Spare Battery Charger
			picture = http://i00.i.aliimg.com/wsphoto/v0/861977540/Samsung-Galaxy-S3-Stand-and-Spare-Battery-Charger.jpg
			price = 1135.58
			currency = RUR
			commission_rate = 915
			description = Best Samsung Galaxy S3 Charger
			url = http://epnredirect.ru/redirect/goods/d73d3c21b691d24c7f8265cb0d9a426d/2164021
			store_id = 123654
			store_title = MegaStorCompany LLC
			prices = {
				RUR = 915
				USD = 12.5
			}
		}
	}

action = search

Это действие самое сложное, имеет большое количество параметров и с его помощью можно реализовать большое количество функций.

Сводная таблица параметров

Параметр	Обязателен	Возможные значения	Значение по умолчанию
query	нет	произвольный поисковый запрос в виде текстовой строки.	пустая строка
orderby	нет	поле сортировки пустая строка (по релевантности) rand (в случайном порядке) price (по цене) commission_rate (по комиссии) added_at (по дате добавления) orders_count (по количеству заказов за последние 30 дней продаж)	пустая строка (по релевантности)
order_direction	нет	направление сортировки: desc (по убыванию) asc (по возрастанию)	desc
limit	нет	количество результатов в отклике.	10
offset	нет	сдвиг относительно начала.	0
category	нет	список идентификаторов категорий через запятую (например 2,6,1501) либо пустая строка.	пустая строка (отсутствие фильтра по категориям).
store	нет	список идентификаторов продавцов через запятую (например 2,6,1501) либо пустая строка.	пустая строка (отсутствие фильтра по продавцам).
price_min	нет	минимальная цена (в USD), которая необходима (включительно).	0.0
price_max	нет	максимальная цена (в USD), которая необходима (включительно).	1000000.0
lang	нет	язык описаний товаров. на момент написания документации возможны значения "ru" и "en".	en
currency	нет	Валюта, в которой будет передаваться информация о ценах. В настоящий момент возможны значения: RUR, USD, EUR, UAH, KZT, BYR. Допустимо перечислить несколько валют через запятую.	USD

В качестве результат всегда возвращаются поля 'offers' и 'total_found'. Поле 'total_found' содержит общее количество результатов (без учёта 'limit' и 'offset').

Поле 'offers' содержит массив элементов вида:

	{
		id = 2164021
		id_category = 509
		name = Samsung Galaxy S3 Stand and Spare Battery Charger
		picture = http://i00.i.aliimg.com/wsphoto/v0/861977540/Samsung-Galaxy-S3-Stand-and-Spare-Battery-Charger.jpg
		all_images = {
				http://i00.i.aliimg.com/wsphoto/v0/861977540/Samsung-Galaxy-S3-Stand-and-Spare-Battery-Charger.jpg
				http://i00.i.aliimg.com/wsphoto/v0/861977540/Samsung-Galaxy-S3-Stand-and-Spare-Battery-Charger-2.jpg
				http://i00.i.aliimg.com/wsphoto/v0/861977540/Samsung-Galaxy-S3-Stand-and-Spare-Battery-Charger-3.jpg
			}
		price = 18.39
		currency = USD
		commission_rate = 12.5
		description = Best Samsung Galaxy S3 Charger
		url = http://epnredirect.ru/redirect/goods/d73d3c21b691d24c7f8265cb0d9a426d/2164021
		store_id = 123654
		store_title = MegaStorCompany LLC
		prices = {
			USD = 12.5
			RUR = 912.3
		}
	}

Как уже было сказано выше, с помощью action=search можно реализовать большое количество различных функций. Рассмотрим примеры:

Пять случайных товаров:

	{
		orderby = rand
		limit = 5
	}

Просмотр товаров в категории:

	{
		orderby = added_at
		order_direction = desc
		category = 2
		limit = $items_per_page
		offset = ($page - 1) * $items_per_page
	}

Поиск товаров:

	{
		query = $query
		limit = $items_per_page
		offset = ($page - 1) * $items_per_page
	}

Пять самых дешёвых товаров:

	{
		orderby = price
		order_direction = asc
		limit = 5
	}

action = count_for_categories

Полезное в ряде случаев действие. Позволяет узнать количество товаров в категориях, соответствующее определённым критериям. Список параметров полностью аналогичен списку параметров действия "search" с одним исключением: параметры "category", "limit", "offset", "currency" - игнорируются.

В качестве ответа возвращается ассоциативный массив (хэш), в котором в качестве ключей указываются идентификаторы категорий, а в качестве значений - количество товаров.

Пример ответа:

	{
		200005271 = 207
		1524 = 21
		1509 = 25
		509 = 1
		3 = 10
	}

action = list_currencies

Позволяет получить список поддерживаемых валют и их описаний. Не содержит параметров. Пример ответа:

	{
		currencies = {
			USD = US Dollar
			EUR = Euro
			UAH = Ukrainian Hryvnia
			BYR = Belarussian Ruble
			KZT = Kazakh Tenge
			CNY = China Yuan
			RUR = Russian Ruble
		}
	}

action = top_monthly

Позволяет получить "топы" товров за прошедший месяц с сортировкой по комиссии (от максимальной и "вниз") или продажам.

Параметр	Обязателен	Возможные значения	Значение по умолчанию
orderby	нет	sales - сортировка по продажам. commission - сортировка по комиссии.	sales
category	нет	список идентификаторов категорий через запятую (например 2,6,1501) либо пустая строка.	пустая строка (отсутствие фильтра по категориям).
lang	нет	язык описаний товаров. на момент написания документации возможны значения "ru" и "en".	en
currency	нет	Валюта, в которой будет передаваться информация о ценах. В настоящий момент возможны значения: RUR, USD, EUR, UAH, KZT, BYR. Допустимо перечислять несколько значений через запятую.	USD

В качестве результат всегда возвращается поле 'offers', являющееся массивом из ста элементов вида:

	{
		id = 32269721105
		id_category = 44
		name = Mini Mirror Surface Clip Mp3 Sport With TF-Card Slot Suppot Up To 8GB New Free shippingFree Shipping
		price = 1.32
		currency = USD
		product_id = 32269721105
		description = Mini Mirror Surface Clip Mp3 Sport With TF-Card Slot
		lang = en
		picture = http://i01.i.aliimg.com/wsphoto/v0/32269721105_1/Mini-Mirror-Surface-Clip-Mp3-Sport-With-TF-Card-Slot-Suppot-Up-To-8GB-New-Free.jpg
		all_images = {
			http://i01.i.aliimg.com/wsphoto/v0/32269721105_1/Mini-Mirror-Surface-Clip-Mp3-Sport-With-TF-Card-Slot-Suppot-Up-To-8GB-New-Free.jpg
			http://i01.i.aliimg.com/wsphoto/v0/32269721105_2/Mini-Mirror-Surface-Clip-Mp3-Sport-With-TF-Card-Slot-Suppot-Up-To-8GB-New-Free.jpg
			http://i01.i.aliimg.com/wsphoto/v0/32269721105_3/Mini-Mirror-Surface-Clip-Mp3-Sport-With-TF-Card-Slot-Suppot-Up-To-8GB-New-Free.jpg
		}
		prices = {
			USD = 1.32
			RUR = 96.36
		}
		commission_rate = 3.75
	}

Использование в PHP. Класс clEPNAPIAccess

Для упрощения разработки проектов на PHP, использующих EPN API, предоставляется готовый класс clEPNAPIAccess, который предоставляет простой, но функциональный интерфейс для работы с ePN API.

Для начала необходимо создать экземпляр класс clEPNAPIAccess. В качестве параметров конструктору передаётся API Key и DeepLink Hash. Пример кода:

	$epn = new clEPNAPIAccess($your_api_key, $your_deep_link_hash);

Класс предоставляет следующие методы:

AddRequestCategoriesList($name, $lang = 'en') - добавление запроса на получение списка категорий.
AddRequestGetOfferInfo($name, $id, $lang = 'en', $currency = 'USD') - добавление запроса на получение информации о товаре.
AddRequestSearch($name, $options = array()) - добавление запроса на поиск.
AddRequestCountForSearch($name, $options = array()) - добавление запроса на получение количества товаров в категориях.
AddRequestCurrenciesList() - получение списка поддерживаемых валют.
AddRequestGetTopMonthly($name, $lang = 'en', $currency = 'USD', $orderby = 'sales', $category = '') - получение топовых товаров.
RunRequests() - выполнение запросов.
LastError() - сообщение об ошибке, возникшей при последнем выполнении RunRequests.
LastErrorType() - тип последней ошибки при выполнении RunRequests.
GetRequestResult($name) - получение результата выполнения запроса.

Методы clEPNAPIAccess. AddRequestCategoriesList:

Метод "AddRequestCategoriesList" имеет два параметра: уникальное имя запроса и код языка. Последний параметр не является обязательным. Пример использования:

	// Список категорий на английском языке
	$epn->AddRequestCategoriesList('categories_list_1');
	
	// Список категорий на русском языке
	$epn->AddRequestCategoriesList('categories_list_2', 'ru');

Методы clEPNAPIAccess. AddRequestGetOfferInfo:

Метод "AddRequestGetOfferInfo" предназначен для получения подробной информации о товаре. Принимает четыре параметра: уникальное имя запроса, идентификатор товара, код языка и наименование валюты (последний два - необязательные параметры). Пример использования:

	$epn->AddRequestGetOfferInfo('offer_info_en', 2164021);
	$epn->AddRequestGetOfferInfo('offer_info_ru', 2164021, 'ru', 'RUR');

Методы clEPNAPIAccess. AddRequestSearch:

Метод "AddRequestSearch" является самым сложным и функциональным. Принимает два параметра: уникальный идентификатор запроса и массив параметров поиска.

Массив поисковых опций описан выше (см. описание параметров action=search). Пример использования:

	// Запрос десяти случайных товаров в категориях 5, 6 и 7
	$epn->AddRequestSearch(
		'random_goods_1',
		array(
			'query' => '',
			'orderby => 'rand',
			'limit' => 10,
			'offset' => 0,
			'category' => '5,6,7'
		)
	);

Методы clEPNAPIAccess. AddRequestCountForSearch:

Список параметров полностью идентичен AddRequestSearch с небольшим отличием в списке опций (см описание action=count_for_categories). Пример использования:

	// Количество товаров в категориях, соответствующих запросу 'phone'
	$epn->AddRequestCountForSearch(
		'category_count_1',
		array(
			'query' => 'phone',
			'orderby => '',
		)
	);

Методы clEPNAPIAccess. AddRequestCurrenciesList:

Самый простой метод. Имеет только один параметр: уникальное имя запроса. Пример использования:

	// Получение списка валют
	$epn->AddRequestCurrenciesList('currency_list_1');

Методы clEPNAPIAccess. AddRequestGetTopMonthly:

	// Получение самых продаваемых товаров с описанием на русском языке и ценой в рублях
	$epn->AddRequestGetTopMonthly('top_sales_1', 'ru', 'RUR', 'sales');

Методы clEPNAPIAccess. RunRequests:

Метод "RunRequests" не содержит параметров, но именно он отправляет все запросы к серверу API и обрабатывает отклик. Метод возвращает TRUE в случае успешного ответа от API и FALSE если что-то пошло не так. Пример использования:

	if ($epn->RunRequests()) {
		print "Данные получены\n";
	}
	else {
		print "Произошла ошибка\n";
	}

Методы clEPNAPIAccess. LastError:

Метод "LastError" позволяет получить описание ошибки, возникшей при последнем вызове RunRequests. Если последний вызов RunRequests был завершён успешно то вместо сообщения об ошибке будет пустая строка. Пример использования:

	if (!$epn->RunRequests()) {
		print $epn->LastError() . "\n";
	}

Методы clEPNAPIAccess. LastErrorType

Метод "LastErrorType" позволяет получить тип последней ошибки, возникшей при последем вызове RunRequests. Пример вызова:

	$result_type = $epn->LastErrorType();
	if ($result_type == 'none') {
		print "Всё хорошо\n"
	}
	elseif ($result_type == 'network') {
		print "Сетевая проблема\n"
	}
	elseif ($result_type == 'data') {
		print "Не удалось разобрать ответ сервера\n"
	}
	else {
		print "Что-то непонятное. Такого быть не должно\n"
	}

Методы clEPNAPIAccess. GetRequestResult:

Метод "GetRequestResult" используется при разборе отклика от API. Метод принимает на вход уникальное имя запроса и возвращает ответ на запрос, либо FALSE если по какой-то причине этот запрос не был обработан. Пример использования:

	// получение списка категорий по имени блока 'categories_list_1'
	$categories = array();
	if ($categories_tmp = $epn->GetRequestResult('categories_list_1') && isset($categories_tmp['categories']) {
		$categories = $categories_tmp['categories'];
	}

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

	// Инициализируем переменные
	$categories = array();
	$offers = array();
	$total_offers = array();
	// Создаём объект
	$epn = new clEPNAPIAccess($api_key, $deep_link_hash);
	// Добавляем запрос на получение списка категорий
	$epn->AddRequestCategoriesList('categories_list_1');
	// Добавляем запрос на поиск первых двадцати товаров по запросу "phone"
	$epn->AddRequestSearch(
			'search_1',
			array(
				'query' => 'phone',
				'limit' => 20,
				'offset' => 0
			)
		);
	// Добавляем запрос на получение количества товаров, соответствующих запросу "phone" в категориях
	$epn->AddRequestCountForSearch(
			'search_count_1',
			array(
				'query' => 'phone',
			)
		);
	// Пытаемся выполнить запрос
	if ($epn->RunRequests()) {
		// Извлекаем список категорий
		if (($categories_tmp = $epn->GetRequestResult('categories_list_1')) && isset($categories_tmp['categories'])) {
			$categories = $categories_tmp['categories'];
		}
		// Извлекаем список товаров
		if (($offers_tmp = $epn->GetRequestResult('search_1')) && isset($offers_tmp['offers'])) {
			$offers = $offers_tmp['offers'];
			$total_offers = $offers_tmp['total_found'];
		}
		// Извлекаем количество товаров по категориям
		if (($search_count_hash_tmp = $epn->GetRequestResult('search_count_1')) && isset($search_count_hash_tmp['count'])) {
			$search_count_hash = $search_count_hash_tmp['count'];
		}
	}
	// Если что-то пошло не так
	else {
		print $epn->LastError() . "\n"
	}
	// Отображаем список категорий
	print_r($categories);
	// Отображаем найденные товары
	print_r($offers);
	// Отображем количество товаров по категориям
	print_r($search_count_hash);

Список изменений

2016.03.06:
- Добавлен метод LastErrorType.
2016.01.11:
- Дополнительные поля в ответе на offer_info;
- Возможность получать цену сразу в нескольких валютах (массив "prices"). Для совместимости со старыми инсталляциями оставлены поля "price" и "currency";
2015.10.26:
- Во всех методах прекращена поддержка параметров "rate_min" и "rate_max";
2015.08.04:
- Добавлено описание запроса top_monthly и связанных с ним методов;
2015.05.19:
- Дополнительные поля в описание товаров: "store_id" - идентификатор продавца и "store_title" - название продавца;
- Дополнительный фильтр для поиска: "store"
2015.04.21:
- Дополнительное поле в описание товаров: "commission_rate" - комиссия вебмастера (в процентах);
2015.03.22:
- Новый вариант сортировки: "orders_count" (количество заказов за последние 30 дней продаж);
- Дополнительное поле в описание товаров: "all_images" - массив, содержащий все (включая основную) фотографии товара;
2015.03.10:
- "пустые" запросы теперь не отсылаются на сервер;
2015.02.20:
- Добавлена возможность выбора валюты (параметр currency);
- Добавлено описание запроса list_currencies и связанных с ним методов;
- Исправлены замеченные ошибки;
2015.02.06:
- Добавлена возможность указания языка (параметр lang).