Wialon для разработчиков Руководство пользователя Документация API order update

update

Метод order/update позволяет создавать, обновлять, удалять, назначать, подтверждать, отклонять и переназначать заявки, а также перемещать их в историю.

Начало работы

Параметр callMode определяет действие, которое выполняет запрос. Чтобы работать с заявкой, последовательно отправьте следующие запросы:

Создайте заявку с помощью "callMode":"create". Если на заявку не назначен объект, возвращаемый результат содержит "s":0 (неактивна).
Назначьте объект на заявку с помощью "callMode":"assign". Статус заявки меняется на 1 (активна).
Вручную переместите заявку в историю с помощью "callMode":"register".

Создание или обновление заявки

Чтобы создать или обновить заявку, используйте следующий запрос:

Copied!

svc=order/update&params={
  "itemId": <long>,    /* идентификатор ресурса */
  "id": <long>,        /* идентификатор заявки (0 при создании) */
  "n": "<text>",       /* имя заявки */
  "oldOrderId": <long>, /* идентификатор старой заявки */
  "oldOrderFiles": ["<text>"], /* массив файлов старой заявки */
  "p": {               /* параметры заявки */
    "n": "<text>",     /* имя клиента */
    "p": "<text>",     /* телефон */
    "p2": "<text>",    /* второй телефон */
    "e": "<text>",     /* email */
    "a": "<text>",     /* адрес */
    "v": "<text>",     /* объем */
    "w": "<text>",     /* вес, кг */
    "c": <uint>,       /* стоимость */
    "ut": <uint>,      /* время обслуживания, с */
    "t": "<text>",     /* тип транспортного средства */
    "d": "<text>",     /* описание */
    "uic": "<text>",   /* номер накладной */
    "cid": "<text>",   /* произвольный идентификатор */
    "cm": "<text>",    /* комментарий при подтверждении/отклонении заявки */
    "aff": "<text>",   /* [склад] список идентификаторов объектов склада ("123,456") */
    "z": "<text>",     /* [склад] список геозон склада ("resId_geofenceId,...") */
    "ntf": <uint>,     /* флаги уведомлений: 1 - SMS на первый телефон; 0x2 - SMS на второй телефон; 0x10 - email */
    "pr": <uint>,      /* приоритет заявки */
    "tags": [<uint>],  /* теги заявки */
    "r": {             /* информация о маршруте */
      "id": "<uint>",  /* идентификатор маршрута */
      "i": "<uint>",   /* номер [0..] */
      "m": "<uint>",   /* пробег от предыдущей точки по плану, м */
      "t": "<uint>",   /* время от предыдущей точки по плану, с */
      "ndt": <uint>,   /* за сколько времени до расчетного времени доставки уведомить клиента, с */
      "vt": "<uint>"   /* время посещения по плану, UNIX_TIME */
    }
  },
  "rp": "<text>",      /* маршрут заявки */
  "f": <uint>,         /* флаги заявки */
  "tf": <uint>,        /* нижняя граница времени выполнения заявки, UNIX-time */
  "tt": <uint>,        /* верхняя граница времени выполнения заявки, UNIX-time */
  "trt": <uint>,       /* допустимое время опережения графика, с */
  "r": <uint>,         /* радиус точки заявки, м */
  "y": <double>,       /* широта точки заявки */
  "x": <double>,       /* долгота точки заявки */
  "u": <long>,         /* идентификатор объекта */
  "ej": {},            /* расширенный JSON (необязательно) */
  "tz": <int>,         /* временная метка пользователя */
  "force": <uint>,     /* разрешить обновление заявки, входящей в маршрут: 1 - да, 0 - нет (необязательно) */
  "callMode": "<text>", /* "create" или "update" для создания или обновления соответственно */
  "dp": ["<uint>", ..] /* массив идентификаторов зависимых заявок */
}

Значения параметра f описаны в разделе Флаги.

Если заявка входит в маршрут (ее значение p.r.id не равно 0), ее можно обновить, только если параметр p.r в запросе содержит те же значения id, i, m, t, vt и ndt, что и заявка. В противном случае возвращается ошибка 6 с причиной ORDER_IN_ROUTE. Чтобы все равно обновить такую заявку, укажите "force":1. В Wialon Local эта проверка доступна начиная с версии 2404.

Удаление заявки

Чтобы удалить заявку, используйте следующий запрос:

Copied!

svc=order/update&params={
  "itemId": <long>,   /* идентификатор ресурса */
  "id": <long>,       /* идентификатор заявки */
  "force": <uint>,    /* разрешить удаление заявки, входящей в маршрут: 1 - да, 0 - нет (необязательно) */
  "callMode": "delete"
}

Заявку, которая входит в маршрут (ее значение p.r.id не равно 0), удалить нельзя. В этом случае возвращается ошибка 6 с причиной ORDER_IN_ROUTE:

Copied!

{
  "error": 6,
  "reason": "ORDER_IN_ROUTE"
}

Чтобы все равно удалить такую заявку, укажите "force":1.

Перемещение заявки в историю вручную

Чтобы переместить заявку в историю, используйте следующий запрос:

Copied!

svc=order/update&params={
  "itemId": <long>,   /* идентификатор ресурса */
  "id": <long>,       /* идентификатор заявки */
  "callMode": "register"
}

Назначение объекта на заявку

Чтобы назначить объект на заявку, используйте следующий запрос:

Copied!

svc=order/update&params={
  "itemId": <long>,   /* идентификатор ресурса */
  "id": <long>,       /* идентификатор заявки */
  "u": <long>,        /* идентификатор объекта */
  "callMode": "assign"
}

Отклонение заявки

Чтобы отклонить заявку, используйте следующий запрос:

Copied!

svc=order/update&params={
  "itemId": <long>,   /* идентификатор ресурса */
  "id": <long>,       /* идентификатор заявки */
  "ej": {},           /* расширенный JSON (необязательно) */
  "callMode": "reject"
}

Ключи параметра ej объединяются с текущим расширенным JSON заявки: ключи с совпадающими именами заменяются, новые ключи добавляются, а остальные ключи остаются без изменений.

Переназначение заявки

Чтобы отклонить заявку и отметить ее как переназначенную, используйте следующий запрос:

Copied!

svc=order/update&params={
  "itemId": <long>,   /* идентификатор ресурса */
  "id": <long>,       /* идентификатор заявки */
  "callMode": "reassign"
}

Статус заявки меняется так же, как при "callMode":"reject", но в параметре sf устанавливается флаг 0x2000 (переназначена) вместо 0x100 (отклонена).

Подтверждение заявки

Чтобы подтвердить заявку, используйте следующий запрос:

Copied!

svc=order/update&params={
  "itemId": <long>,   /* идентификатор ресурса */
  "id": <long>,       /* идентификатор заявки */
  "ds": <uint>,       /* статус выполнения, например, % (необязательно, по умолчанию 0) */
  "ignoreConfirmInRadius": <uint>, /* подтвердить заявку независимо от местоположения объекта: 1 - да, 0 - нет (необязательно) */
  "ej": {},           /* расширенный JSON (необязательно) */
  "callMode": "confirm"
}

Если у заявки есть флаг 0x40, ее можно подтвердить, только если назначенный на нее объект находится в пределах радиуса заявки. В этом случае пользователю требуется право Использование объекта в уведомлениях, заданиях, маршрутах, ретрансляторах на объект. Если объект находится за пределами радиуса, возвращается ошибка 7 с причиной UNIT_NOT_IN_RADIUS. Чтобы пропустить эту проверку, укажите "ignoreConfirmInRadius":1.

Параметр ej объединяется с текущим расширенным JSON заявки так же, как при отклонении заявки.

Флаги

Флаги заявки передаются в параметре f. Доступны следующие флаги:

Значение	Описание
`0x1`	Заявка отмечается как выполненная, если в области заявки есть хотя бы одно сообщение с нулевой скоростью.
`0x2`	Заявка выполняется после выхода объекта из области заявки.
`0x4`	Первый склад.
`0x8`	Последний склад.
`0x10`	Промежуточный склад (склад перегрузки).
`0x20`	Постоянная заявка.
`0x40`	Заявку нельзя подтвердить за пределами указанного радиуса.
`0x80`	Статус заявки не меняется после автоматического завершения маршрута.
`0x100`	Если маршрут завершен автоматически, а заявка не выполнена, на основе копии заявки создается новая заявка.

Флаги 0x8 и 0x10 учитываются при оптимизации, только если заявки находятся в массиве складов.

Внутренние флаги

Внутренние флаги возвращаются в параметре if. Доступны следующие флаги:

Значение	Описание
`0x1`	Заявка доставляется.
`0x2`	Водитель уведомлен об отклонении от маршрута.
`0x4`	Водитель уведомлен о том, что заявка не подтверждена.
`0x8`	Клиент уведомлен о предыдущем расчетном времени прибытия.
`0x10`	Клиент уведомлен о расчетном времени прибытия.
`0x20`	Клиент уведомлен о расстоянии, оставшемся до точки доставки.
`0x40`	Заявка подтверждена, но доставка не начата.
`0x80`	Водитель уведомлен об отклонении от планового времени посещения.
`0x100`	Водитель уведомлен об отклонении от планового времени разгрузки.
`0x200`	Клиент уведомлен о расчетном времени прибытия для маршрута.

Ответ

Если запрос выполнен успешно, возвращаемый результат зависит от значения callMode.

Для "callMode":"create":

Copied!

[
	<uint>,
	{
		"id":<uint>,			/* идентификатор заявки */
		"n":"<text>",			/* имя заявки */
		"p":{				/* параметры заявки */
			"n":"<text>",		/* имя клиента */
			"p":"<text>",		/* телефон */
			"p2":"<text>",		/* второй телефон */
			"e":"<text>",		/* email */
			"a":"<text>",		/* адрес */
			"v":<uint>,		/* объем */
			"w":<uint>,		/* вес, кг */
			"c":<uint>,		/* стоимость */
			"ut":<uint>,		/* время обслуживания, с */
			"t":"<text>",		/* тип транспортного средства */
			"d":"<text>",		/* описание */
			"uic":"<text>",		/* номер накладной */
			"cid":"<text>",		/* произвольный идентификатор */
			"cm":"<text>",		/* комментарий, оставленный при подтверждении или отклонении заявки */
			"aff":"<text>",		/* [ склад ] список идентификаторов объектов склада ("123,456") */
			"z":"<text>",		/* [ склад ] список геозон склада ("resId_geofenceId,...") */
			"ntf":<uint>,		/* флаги уведомлений */
			"pr":<uint>,		/* приоритет заявки */
			"r":{			/* информация о маршруте */
				"id":"<text>",	/* идентификатор маршрута */
				"i":"<text>",	/* номер [0..] */
				"m":"<text>",	/* пробег от предыдущей точки по плану, м */
				"t":"<text>",	/* время от предыдущей точки по плану, с */
				"ndt":<uint>,	/* за сколько времени до расчетного времени доставки необходимо уведомить клиента, с */
				"vt":"<text>"	/* время посещения по плану, UNIX_TIME */
			}
		},
		"rp":"<text>",			/* маршрут заявки в формате google polyline encoding */
		"f":<uint>,			/* флаги заявки */
		"tf":<uint>,			/* нижняя граница времени выполнения заявки, UNIX-time */
		"tt":<uint>,			/* верхняя граница времени выполнения заявки, UNIX-time */
		"trt":<uint>,			/* допустимое время опережения графика, с */
		"uid":<uint>,			/* уникальный идентификатор (используется как уникальный ключ в истории заявок) */
		"r":<uint>,			/* радиус точки заявки, м */
		"y":<double>,			/* широта точки заявки */
		"x":<double>,			/* долгота точки заявки */
		"u":<long>,			/* идентификатор объекта */
		"s":<uint>,			/* статус заявки: 0 - неактивна (объект не назначен), 1 - активна, 2 - выполнена вовремя, 3 - выполнена с опозданием, 4 - отклонена, 5 - объект находится в области заявки */
		"sf":<uint>,			/* флаг статуса заявки (0x100 - отклонена, 0x200 - подтверждена, 0x400 - получено уведомление о заявке (устарело), 0x800 - следующая заявка в начатом маршруте, 0x1000 - просрочена, 0x2000 - переназначена) */
		"st":<uint>,			/* время последнего изменения статуса */
		"tz":<uint>,			/* временная метка пользователя */
		"eta":<uint>,			/* ETA, рассчитываемое каждые 180 секунд с помощью маршрутизации (или по прямой линии), если есть следующая заявка и включено уведомление о ETA/пробеге (RD) */
		"rd":<double>,			/* пробег */
		"cnm":<uint>,			/* счетчик пробега из свойств объекта */
		"nt":<uint>,			/* next_time, время получения заявками статуса 'next' */
		"ds":<uint>,			/* статус выполнения, целое число передается в параметре 'confirm', например, % */
		"dp":<uint>,			/* список UID заявок, от которых зависит текущая заявка: текущую заявку нельзя выполнить, пока не выполнены перечисленные заявки */
		"stt":<uint>,			/* start_transfer_time, время прибытия */
		"dtt":<uint>,			/* done_transfer_time, время выезда */
		"if":<uint>			/* internal_flags */
	}
]

Значения параметра if описаны в разделе Внутренние флаги.

Для "callMode":"update":

Copied!

[
	<uint>		/* идентификатор обновленной заявки */
]

Для "callMode":"delete":

Copied!

[
	<uint>,		/* идентификатор удаленной заявки */
	null
]

Для "callMode":"assign", "callMode":"register", "callMode":"reject", "callMode":"reassign" и "callMode":"confirm":

Copied!

{ }	/* успешно */

или

Copied!

{
	"error":4	/* если назначить не удалось */
}

При неудачном выполнении возвращается код ошибки.

Коды ошибок

Код ошибки	Описание
4	Неверный режим вызова или неверные переданные данные, либо заявка с указанным ID не существует (для `"callMode":"confirm"` с причиной `ORDER_NOT_FOUND`).
6	Одна из следующих ошибок: заявка с указанным ID не существует или не может быть обновлена. Убедитесь, что указан правильный ID заявки; заявка входит в маршрут (причина `ORDER_IN_ROUTE`). Чтобы удалить или обновить такую заявку, укажите `"force":1`; не удалось обновить расширенный JSON заявки при ее отклонении или подтверждении (причина `CAN_NOT_UPDATE_EJ`).
7	Не удалось получить ресурс или объект. При подтверждении заявки с флагом `0x40` возможны следующие причины: `UNIT_NOT_FOUND`: объект не существует или у пользователя нет права Использование объекта в уведомлениях, заданиях, маршрутах, ретрансляторах на него; `UNIT_UNKNOWN_POSITION`: местоположение объекта неизвестно; `UNIT_NOT_IN_RADIUS`: объект находится за пределами радиуса заявки.

Если вы заметили ошибку в тексте, пожалуйста, выделите её и нажмите Ctrl+Enter.