|
API-сервис – это удобный инструмент для встраивания нашего функцонала в ваш сайт. На этой стрнице вы узнаете, как общаться с нашим сервером, чтобы самостоятельно проверять и добавлять номера телефонов.
Никаких SOAP и сертифткатов! Наш сервер принимает обычные HTTP-запросы. А ответы даёт в человеческих форматах json (по умолчанию) и xml (по желанию).
Все данные в запросе должны быть в кодировке UTF-8, а сами запросы должны идти по одному адресу: http://etoagent.ru/api/
А теперь немного технической документации по двум способам общения с нашим сервером:
Подразумевается, что доступная ниже информация написана для человека, знаюшего, как работают POST-запросы.
Если вы испытываете трудности, обращайтесь к нам за помощью по почте, не стесняйтесь.
Чтобы послать запрос нашему серверу по АПИ, необходимо подать ему одну из трёх команд: getCityIdByName, addPhone или checkPhone. Название команды передаётся параметром "method".
А чтобы указать, в каком формате вам удобнее получать данные от сервера, надо указать параметр "answer_format" и его значение: "json" и "xml". Этот параметр необязателен, и сервер по умолчанию отдаёт данные в формате json.
Остальные параметры должны передаваться в зависимости от конкретного метода:
getCityIdByName
Возвращает массив информации по названию города. Она понадобится до добавления телефонов. Параметры:
- name (обязат.) – название города
Сервер возвратит массив городов, названия которых совпадают с переданным параметром name.
У каждого города будет указан его регион, страна, телефонный код и конечно же id, который понадобится для работы с другими методами АПИ.
Например, при запросе по адресу http://etoagent.ru/api/
?method=getCityIdByName&answer_format=xml&name=Москва
сервер выдаст ответ (xml-вариант):
<?xml version="1.0" encoding="utf-8" ?>
<cityList>
<city id="4400" name="Москва" phone_code="499" country="Россия" region="Москва и Московская обл."/>
</cityList>
addPhone
Позволяет добавить новый телефон в базу данных. Параметры:
- api_key (обязат.) – ключ-пароль, по которому мы разрешаем вам доступ к нашей базе. Получить его можно, попросив нас об этом по почте.
- city_id (обязат.) – id города, его можно узнать методом getCityIdByName
- phone (обязат.) – телефон без кода города (5-7 цифр)
- phone_code (обязат.) – телефонный код города (2-5 цифр), его можно узнать методом getCityIdByName. Если не указать этот параметр, то в будущем система будет производить поиск по этому номеру с учётом кода города по умолчанию.
- comment (необязат.) – комментарий. Всё, что угодно, от названия агентства до имени агента и его характеристик
Сервер возвратит статус выполнения команды в выбранном формате. Это будет либо "error" с описанием ошибки, либо "thank_you".
checkPhone
Проверяет, является ли номер агентским. Параметры:
- phone_code (обязат.) – телефонный код (2-5 цифр)
- phone (обязат.) – цифры номера для проверки (5-7 цифр)
Пареметр phone можно передавать как число, а можно как и массив. Во втором случае сервер проверит все указанные в массиве номера.
Например, при запросе по адресу http://etoagent.ru/api/
?method=checkPhone&phone_code=495&phone[]=1234567&phone[]=4567890
сервер выдаст ответ (xml-вариант):
<?xml version="1.0" encoding="utf-8" ?>
<phoneList>
<item status="found" phone_code="495" phone="1234567" city="Москва" comment="ООО МосГазАренда" added_at="24.06.2010 11:59:16"/>
<item status="not found" phone_code="495" phone="4567890"/>
</phoneList>
JSONP используется для запросов прямо со страниц вашего сайта к нашему серверу, преодолевая ограничение ajax'а обращения только к родительскому серверу. Подробности ищутся в интернете по слову jsonp
GET-запросы используются только для проверки номеров. Среди параметров достаточно указать название вашей js-функции ("обёртки") в параметре "callback", телефонный код и массив номеров для проверки.
Например, при вставке в код страницы такого куска
<script type="text/javascript" src="http://etoagent.ru/api/?callback=setEtoAgentLables&phone_code=495&phone=1256454"></script>
сервер выдаст ответ:
setEtoAgentLables([{"phone_code":"499", "phone":"123456", "status":"found", "city":"Москва", "comment":"ООО МосГазАренда", "added_at":"24.06.2010 11:59:16"}]);
Таким образом, выполнится указанная вами функция setEtoAgentLables(), в которую наш сервер встроит ответные данные.
В параметрах вместо номера телефона можно передать массив номеров (&phone[]=1256454&phone[]=2974562), тогда сервер обработает эти данные вместе, выдав ответный массив. Телефонный код будет учитываться один на все указанные номера.
А ещё мы просим вас использовать особый формат вывода результатов. Если номер был найден в базе агентов, надо будет написать рядом с номером текст "Это агент!" или разместить одну из наших картинок:
 или 
В случае, если телефон не найден, подойдёт вопросительный текст "Это агент?" или другие наши картинки:
 или 
Если вам не нравятся наши картинки – это не проблема, используйте что угодно, только ставьте в зависимости от результатов АПИ-запросов знаки "!" и "?" и делайте слова "Это агент" ссылкой типа http://etoagent.ru/495/123456/. Например, по ссылке
<a href="http://etoagent.ru/495/123456/">Это агент?</a>
в новом окне откроется наш сайт, где автоматически произойдёт проверка телефона с кодом 495 и номером 123456.
|
