Обновление наряда

Для обновления наряда отправьте PATCH-запрос на https://api.planado.ru/v2/jobs/:job_id. Здесь :job_id это uuid или external_id.

$ curl -H "Authorization: Bearer api-key" \
       -X PATCH \
       --data "{\"description\": \"Updated description\"}" \
       https://api.planado.ru/v2/jobs/8070f98d-b3f6-4cc8-b7c4-54b6709cd98b | jq
{
  "job_uuid": "8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"
}

Схема запроса

Все поля необязательны.

Поле Тип JSON-тип Обязательно Может быть null Описание

description

Строка

Строка

Нет

Да

Текстовое описание наряда. Ограничено 15000 символов

scheduled_at

Дата и время

Строка

Нет

Да

Запланированная дата начала наряда

scheduled_duration

Длительность

Объект

Нет

Да

Запланированная длительность

assignee

Исполнитель

Объект

Нет

Да

Исполнитель — пользователь или бригада

assignees

[Множественный исполнитель]

Массив

Нет

Нет

Список исполнителей.
Если передан, то значение поля assignee игнорируется. Должен включать как минимум одного исполнителя с edit правом

possible_resolutions

[Резолюция]

Массив

Нет

Нет

Список возможных резолюций. Если передан, должен включать как минимум одну успешную и одну неуспешную резолюцию

address

Адрес

Объект

Нет

Нет

Адрес

contacts

[Контакт]

Массив

Нет

Нет

Список контактов

client

Существующий клиент или Новый клиент

Объект

Нет

Да

Клиент

site

Существующий объект или Новый объект

Объект

Нет

Да

Объект

territory

Участок

Объект

Нет

Да

Участок

skills

[Навык]

Массив

Нет

Нет

Навыки, необходимые для выполнения наряда

custom_fields

[Доп. поле]

Массив

Нет

Нет

Значения дополнительных полей наряда

report_fields

[Доп. поле]

Массив

Нет

Нет

Значения полей отчета наряда

expected_version

Целое

Число

Нет

Нет

Версия наряда (version), на основе которой сделано обновление. Если наряд с тех пор изменился, обновление будет отклонено, см. Условное обновление

Некоторые поля, например, possible_resolutions, assignees и assignee, нельзя обновлять у начатого наряда.

Условное обновление

Чтобы не перезаписать изменение, сделанное после того, как вы получили наряд (например, ручную правку длительности диспетчером), передайте expected_version — значение version из ответа запроса наряда. Планадо проверяет версию и записывает обновление атомарно, поэтому изменение, сделанное после вашего запроса, не будет перезаписано.

$ curl -H "Authorization: Bearer api-key" \
       -X PATCH \
       --data "{\"scheduled_duration\": {\"minutes\": 90}, \"expected_version\": 5}" \
       https://api.planado.ru/v2/jobs/8070f98d-b3f6-4cc8-b7c4-54b6709cd98b | jq

Если версия наряда уже не равна expected_version, ничего не записывается, а ответ — 409 Conflict:

{
  "code": "stale_version",
  "retryable": false
}

Версию увеличивает любое изменение наряда, а не только изменение передаваемых полей: например, смена статуса исполнителем. Получив stale_version, запросите наряд снова, решите, нужно ли обновление, и отправьте его с новой version.

Без expected_version обновление применяется к текущему состоянию наряда. В обоих случаях ответом также может быть 409 Conflict с "code": "version_conflict" и "retryable": true, если наряд одновременно изменяется кем-то ещё: повторите тот же запрос.

Обновление и добавление полей

Примеры изменения полей.