Регистрация | Вход
API поисковой системы eFind.ru




Контактная информация
Телефон:
+7 (812) 309-50-30
Электронная почта:
client@efind.ru

Текущая версия 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 — запрос списка складов

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

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

Параметр Возможные значения Описание
r ID региона Запрос только складов, расположенных в заданном регионе.

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

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

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

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

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

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

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

Параметр Возможные значения Описание
r ID региона Запрос только складов, расположенных в заданном регионе.
id ID склада или список ID складов, разделенный запятыми Запрос только к заданному складу или складам.
stock 0|1 1 — запрос только позиций с наличием на складе. 0 — запрос любых позиций, применяется по умолчанию.
hp 0|1 1 — запрос только позиций с наличием цены. 0 — запрос любых позиций, применяется по умолчанию.
cur asis|rur|usd|eur|uah Конвертация цен. asis — без конвертации, rur — вывод цен в рублях, usd — вывод цен в долларах США, eur — вывод цен в евро, uah — вывод цен в украинских гривнах. Конвертация производится по текущему курсу ЦБ РФ.
tm десятичное число Управление продолжительностью запроса: параметр указывает предельное время ожидания ответа от складов в секундах. Десятичная часть отделена точкой. По умолчанию tm=6.

Например, запрос к 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": <список структур данных о позициях>
    },
    ...
]

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

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

Ключ Тип данных Комментарий
title строка Название склада на русском языке.
title_en строка Название склада на английском языке.
contact_email строка Адрес электронной почты.
contact_phones список строк Список телефонов.
city строка Город склада.
country строка Страна склада.
region_id число ID региона склада.
site строка Адрес web-сайта.
min_order строка Дополнительные условия поставки (например, условие минимального заказа).

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

Ключ Тип данных Комментарий
title строка Название филиала склада на русском языке.
contact_email строка Адрес электронной почты филиала.
contact_phone список строк Список телефонов филиала.
region_id число ID региона филиала.
site строка Адрес web-сайта филиала.

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

Ключ Тип данных Комментарий
part строка Название компонента (партномер).
mfg строка Производитель.
sku строка или null Артикул позиции.
note строка Описание компонента.
cr список строк Список аналогов компонента.
stock строка Количество на складе.
instock true или false Флаг наличия на складе.
pdf строка Ссылка на документацию.
img строка Ссылка на изображение.
url строка Ссылка на страницу компонената на сайте поставщика.
cur строка Идентификатор валюты.
price список списков Список цен на компонент. Каждый элемент списка является списком вида [a,b,c,d], где a — мин.количество в заказе, которому соответствует эта цена, b — цена в выбранной валюте, c — оригинальная цена в валюте компонента (указанной в поле cur компонента), d — значок валюты. Поле «a» также 3 специальных значения, отрицательные числа:
"-1" — оптовая цена
"-2" — мелкооптовая цена
"-3" — розничная цена
dc строка Дата изготовления.
moq строка Минимальный заказ.
pkg строка Тип корпуса.
pack строка Тип упаковки.
mpq строка Размер упаковки.
dlv строка Информация о сроках поставки на склад.

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

[
    {
        "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": null,
                "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": null,
                "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.

2002—2018 «ЭтЛайт»
Наши контакты: +7 (812) 309-50-30, client@efind.ru
Реклама · Участие в поиске · Инструменты · Блог · Аналитика · English version

  RADEL ExpoElectronica