Соответствует текущей версии 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>

Ниже представлен перечень кодов ошибок, которые сервер может возвращать:

Помимо ошибок, сервер может возвращать предупреждения. Тэг предупреждения имеет следующий формат:

<warning code="WARNING">Это предупреждение</warning>

Предупреждений может быть несколько, и они могут соседствовать с прочими элементами в ответе сервера. Предупреждения могут быть возвращены в ответах не на все запросы, а только на некоторые, и все возможные случаи описаны отдельно. Обрабатывать предупреждения или нет — дело разработчика приложения.

Возможные предупреждения, который может возвращать сервер:

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

Возможные параметры, которые могут быть переданы в запросе:

limit = default_limit (30 дефектов),
offset = page*default_limit.

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 в данный момент не реализована.

Запрос 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:

Комментарии к файлам

Файлы должны быть переданы именно как файлы (encryption type должно быть multipart/form-data). Имена, под которыми файлы передаются на сервер, не имеют значения, но их должно быть не больше десяти. Обрабатываться они будут в том порядке, в котором будут переданы на сервер. В том случае, если файлов будет больше, чем десять, те файлы, которые были переданы после десятого, не будут обработаны, и будет выдано предупреждение FILES_DROPPED.

В том случае, если суммарный размер файлов превышает допустимые ограничения, никакой специфической ошибки не возвращается, так как веб-сервер обычно обрабатывает эту ситуацию самостоятельно. Вероятнее всего в этом случае можно получить ошибку AUTHORIZATION_REQUIRED. Узнать максимальный размер одного файла и максимальный суммарный размер файлов можно с помощью запроса GetFileUploadLimits.

В случае, если при загрузке файлов произошли какие-то другие ошибки, то они будут выведены в XML.

Ошибки, которые могут возникнуть при загрузке файлов:

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

Изменение дефекта

Существует несколько запросов, позволяющих изменить дефект. Эти запросы различны по тем данным, которые могут быть изменены, и по тому, когда они могут быть вызваны, это зависит от статуса дефекта. По своей сути эти запросы сводятся к одному универсальному, но снаружи этого не видно.

Список запросов, которыми можно изменять дефект.

Дефект переходит из статуса «в процессе» в статус «просрочен» самостоятельно с течением времени.

Для удобства пользования существует служебный запрос 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:

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