API УкрЯмы
Соответствует текущей версии 2.3
УкрЯмы.
Общение с сервером УкрЯмы любое внешнее приложение осуществляет посредством запроса к серверу по протоколу http
, а лучше — https
на определённый адрес. Сервер в ответ присылает XML
.
Запросы могут быть посланы как методом GET
, так и методом POST
, в зависимости от запроса. В случае, если приложение отправляет запрос методом GET
, то может передать какие-нибудь данные в строке URL
, а также в строке URL
содержится тип запроса. Проще говоря, в зависимости от того, что приложение хочет получить и сообщить, оно формирует запрос на определённый URL
. Запросы методом POST
используются для отправки на сервер больших объёмов информации (загрузка картинок и так далее), а также могут быть использованы для выполнения запросов, которые требуют авторизации. Все запросы, для которых авторизация не требуется, отправляются на сервер методом GET
.
Промышленный сервер, который принимает запросы: ukryama.com/xml/.
Тестовый сервер, на котором можно отлаживать приложения: test.ukryama.com/xml/.
Текущая версия API
на промышленном сервере описана по адресу http://ukryama.dev/page/api/.
Начиная работу имейте ввиду, что любые манипуляции с данными кроме открытой информации происходит после авторизации и возвращении passwordhash, который Вы будете использовать для дальнешей работы с сервером.
Формат XML ответа сервера
Валидный ответ сервера выглядит следующим образом:
<?xml version="1.0" encoding="UTF-8"?> <st1234reply> <requesttime> тут время запроса (таймстамп) </requesttime> <requestmethod> тут метод запроса (обычно GET или POST) </requestmethod> <replytime> тут время ответа сервера (таймстамп) </replytime> Тело ответа. </st1234reply>
Сервер принимает запросы и выдаёт ответы в кодировке UTF-8
. Использование иной кодировки в запросе не запрещается, но и не гарантирует адекватные ответы.
Формат XML ошибок
В случае каких-либо проблем или ошибок, которые сервер может обработать, он отвечает XML
с описанием ошибки. XML
ошибки содержит внутри ответа элемент <error/>
, у которого есть свойство code, а в себе он содержит текст ошибки. Например:
<?xml version="1.0" encoding="UTF-8"?> <st1234reply> <requesttime>1307535706</requesttime> <requestmethod>GET</requestmethod> <replytime>1307535707</replytime> <error code="NOT_IMPLEMENTED">Метод не реализован</error> </st1234reply>
Ниже представлен перечень кодов ошибок, которые сервер может возвращать:
NOT_IMPLEMENTED | Метод не реализован |
NOT_FOUND | Запрашиваемый ресурс не найден |
NO_FILES | Не загружено ни одного файла |
TOO_BIG_FILE | Слишком большой файл |
TOO_MANY_FILES | Слишком много файлов |
PARTIALLY_UPLOADED_FILE | Файл загружен только частично |
CANNOT_UPLOAD_FILE | Невозможно загрузить файл |
UNKNOWN_MIME_TYPE | Неподдерживаемый тип файла |
UNKNOWN_IMAGE_FORMAT | Неподдерживаемый формат изображения |
INCORRECT_TYPE | Неправильный тип дефекта |
DEPRECATED_TYPE | Неиспользуемый в данный момент тип дефекта |
CANNOT_ADD_DEFECT | Невозможно добавить дефект |
AUTHORIZATION_REQUIRED | Требуется авторизация |
LATITUDE_NOT_SET | Не указана широта дефекта |
LONGITUDE_NOT_SET | Не указана долгота дефекта |
NO_ADDRESS | Не указан адрес |
WRONG_CREDENTIALS | Неправильный логин и/или пароль |
UNAPPROPRIATE_METHOD | Неподходящий метод |
CANNOT_UPDATE_DEFECT | Не удалось обновить дефект |
CANNOT_DELETE_DEFECT | Не удалось удалить дефект |
GEOCODE_ERROR | Не удалось произвести геокодирование |
GEOCODE_EMPTY_REQUEST | Пустой запрос к геокодеру |
INTERNAL | Иная внутренняя ошибка |
Формат предупреждений
Помимо ошибок, сервер может возвращать предупреждения. Тэг предупреждения имеет следующий формат:
<warning code="WARNING">Это предупреждение</warning>
Предупреждений может быть несколько, и они могут соседствовать с прочими элементами в ответе сервера. Предупреждения могут быть возвращены в ответах не на все запросы, а только на некоторые, и все возможные случаи описаны отдельно. Обрабатывать предупреждения или нет — дело разработчика приложения.
Возможные предупреждения, который может возвращать сервер:
FILES_DROPPED | Несколько файлов не загружено на сервер |
CANNOT_REALISE_CITY | Не удалось распознать город |
FILES_LIMIT_REACHED | Достигнуто максимальное количество файлов для одного дефекта |
Формат XML описания дефекта
В разных запросах могут приходить описания разных дефектов. В списке дефектов их несколько, в карточке дефекта — он, соответственно, один. Во всех случаях XML
с описанием дефекта выглядит одинаково.
<hole id="номер дефекта"> <id> номер дефекта </id> <archive> находится ли яма в архиве (boolean) </archive> <username full="полоное имя пользователя" user_id="ID пользователя"> <name>имя</name> <secondname>отчество</secondname> <lastname>фамилия</lastname> </username> <latitude> широта </latitude> <longitude> долгота </longitude> <address city="название города" gt;полный адрес дефекта</address> <state code="код статуса дефекта"> название статуса</state> <type code="код типа дефекта"> название типа</type> <datecreated readable="02.06.2011">1307003591</datecreated> - дата создания дефекта <datesent readable="02.06.2011">1307003789</datesent> - дата отправки заявления в ГАИ <datestatus readable="02.06.2011">1307003797</datestatus> - дата простановки текущего статуса <commentfresh>комментарий пользователя к дефекту</commentfresh> <commentfixed>комментарий, который пользователь оставляет при отметке дефекта, как починенного</commentfixed> <commentgibddre>комментарий, который пользователь оставляет при простановке статуса «пришёл ответ из ГАИ»</commentgibddre> <pictures> <original> - картинки оригинального размера (ну на самом деле не оригинального, я ужатого до 1024 пикселей по ширине для экономии места на сервере) <fresh> - картинки к «свежему» дефекту, загружаемые на сайт при добавлении дефекта. Этот элемент (равно как и соседние с ним <gibddreply> и <fixed>) может иметь внутри любое (в том числе и нулевое) количество элементов <src>, в которых содержатся пути к картинкам дефектов относительно корня http-сервера (обычного, где крутится сайт) <src id="123">src</src> - путь к каринке и ее ID <src id="124">src</src> ... </fresh> <gibddreply>...</gibddreply> <fixed>...</fixed> </original> <medium> - картинки среднего размера, которые показываются на сайте внутри карточки дефекта <fresh>...</fresh> <gibddreply>...</gibddreply> <fixed>...</fixed> </medium> <small> - картинки маленького размера <fresh>...</fresh> <gibddreply>...</gibddreply> <fixed>...</fixed> </small> </pictures> <gibddrequests> - запросы в ГАИ
<request id="6" gibdd_id="75" date="1326669064" user_id="2" user_name="Иванов Иван"> - ID запроса, ID ГАИ, время отправки и имя пользователя
<answer id="2" date="1326729513"> - Ответ из ГАИ и его время
<files>
<file id="7" type="image">src</file> - Один из загруженых файлов, допустимые типы "image", "application/pdf" и "text/plain"
...
</files>
</answer>
</request>
</gibddrequests> </hole>
Список дефектов
Список дефектов получается простым запросом к корню http-сервера методом GET
. Могут быть переданы параметры, влияющие на фильтрацию, возможно, упорядочивание и отображение списка дефектов. Например:
GET /?filter_type=holeonroad&filter_status=fixed
Приведённый запрос отфильтрует выведет дефекты, типа «яма на дороге» и в статусе «починенные». Просто запрос GET /
выведет все ямы. Список дефектов можно получать без авторизации.
Возможные параметры, которые могут быть переданы в запросе:
filter_city |
Фильтр по названию города (или по его началу). Если указать, например, «Волг», то будут выбраны ямы, расположенные в Волгограде, Волгодонске и во прочих всех городах, название которых начинается на «Волг». Соответствует имени поля ADR_CITY .Если соответствующий фильтр задан, но равен пустой строке, то будут выбраны дефекты, не привязанные к городам (неправильный формат строки адреса или по иной причине). |
filter_status |
Фильтр по статусам дефектов. Может принимать значения:
Соответствует имени поля STATE .
|
filter_type |
Фильтр по типу дефектов. Спектр типов дефектов довольно обширен, часть типов не используется на сайте, хотя предусмотрены:
Соответствует имени поля TYPE .
|
limit | Количество возвращаемых дефектов. Если не указано, то берётся по умолчанию, 30 штук. На всякий случай максимальный лимит ограничен 2000 дефектами, чтоб злоумышленники не принялись выбирать дефекты десятками тысяч, положив БД и забив канал. |
offset | Если надо выбрать некоторое количество дефектов не с первого, то можно использовать offset — количество дефектов между первым по порядку и первым возвращённым в выборке. Если не указано, то считается равным 0. |
page |
Этот параметр обладает более высоким приоритетом по сравнению с limit и offset, если указать его, то limit и offset будут проигнорированы. Смысл его в том, что он переопределяет эти параметры следующим образом:limit = default_limit (30 дефектов), offset = page*default_limit.То есть нумерация страниц начинается с ноля. |
archive | Показывать ямы из архива. По умолчанию выдаются все ямы, не помещенные в архив. При включенном параметре - выдаются ямы только из архива. |
polygons | Вывести ямы по определенной территории. В качестве параметра передается двумерный массив Например: polygons[0][0][lat]=55.70576801798&polygons[0][0][lng]=37.35893083736и т.д. |
Формат возвращаемого в ответе XML
.
Основная информация содержится в элементе <defectslist>
в теле ответа. Там перечислены элементы <hole>
- дефекты, полученные в этой выборке. Формат каждого элемента <hole>
описан выше. Тело ответа, помимо присутствующих всегда элементов, содержит некоторые дополнительные:
<st1234reply> ... <sort> - тут описана сортировка выбоки. В каждом элементе <item>, которых может быть любое количество, но обычно только один, указано направление сортировки, а в свойстве code — имя поля, по которому идёт сортировка. <item code="ID">desc</item> ... </sort> <filter> - тут описана фильтрация. При применении фильтров (см. таблицу выше) здесь содержатся элементы <item>, значение которых — значение фильтра, а свойство code — имя поля, по которому производится фильтрация, которое не совпадает с названием фильтра (опять же см. таблицу выше). <item code="ADR_CITY">Москва</item> ... </filter> <navigation> - параметры выборки из БД, limit и offset. <item code="limit">30</item> <item code="offset">0</item> </navigation> <defectslist> <hole ...>...</hole> <hole ...>...</hole> <hole ...>...</hole> … </defectslist>
Карточка дефекта
Карточка дефекта является общедоступной информацией, для просмотра не требуется авторизация. Чтоб получить XML
с карточкой дефекта, надо отправить запрос методом GET
на адрес вида /<id дефекта>
, например: GET /123
— получить дефект с номером 123 (GET /123/
- тоже, слэш на конце не влияет на номер).
Если такой дефект существует, то он будет возвращён в XML
в теле ответа в описанном выше формате. В том случае, если он существует, но не прошёл премодерацию, будет возвращена ошибка NOT_FOUND
.
Авторизация
Авторизация осуществляется отправкой методом GET
полей login
и password
по адресу /xml/authorize
:
POST /xml/authorize/ Поля POST: { login: <логин пользователя> password: <пароль пользователя> }
В случае, если логин и/или пароль неправильные, возвращается ошибка с кодом WRONG_CREDENTIALS
. Если авторизация прошла успешно, будет возвращён набор данных порльзователя — его ID, ФИО и, самое главное, авторизационный хэш, который привязан к пользователю и который потом надо будет передавать серверу для подтверждения авторизованности пользователя при совершении действий, эту авторизованность требующих.
Пример ответа об успешной авторизации:
<?xml version="1.0" encoding="UTF-8"?> <st1234reply> <requesttime>1308213745</requesttime> <requestmethod>POST</requestmethod> <replytime>1308213746</replytime> <user id="1"> <username full="1 3 2"> <name>1</name> <secondname>2</secondname> <lastname>3</lastname> </username> <passwordhash>&6thg^dsflo8<f6ewt3h4f384bdrtg5g3efev43</passwordhash> </user> </st1234reply>
Авторизация через OpenID/OAuth
в данный момент не реализована.
Yii
, на котором работает весь сайт УкрЯма. Также, необходимо помнить о том, что символы <
и >
, которые могут попасться в хэше, заменены HTML-последовательностями <
и >
соответственно. Сессия хранится долго, то есть не слетает через некоторое время бездействия, однако, нельзя гарантировать то, что она будет храниться вечно. Если приложение не хранит у себя пароль пользователя, а хранит только возвращаемый при авторизации хэш, то, для заблаговременного сообщения пользователю о том, что его сессия истекла и ему необходимо ввести пароль снова, можно воспользоваться запросом CheckAuth
. Он ничего не делает, только проверяет, может ли пользователь авторизоваться по указанному логину и хэшу пароля. Ну и продлевает сессию, наверное, тоже.
Запрос CheckAuth
Осуществляется отправкой запроса методом GET
или POST
по адресу /checkauth/
:
POST /xml/checkauth/ Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> }
Ответ сервера стандарный, в теле ответа присутствует всего один элемент <checkauthresult>
, который содержит строку либо ok
, либо fail
, и имеет свойство result
, равное 1
или 0
соответственно.
Запрос exit
На всякий случай, мало ли, вдруг понадобится, сделана и возможность разлогинится. Запрос exit
посылается методом POST
или GET
по адресу exit
:
POST /xml/exit/ GET /xml/exit/
Никаких параметров более передавать не нужно. Тело ответа всегда будет сообщать об успешном завершении процедуры. Выглядит это так:
<?xml version="1.0" encoding="UTF-8"?> <st1234reply> <requesttime>1308220587</requesttime> <requestmethod>GET</requestmethod> <replytime>1308220588</replytime> <callresult result="1">ok</callresult> </st1234reply>
Профиль пользователя
Подробную информацию о пользователе можно получить запросом POST
по адресу: /xml/profile/<ID пользователя>/
.
В случае, если логин и/или пароль неправильные, возвращается ошибка с кодом WRONG_CREDENTIALS
. Если авторизация прошла успешно, будет возвращён набор данных порльзователя — его ID, ФИО и, если пользователь разрешил публикацию своей зоны наблюдения, координаты точек многоугольников пользовательской зоны.
Пример ответа:
<?xml version="1.0" encoding="UTF-8"?> <st1234reply> <requesttime>1308213745</requesttime> <requestmethod>POST</requestmethod> <replytime>1308213746</replytime> <user id="1"> <username full="1 3 2"> <name>1</name> <secondname>2</secondname> <lastname>3</lastname> </username> <passwordhash>&6thg^dsflo8<f6ewt3h4f384bdrtg5g3efev43</passwordhash> <area>
<polygon>
<point>
<lat>
55.70576801798
</lat>
<lng>
37.35893083736
</lng>
</point>
<point>
<lat>
55.86373205569
</lat>
<lng>
37.35893083736
</lng>
</point>
<point>
<lat>
55.86373205569
</lat>
<lng>
37.66767103225
</lng>
</point>
....
</polygon> ....
</area> </user> </st1234reply>
Список дефектов, выложенных на сайт пользователем
Список дефектов, которые выложил на сайт определённый пользователь получается запросом методом POST
по адресу /xml/my/
:
POST /xml/my/ Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля, полученный при авторизации> }
Вместо поля passwordhash может быть передан собственно пароль в поле password (тогда поле passwordhash
должно отсутствовать вообще, а не быть нулевой длины). В том случае, если логин и хэш пароля (пароль) принадлежат одному пользователю, то в ответе содержится список дефектов, выложенных на сайт этим пользователем, в том числе и те, которые ещё не прошли премодерацию. В противном случае ответ будет содержать ошибку AUTHORIZATION_REQUIRED
.
К списку собственных дефектов может быть применён фильтр, аналогичный фильтру обычного списка дефектов, и выглядит он точно так же.
Просмотр карточки дефекта с правами пользователя
Авторизованный пользователь может смотреть информацию по каждому из загруженных им дефектов, даже по тем, которые ещё не прошли премодерацию. Для этого надо отправить запрос методом POST
по адресу /xml/my/xxx/
, где xxx
— номер дефекта, который пользователь хочет посмотреть. Например:
POST /xml/my/154/ Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля, полученный при авторизации> }
Вместо поля passwordhash
может быть передан собственно пароль в поле password
(тогда поле passwordhash
должно отсутствовать вообще, а не быть нулевой длины). В том случае, если логин и хэш пароля (пароль) принадлежат пользователю, загрузившему на сайт указанный дефект (в примере — дефект №154), то будет возвращено описание запрошенного дефекта. Если логин и хэш пароля (пароль) не принадлежат одному пользователю, будет возвращена ошибка AUTHORIZATION_REQUIRED
, а если дефект принадлежит другому пользователю, то будет возвращена ошибка NOT_FOUND
.
Работа с дефектами
Добавление дефекта
Добавление дефекта осуществляется отправкой необходимых данных методом POST
по адресу /add/
.
POST /xml/add/ Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> address: <адрес ямы, желательно в формате xAL> latitude: <широта дефекта> longitude: <долгота дефекта> comment: <комментарий пользователя к дефекту> type: <тип дефекта> }
Кроме того, должен быть передан хотя бы один графический файл с фотографией ямы.
Комментарии к передаваемым полям POST
:
passwordhash | Содержит хэш пароля. Вместо этого поля можно передать пароль в поле password , но тогда поле passwordhash должно отсутствовать (а не быть равным пустой строке). |
login | Логин пользователя. В том случае, если логин и пароль (хэш пароля) не соответствуют одному пользователю, будет возвращена ошибка AUTHORIZATION_REQUIRED . |
address |
Адрес должен быть в формате xAL , или, по крайней мере, начинаться как адрес в этом формате. Определение текстового поля «название города» происходит именно на основании данных адреса. Поэтому хорошей практикой может считаться определение адреса по координатам с помощью обратного геокодирования, и позволение пользователю дописать что-то в конец адреса, или слегка отредактировать первую часть адреса, но тогда не исключена такая ситуация, что дефект, территориально расположенный в городе N, будет не находиться в этом городе при поиске по названию города N. Адрес является обязательным параметром, при его отсутствии будет возвращена ошибка NO_ADDRESS .А если не удалось опередить город, то генеририуется предупреждение CANNOT_REALISE_CITY .
|
latitude, longitude | Широта и долгота месторасположения дефекта. Их можно не передавать по отдельности, а передать сразу в поле coordinates перечисленными через запятую, сначала широта, потом долгота. Либо передать их в поле coordinatesr через запятую, но сначала долгота, а потом широта. Координаты должны быть переданы, это обязательные параметры. В том случае, если они не будут переданы, будут возвращены ошибки LATITUDE_NOT_SET или LONGITUDE_NOT_SET . |
comment | Текстовый комментарий к дефекту, может быть пустым. |
type | Тип дефекта, один из возможных. При указании несуществующего типа будет возвращена ошибка INCORRECT_TYPE , при указании существующего, но неиспользуемого типа дефектов будет возвращена ошибка DEPRECATED_TYPE . |
Комментарии к файлам
Файлы должны быть переданы именно как файлы (encryption type
должно быть multipart/form-data
). Имена, под которыми файлы передаются на сервер, не имеют значения, но их должно быть не больше десяти. Обрабатываться они будут в том порядке, в котором будут переданы на сервер. В том случае, если файлов будет больше, чем десять, те файлы, которые были переданы после десятого, не будут обработаны, и будет выдано предупреждение FILES_DROPPED
.
В том случае, если суммарный размер файлов превышает допустимые ограничения, никакой специфической ошибки не возвращается, так как веб-сервер обычно обрабатывает эту ситуацию самостоятельно. Вероятнее всего в этом случае можно получить ошибку AUTHORIZATION_REQUIRED
. Узнать максимальный размер одного файла и максимальный суммарный размер файлов можно с помощью запроса GetFileUploadLimits
.
В случае, если при загрузке файлов произошли какие-то другие ошибки, то они будут выведены в XML
.
Ошибки, которые могут возникнуть при загрузке файлов:
NO_FILES | Ни одного файла не загружено |
UPLOAD_ERROR | Слишком большой файл |
UPLOAD_ERROR | Слишком много файлов (количество превышает директиву max_file_uploads в php.ini ) — но эту ошибку вряд ли можно наблюдать, если честно |
UPLOAD_ERROR | Файл загружен только частично |
UPLOAD_ERROR |
Невозможно загрузить файл. Это сообщение выдаётся в случае, если загрузить файлы не удалось по какой-то внутренней причине, о которой пользователю знать не обязательно — проблемы с записью на диск, с правами доступа и так далее. |
UPLOAD_ERROR |
Неподдерживаемый формат файла. В качестве изображений принимаются картинки форматов JPEG , PNG и GIF , попытка загрузить файл любого другого формата вызовет эту ошибку. |
UPLOAD_ERROR |
Неизвестный формат изображения. Если mime-type и содержимое картинки не совпадают или что-то случилось на сервере, что не позволяет открыть этот файл для пережатия в меньший размер, то будет показана эта ошибка.
|
В том случае, если по какой-то причине не удалось добавить дефект, то будет возвращена ошибка CANNOT_ADD_DEFECT
, в которой будет описание, почему, собственно, не удалось добавить дефект, и элемент callresult
с результатом 0
(fail
). В том случае, если дефект добавить удалось, будет возвращён его идентификатор в элементе XML
-репорте об успешном завершении операции:
<callresult result="1" inserteddefectid="32">ok</callresult>
В свойстве inserteddefectid
элемента callresult
находится идентификатор добавленного дефекта.
Запрос GetFileUploadLimits
Запрос позволяет выяснить настройки PHP
на сервере и прочие ограничения, присутствующие при загрузке фалов на сервер. Отправляется методом GET
по адресу /getfileuploadlimits
:
GET /getfileuploadlimits
Запрос авторизации не требует и возвращает вот такой XML
:
<?xml version="1.0" encoding="UTF-8"?> <st1234reply> <requesttime>1308920653</requesttime> <requestmethod>GET</requestmethod> <replytime>1308920653</replytime> <maxpostsize>1M</maxpostsize> <maxfilesize>3M</maxfilesize> <maxfilescount>10</maxfilescount> </st1234reply>
Элементы <maxpostsize>
и <maxfilesize>
содержат значения значений post_max_size
и upload_max_filesize
из php.ini
в том виде, в каком они содержатся там; как видно в примере — даже без проверок на адекватность. Элемент maxfilescount
содержит максимальное число файлов, которое можно загрузить за один раз.
Изменение дефекта
Существует несколько запросов, позволяющих изменить дефект. Эти запросы различны по тем данным, которые могут быть изменены, и по тому, когда они могут быть вызваны, это зависит от статуса дефекта. По своей сути эти запросы сводятся к одному универсальному, но снаружи этого не видно.
Список запросов, которыми можно изменять дефект.
Запрос | Статус дефекта, когда может быть вызван запрос | Поля, которые можно изменять, и прочие допустимые изменения |
---|---|---|
update | новый | координаты, тип, строка адреса, комментарий, можно загружать ещё файлы и удалять имеющиеся |
set_inprogress | новый, исправлено | меняется статус на «в процессе». Для дефекта в статусе «исправлено» этот запрос доступен только в том случае, если не была загружена фотография исправленного дефекта, и статус может измениться на «просрочен» или «получен ответ из гибдд», в зависимости от того, какой был статус до статуса «исправлен» |
revoke | в процессе | меняется статус обратно на «новый» |
set_replied | в процессе, получен ответ, просрочен | меняется статус на «получен ответ из ГАИ», необходимо добавить одно или несколько изображений (обычно скан ответа из ГАИ) и, по желанию, комментарий. Можно удалить ранее загруженный ответ из ГАИ |
set_fixed | все, кроме «исправлено» | меняется статус на «исправлено», можно добавить одно или несколько изображений и комментарий |
to_prosecutor | просрочен | статус меняется на «жалоба в прокуратуру подана» |
revoke_p | жалоба в прокуратуру подана | статус меняется обратно на «просрочен» |
Дефект переходит из статуса «в процессе» в статус «просрочен» самостоятельно с течением времени.
Для удобства пользования существует служебный запрос GetUpdateMethods
, который сообщает список возможных способов изменить дефект, а также — какие поля принимаются при каждом запросе.
Вызов GetUpdateMethods
Вызов существует в двух вариантах — в общем случае и применительно к дефекту. В общем случае вызывается методом GET
адрес /getupdatemethods
:
GET /getupdatemethods
Применительно к одному дефекту он вызывается методом POST
по адресу /xml/my/<defect_id>/getupdatemethods
:
POST /xml/my/<defect_id>/getupdatemethods Поля POST { login: <логин пользователя> passwordhash: <хэш пароля> }
Как и в других случах, тут вместо хэша пароля можно передать собственно пароль в поле password
, а поле passwordhash
в таком случае должно отсутствовать. В том случае, если логин и пароль не подходят, будет выдана ошибка AUTHORIZATION_REQUIRED
. В том случае, если дефект с номером <defect_id>
отсутствует или загружен другим пользователем, будет выдана ошибка NOT_FOUND
.
В общем случае тело ответа сервера выглядит следующим образом:
<state id="state-id"> <method name="method-name"> <field>field_name</field> ... </method> ... </state> …
В теле ответа перечислены элементы state
(теоретически, их может и не быть), каждый из которых соответствует статусу дефекта. В случае, если вы запрашиваете этот метод для одного дефекта, то элемент state
будет максимум один — соответствующий статусу выбранного дефекта. У элемента state
есть свойство id
— это код статуса дефекта.
Внутри элемента state
расположены элементы method
, каждый из которых соответствует методу обновления дефекта, который может быть вызван для дефекта в текущем статусе. Соответственно, этих элементов тоже может не быть. У элемента method
есть свойство name
, которое является именем этого метода.
Внутри элемента method
расположены элементы field
(их тоже может не быть), каждый из которых соответствует свойству дефекта, который может быть изменён данным методом. И является ключом массива с данными, который передаётся методом POST
при обновлении дефекта. Более подробно о кодах field
см. в описании метода обновления update
.
Метод обновления дефекта update
Это наиболее полный метод обновления дефекта, с помощью которого данные дефекта можно обновить полностью (за исключением авторства и даты создания, разумеется). Поэтому данный метод применим только к дефектам в статусе «новый».
Вызывается данный метод отправкой данных методом POST
на адрес /xml/my/<defect-id>/update
:
POST /xml/my/<defect-id>/update Поля POST (практически идентичны с методом добавления дефекта): { login: <логин пользователя> passwordhash: <хэш пароля> address: <адрес ямы, желательно в формате xAL> latitude: <широта дефекта> longitude: <долгота дефекта> comment: <комментарий пользователя к дефекту> type: <тип дефекта> deletefiles: <удаляемые файлы> }
Кроме того, могут быть переданы графические файлы, который добавятся к дефекту.
Комментарии к передаваемым полям POST
:
passwordhash | Содержит хэш пароля. Вместо этого поля можно передать пароль в поле password , но тогда поле passwordhash должно отсутствовать (а не быть равным пустой строке). |
login | Логин пользователя. В том случае, если логин и пароль (хэш пароля) не соответствуют одному пользователю, будет возвращена ошибка AUTHORIZATION_REQUIRED . |
address |
Адрес должен быть в формате xAL , или, по крайней мере, начинаться как адрес в этом формате. Если адрес не передан, то адрес дефекта не изменится.
А если не удалось опередить город, то генерируется предупреждение CANNOT_REALISE_CITY . Желательно передавать адрес полный, полученный с помощью геокодера. Допускатся передавать адрес частичный, совпадающий с полем address дефекта, но в том случае, если он будет изменён, невозможно гарантировать то, что будет сохранён город и регион дефекта.
|
latitude, longitude |
Широта и долгота месторасположения дефекта. Их можно не передавать по отдельности, а передать сразу в поле coordinates перечисленными через запятую, сначала широта, потом долгота. Либо передать их в поле coordinatesr через запятую, но сначала долгота, а потом широта.Если координаты не переданы, то координаты дефекта не изменятся. |
comment | Текстовый комментарий к дефекту, может быть пустым. Если не передан, то не комментарий к дефекту не изменится. |
type | Тип дефекта, один из возможных. При указании несуществующего типа будет возвращена ошибка INCORRECT_TYPE , при указании существующего, но неиспользуемого типа дефектов будет возвращена ошибка DEPRECATED_TYPE . Если тип не передан, то тип дефекта не изменится. |
deletefiles | Массив ID изображений. |
Комментарии к загружаемым файлам аналогичны случаю создания дефекта. С помощью многократного редактирования дефекта можно загрузить достаточно большое количество файлов, но их суммарное количество не должно превышать 100, в противном случае будут выведены предупреждения FILES_DROPPED
и FILES_LIMIT_REACHED
(достигнуто максимальное количество файлов для дефекта).
В том случае, если данный метод неприменим для дефекта из-за того, что последний не в статусе «новый», будет выведена ошибка UNAPPROPRIATE_METHOD
(неподходящий метод).
Если обновление дефекта прошло успешно, то будет выведен элемент <callresult result="1">ok</callresult>
, в противном случае будет выведен элемент <callresult result="0">fail</callresult>
и ошибка CANNOT_UPDATE_DEFECT
(не удалось обновить дефект) в том случае, если произошёл какой-то сбой иного рода, элемент error
будет содержать текст ошибки, например:
<error code="CANNOT_UPDATE_DEFECT">Неподдерживаемый формат изображения</error>
Метод обновления дефекта set_inprogress
Метод предназначен, в основном, для перевода дефекта из статуса «новый» в статус «в процессе», однако, может применяться и для отмены статуса «исправлен» в том случае, если ещё не была загружена фотография исправленного дефекта. Вызывается отправкой запроса методом POST
на адрес /xml/my/<defect-id>/setinprogress
:
POST /xml/my/<defect-id>/setinpgogress Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> }
Вместо passwordhash
может быть передан password
.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD
. Результат выполнения выводится в элементе <callresult>
. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT
, элемент error
будет содержать текст ошибки.
Метод обновления дефекта revoke
Метод служит для возвращения дефекту, который в статусе «в процессе», статуса «новый». Соответственно, применим только для дефектов в статусе «в процессе». Вызывается отправкой запроса методом POST
по адресу /xml/my/<defect-id>/revoke
:
POST /xml/my/<defect-id>/revoke Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> }
Вместо passwordhash может быть передан password.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD
. Результат выполнения выводится в элементе <callresult>
. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT
, элемент error
будет содержать текст ошибки.
Метод обновления дефекта set_replied
Данный метод предназначен для перевода дефекта из статуса «в процессе» в статус «получен ответ из ГАИ» или для добавления ещё сканов ответа из ГАИ. Применим только к дефектам в статусе «в процессе». Вызывается отправкой запроса методом POST
по адресу /xml/my/<defect-id>/setreplied
:
POST /xml/my/<defect-id>/setreplied Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> comment: <комментарий> deletefiles: <список удаляемых файлов ответов ГАИ через запятую> }
Вместо passwordhash
может быть передан password
.
Должен быть передан как минимум один графический файл, являющийся, по замыслу, сканом ответа из ГАИ. Максимальное число файлов всё так же 10. Комментарий не обязателен.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD
. Результат выполнения выводится в элементе <callresult>
. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT
, элемент error
будет содержать текст ошибки. Если не загружено ни одного файла, будет выдана ошибка NO_FILES
. Также могут быть выданы ошибки, связанные с загрузкой файлов, аналогичные описанным в разделе о методе обновления update
.
Метод обновления дефекта set_fixed
Данный метод предназначен для перевода дефекта в статус «исправлено». Применим к дефекту в любом статусе, кроме «новый» и «исправлено». Вызывается отправкой запроса методом POST
по адресу /xml/my/<defect-id>/setfixed
:
POST /xml/my/<defect-id>/setfixed Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> comment: <комментарий> }
Вместо passwordhash
может быть передан password
.
Комментарий не обязателен. Также могут быть переданы графические файлы, но они тоже не обязательны, и к ним относятся все замечания, касающиеся загрузки файлов, для вышеописанных методов.
Следует отметить отдельно, что в том случае, если файл не был загружен, то дефект можно вернуть в статус «в процессе» (или «просрочен»), а если был загружен файл, то нельзя.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD
. Результат выполнения выводится в элементе <callresult>
. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT
, элемент error
будет содержать текст ошибки. Если не загружено ни одного файла, будет выдана ошибка NO_FILES
. Также могут быть выданы ошибки, связанные с загрузкой файлов, аналогичные описанным в разделе о методе обновления update
.
Метод обновления дефекта to_prosecutor
Метод служит для простановки дефекту статуса «заявление отправлено в прокуратуру». Метод применим только для просроченных дефектов (находящихся в статусе «просрочен»). Вызывается отправкой запроса методом POST
по адресу /xml/my/<defect-id>/toprosecutor
:
POST /xml/my/<defect-id>/toprosecutor Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> }
Вместо passwordhash
может быть передан password
.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD
. Результат выполнения выводится в элементе <callresult>
. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT
, элемент error
будет содержать текст ошибки.
Метод обновления дефекта revoke_p
Метод служит для простановки дефекту в статуске «заявление в прокуратуре» статуса «просрочен». Вызывается отправкой запроса методом POST
по адресу /xml/my/<defect-id>/revokep
:
POST /xml/my/<defect-id>/revokep Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> }
Вместо passwordhash
может быть передан password
.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD
. Результат выполнения выводится в элементе <callresult>
. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT
, элемент error
будет содержать текст ошибки.
Удаление дефекта
Удалить можно только дефект в статусе «новый». Для этого надо отправить запрос методом POST
по адресу /xml/my/<defect-id>/delete
:
POST /xml/my/<defect-id>/delete Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> }
Вместо passwordhash
может быть передан password
.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD
. Результат выполнения выводится в элементе <callresult>
. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_DELETE_DEFECT
, элемент error
будет содержать текст ошибки.
Геокодирование
Геокодирование получается обращением методом POST
по адресу /geocode/
:
POST /xml/geocode/ Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> geocode: <любая строка или координаты через запятую> }
Вместо passwordhash
может быть передан password
.
geocode
передаётся сначала долгота, потом широта.
Ответ сервера содержит в себе элемент <geocode>
, в котором целиком содержится (за исключением тэга <?xml>
) ответ Яндекса в формате XML
(пробелы, которыми сделан отступ строк слева, заменены на символы табуляции). В случае ошибки элемент <geocode>
отсутствует, а вместо него выводится ошибка. Если не указан адрес или координаты, то выводится ошибка GEOCODE_EMPTY_REQUEST
(пустой запрос к геокодеру), в случае каких-либо иных ошибок выводится GEOCODE_ERROR
.
Получение с сервера PDF
В некоторых ситуациях вместо ответа в формате XML
сервер может предложить для скачивания PDF
-файл со сформированным заявлением в прокуратуру или жалобой в ГАИ. Для получения с сервера PDF
необходимо отправить запрос методом POST
по определённому адресу и передать заполненные поля, которые подставятся в текст.
Формирование и получение с сервера жалобы в ГАИ
Для получения с сервера жалобы в ГАИ в формате PDF или текста необходимо отправить на сервер запрос методом POST
по адресу /xml/my/<defect-id>/pdf_gibdd/
:
POST /xml/my/<defect-id>/pdf_gibdd/ Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> to: <кому> from: <от кого> postaddress: <почтовый адрес отправителя> holeaddress: <адрес дефекта> signature: <подпись (фамилия и инициалы отправителя)> html: [Не обязательный boolean параметр. Если true ответ будет выдан ввиде строки размеченой html] textonly: [Не обязательный boolean параметр. Если true ответ будет выдан ввиде текстовой строки] }
Вместо passwordhash
может быть передан password
.
В поле from
должно быть указано полное имя отправителя.
Данный запрос применим только к дефектам, находящимся в статусах «новый» и «в процессе». В случае, если дефект находится не в этих статусах, будет выведена ошибка UNAPPROPRIATE_METHOD
. Скрипты на сайте не проверяют валидность вводимых данных. Сгенерированный текст заявления не хранится на сервере.
Формирование и получение с сервера заявления в прокуратуру
Для получения с сервера жалобы в ГАИ в формате PDF или текста необходимо отправить на сервер запрос методом POST по адресу /xml/my/<defect-id>/pdf_prosecutor/:
POST /xml/my/<defect-id>/pdf_prosecutor/ Поля POST: { login: <логин пользователя> passwordhash: <хэш пароля> from: <от кого> postaddress: <почтовый адрес отправителя> holeaddress: <адрес дефекта> signature: <подпись (фамилия и инициалы отправителя)> gibdd: <название отделения ГАИ> gibddre: <ответ ГАИ> html: [Не обязательный boolean параметр. Если true ответ будет выдан ввиде строки размеченой html] textonly: [Не обязательный boolean параметр. Если true ответ будет выдан ввиде текстовой строки] }
Вместо passwordhash
может быть передан password
.
В поле from
должно быть указано полное имя отправителя. Так как на сайте в профиле может быть не указано полное правильное имя пользователя, имеется возможность указать его отдельно. В поле postaddress
необходимо указать свой полный почтовый адрес. На сайте не хранятся почтовые адреса пользователей. Адрес дефекта нужно указать чётко, чтоб было понятно в прокуратуре. Поле gibdd
должно содержать название отделения ГАИ, куда было направлено заявление. Для его получения можно воспользоваться запросом getgibddhead
. Поле gibddre должно содержать содержательную часть ответа из ГАИ и используется только в том случае, если этот ответ получен. Отправить заявление в прокуратуру можно, когда дефект находится в двух статусах: «просрочен» и «получен ответ из ГАИ», в обоих случаях текст заявление будет разный, в первом случае — жалоба на бездействие ГАИ, во втором — заявление о нарушении закнодательства о содержании и ремонте дорог и безопасности дорожного движения. В том случае, если дефект находится в другом статусе, будет выведена ошибка UNAPPROPRIATE_METHOD
. Скрипты на сайте не проверяют валидность вводимых данных. Сгенерированный текст заявления не хранится на сервере.