Текущая версия v.0.2 beta

Доступ к API поискового сервера

Для доступа к API необходимо обратиться по протоколу HTTPS к адресу

https://efind.ru/api/<метод>

где «метод» принимает одно из трех значений:

• listregions
• liststocks
• search

Ответом поискового сервера является JSON-структура, содержащая ответ сервера.

Подробнее о методах и параметрах их вызовов, а также форматах ответов от сервера вы можете узнать из соответствующих разделов документации.

В случае возникновения ошибки, ответом сервера будет являться следующая структура данных:

{"error": "<Текстовое описание ошибки>"}

Авторизация

Все вызовы к API требуют авторизации посредством передачи в вызове токен-параметра:

access_token — ваш токен к API

Токен выдается администрацией eFind.ru.

Таким образом, запрос к API должен выглядеть так:

https://efind.ru/api/listregions?access_token=<Ваш токен>

Лимиты запросов к API и ограничение доступа по IP

Для каждого токена API администрация eFind.ru может установить следующие лимиты по количеству запросов:

• Лимит по количеству запросов в минуту.
• Лимит по количеству запросов в час.
• Лимит по количеству запросов в сутки.

В случае срабатывания лимита по количеству запросов, в ответ сервер выдаст HTTP код ответа 509 и следующую ошибку:

{"error": "Request limit exceeded"}

Также для вас может быть установлено разрешение для доступа к API только с определенного IP-адреса. В случае запроса к API с другого IP-адреса сервер выдаст HTTP код ответа 403 и ошибку:

{"error": "IP <IP-адрес> is not allowed "}

Методы API

listregions — запрос списка регионов

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

[
    {
        "Name": "Россия",
        "Name_en": "Russia",
        "RegionID": 1,
        "RegionParent": 0
    },
...
]

где:

• Name — название региона на русском языке.
• Name_en — название региона на английском языке.
• RegionID — ID региона.
• RegionParent — ID родительского региона (0, если регион является корневым).

liststocks — запрос списка складов

В результате вызова данного метода сервер возвращает список складов.

Параметры запроса к данному методу:

В ответ на запрос сервер возвращает список структур данных с информацией о складах (см. табл. «структура данных о складе»). Также, если в запрашиваемом регионе находится один или несколько филиалов склада, то структура данных о складе будет содержать непустой список структур данных о филиалах (см. табл. «структура данных о филиале») в ключевом поле «filial»

search — запрос поисковой выдачи

Этот метод используется для запроса поисковой выдачи по заданному запросу.

Вызов метода имеет вид:

https://efind.ru/api/search/поисковый запрос

Поисковый запрос должен быть в формате urlencoded значения в кодировке utf-8

Параметры запроса к данному методу:

Например, запрос к API может выглядеть вот так:

https://efind.ru/api/search/max323?access_token=<Ваш токен>&r=165&stock=1&hp=1&cur=eur&tm=2

При таком запросе будет выдан результат поиска по запросу max323 в регионе «Санкт-Петербург». Выданы будут только позиции c наличием на складе и имеющие цены. Цены будут выведены в валюте Евро. Продолжительность поиска по складам будет ограничена 2-мя секундами.

А при таком запросе:

https://efind.ru/api/search/%D0%BA%D0%B0%D0%B1%D0%B5%D0%BB%D1%8C?access_token=<Ваш токен>&id=99,96,127

будет выдан результат поиска по слову «кабель» (%D0%BA%D0%B0%D0%B1%D0%B5%D0%BB%D1%8C в urlencoded формате от строки в utf-8) только по складам с ID 99, 96 и 127

В ответ на запрос сервер возвращает список ответов складов в следующем формате:

[
    {
        "stock_id": <Идентификатор склада>,
        "stockdata": <структура данных о складе>
        "filial": <Структура данных о филиале или null>
        "finish": <Время выдачи результата складом (сек.)>,
        "rows": <список структур данных о позициях>
    },
    ...
]

Структура данных

Структура данных, описывающая склад:

Если в регионе поиска присутствуют филиалы склада, то данные о них определяются следующей структурой:

Структура данных о позиции

Таким образом, итоговый ответ сервера поиска может выглядеть так:

[
    {
        "stock_id": 1234,
        "stockdata": {
            "city": "Москва",
            "contact_email": "sales@mystock.ru",
            "contact_phones": [
                "+7 (495) 111-22-33"
            ],
            "country": "Россия",
            "min_order": "",
            "region_id": "3",
            "site": " http://www.mystock.ru",
            "title": "Склад 1",
            "title_en": "Stock One"
        },
        "filial": {
            "contact_email": "info@mystockspb.ru",
            "contact_phone": [
                "+7 (812) 123-45-67"
            ],
            "filial_id": 1722,
            "region_id": 165,
            "site": "http://www.mystockspb.ru",
            "title": "Stock one, филиал в Санкт-Петербурге"
        },

        "rows": [
            {
                "cr": [],
                "cur": "usd",
                "dc": "",
                "dlv": "",
                "img": "",
                "instock": false,
                "mfg": "Maxim Integrated Products",
                "moq": "",
                "mpq": "",
                "note": "",
                "pack": "",
                "part": "MAX232CSE+",
                "pdf": "",
                "pkg": "",
                "price": [
                    [
                        "-2",
                        null,
                        null,
                        "€"
                    ],
                    [
                        "-1",
                        null,
                        null,
                        "€"
                    ],
                    [
                        -3,
                        "2.434",
                        2.9725,
                        "€"
                    ]
                ],
                "sku": "",
                "stock": "2-4 недели",
                "url": ""
            },
            {
                "cr": [],
                "cur": "usd",
                "dc": "",
                "dlv": "",
                "img": "",
                "instock": false,
                "mfg": "Maxim Integrated Products",
                "moq": "",
                "mpq": "",
                "note": "",
                "pack": "",
                "part": "MAX232CSE+",
                "pdf": "",
                "pkg": "",
                "price": [
                    [
                        "-2",
                        null,
                        null,
                        "€"
                    ],
                    [
                        "-1",
                        null,
                        null,
                        "€"
                    ],
                    [
                        -3,
                        "1.902",
                        2.3229,
                        "€"
                    ]
                ],
                "sku": "",
                "stock": "2-4 недели",
                "url": ""
            }

        ],
        "finish": 0.0218,
    }
]

Привязка к Паспорту eFind.ru

Настройку параметров запроса к методу search можно производить через интерфейс настроек поиска. Для этого надо сообщить нам свой логин в Паспорте eFind.ru, и мы привяжем его к используемому вами токену. После этого настройки, сделанные данным пользователем в интерфейсе настроек, будут применяться к запросам по методу search, сделанные к API.

Обращаем внимание, что настройки, заданные через параметры URL запроса, имеют приоритет над настройками, заданными через интерфейс настроек поиска. Например, если в URL задан параметр "cur=rur", а в интерфейсе задан вывод цен в евро, то в ответе на запрос к API цены будут в рублях.

Пример кода

Пример написан на языке php, с использованием модуля curl.

$token = "<Ваш токен>"; # Токен выдается каждому партнеру индивидуально

$method = "listregions"; # "liststocks" , "search"
$searchtext = ""; # При методе search $searchtext = "/<Поисковый фрагмент>";
                  # В данном примере слэш обязателен для разделения частей url

$link = "https://efind.ru/api/$method$searchtext?access_token=$token";

$curl=curl_init(); #Сохраняем дескриптор сеанса cURL

#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'eFind-API-client/1.0');
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'GET');
curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
curl_setopt($curl,CURLOPT_HEADER,false);

$out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную

$code=(int)curl_getinfo($curl,CURLINFO_HTTP_CODE); #Получим HTTP-код ответа сервера

curl_close($curl); #Завершаем сеанс cURL

if ($code == 200) {
    $data = json_decode($out, TRUE); # Приводим отклик сервера к ассоциативному массиву
    if (isset($data['error'])){
        # Запрос отработал с ошибкой.
        $errormessage = $data['error'];

    } else {

        /*
        *       ... проводим обработку полученной информации
        */
    }
} else {
    /*
    * Ответ www-сервера отличается от 200 Ок: 
    * неправильный URL, сервер недоступен или сетевые проблемы
    */
}

По указанной ниже ссылке расположена демонстрационная форма, на которой можно генерировать API-запросы и анализировать ответ API.

Демонстрационная форма API.