Соответствует текущей версии 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 version="1.0" encoding="UTF-8"?>
<st1234reply>
	<requesttime> тут время запроса (таймстамп) </requesttime>
	<requestmethod> тут метод запроса (обычно GET или POST) </requestmethod>
	<replytime> тут время ответа сервера (таймстамп) </replytime>
	
	Тело ответа.
	
</st1234reply>

Сервер принимает запросы и выдаёт ответы в кодировке UTF-8. Использование иной кодировки в запросе не запрещается, но и не гарантирует адекватные ответы.

В случае каких-либо проблем или ошибок, которые сервер может обработать, он отвечает 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 с описанием дефекта выглядит одинаково.

<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 Фильтр по статусам дефектов. Может принимать значения:
  • fresh — свежий дефект, только добавлен на сайт;
  • inprogress — в процессе, заявление в ГАИ;
  • fixed — отремонтирован;
  • achtung — просрочен (прошло более 37 дней с момента подачи заявления в ГАИ, никакого результата не видно);
  • prosecutor — отправлена жалоба в прокуратуру на бездействие органов ГАИ;
  • gibddre — получен ответ из ГАИ, но дефект не отремонтирован.
Если передать несуществующий статус, то дефекты выбраны не будут.
Соответствует имени поля STATE.
filter_type Фильтр по типу дефектов. Спектр типов дефектов довольно обширен, часть типов не используется на сайте, хотя предусмотрены:
  • badroad — разбитая дорога;
  • holeonroad — яма на дороге;
  • holeinyard — яма во дворе;
  • hatch — люк;
  • crossing — переезд (не используется);
  • nomarking — отсутствие разметки (не используется);
  • rails — рельсы;
  • policeman — лежачий полицейский (не используется);
  • fence — ограждение (не используется);
  • holeinyard — яма во дворе;
  • light — неисправный светофор (не используется);
  • snow — снег.
Если передать несуществуюший тип, то дефекты выбраны не будут.
Соответствует имени поля TYPE.
limit Количество возвращаемых дефектов. Если не указано, то берётся по умолчанию, 30 штук. На всякий случай максимальный лимит ограничен 2000 дефектами, чтоб злоумышленники не принялись выбирать дефекты десятками тысяч, положив БД и забив канал.
offset Если надо выбрать некоторое количество дефектов не с первого, то можно использовать offset — количество дефектов между первым по порядку и первым возвращённым в выборке. Если не указано, то считается равным 0.
page Этот параметр обладает более высоким приоритетом по сравнению с limit и offset, если указать его, то limit и offset будут проигнорированы. Смысл его в том, что он переопределяет эти параметры следующим образом:
limit = default_limit (30 дефектов),
offset = page*default_limit.
То есть нумерация страниц начинается с ноля.
archive Показывать ямы из архива. По умолчанию выдаются все ямы, не помещенные в архив. При включенном параметре - выдаются ямы только из архива.
polygons

Вывести ямы по определенной территории. В качестве параметра передается двумерный массив polygons[i][j], где i № многоугольника а j № точки. Сами координаты точек нужно передавать тутже в ['lat'] и ['lng'].

Например:

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-последовательностями &lt; и &gt; соответственно. Сессия хранится долго, то есть не слетает через некоторое время бездействия, однако, нельзя гарантировать то, что она будет храниться вечно. Если приложение не хранит у себя пароль пользователя, а хранит только возвращаемый при авторизации хэш, то, для заблаговременного сообщения пользователю о том, что его сессия истекла и ему необходимо ввести пароль снова, можно воспользоваться запросом 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 будет содержать текст ошибки.

Прямое геокодирование — определение координат по топониму. Обратное — наоборот. Для уменьшения злоупотребления геокодированием авторизация пользователя является обязательной. Фактически, геокодер УкрЯмы является прокси-сервером для геокодера Google Map, так что можно обращаться напрямую в Google Map, и ответ сервера практически совпадает с ответом Google Map.

Геокодирование получается обращением методом POST по адресу /geocode/:

POST /xml/geocode/
Поля POST:
{
	login: <логин пользователя>
	passwordhash: <хэш пароля>
	geocode: <любая строка или координаты через запятую>
}

Вместо passwordhash может быть передан password.

Обратите внимание, что в поле geocode передаётся сначала долгота, потом широта.

Ответ сервера содержит в себе элемент <geocode>, в котором целиком содержится (за исключением тэга <?xml>) ответ Яндекса в формате XML (пробелы, которыми сделан отступ строк слева, заменены на символы табуляции). В случае ошибки элемент <geocode> отсутствует, а вместо него выводится ошибка. Если не указан адрес или координаты, то выводится ошибка GEOCODE_EMPTY_REQUEST (пустой запрос к геокодеру), в случае каких-либо иных ошибок выводится GEOCODE_ERROR.

В некоторых ситуациях вместо ответа в формате 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. Скрипты на сайте не проверяют валидность вводимых данных. Сгенерированный текст заявления не хранится на сервере.