Общие структуры ответов

Здесь приведены структуры ответов, используемые API. Они имеют одинаковую форму и правила для всех вызовов.

Контакт

Table 1. Поля контакта
Поле	Тип	JSON-тип	Может быть `null`	Описание
`name`	Строка	Строка	Да	Имя контакта. Ограничено 50 символами
`value`	Строка	Строка	Да	Значение контакта. Ограничено 50 символами
`type`	Строка	Строка	Нет	Тип контакта. В настоящее время поддерживается только `"phone"`

Адрес

Table 2. Поля адреса
Поле	Тип	JSON-тип	Может быть `null`	Описание
`formatted`	Строка	Строка	Да	Полный адрес одной строкой
`apartment`	Строка	Строка	Да	Номер квартиры или офиса. До 50 символов
`floor`	Строка	Строка	Да	Этаж. До 50 символов
`entrance_no`	Строка	Строка	Да	Подъезд. До 50 символов
`description`	Строка	Строка	Да	Примечание к адресу. Это поле обычно содержит информацию, помогающую найти адрес исполнителю. До 500 символов
`geolocation`	Геокоординаты	Объект	Да	Геокоординаты

Выездной сотрудник

Выездной сотрудник — это пользователь с правами на выполнение нарядов.

Table 3. Поля сотрудника
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор сотрудника
`email`	Строка	Строка	Нет	Email сотрудника

Бригада

Бригада — это группа сотрудников.

Table 4. `team` fields
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор бригады
`team`	Строка	Строка	Нет	Название бригады

Исполнитель

Наряды и шаблоны нарядов могут иметь исполнителей. Исполнитель — это одиночный сотрудник или бригада сотрудников.

Поля team и worker взаимно исключают друг друга, должно быть передано только одно.

Table 5. Поля исполнителя
Поле	Тип	JSON-тип	Может быть `null`	Описание
`team`	Бригада	Объект	Нет	Бригада
`worker`	Пользователь	Объект	Нет	Сотрудник

Идентификатор исполнителя

Поля team_uuid и worker_uuid взаимно исключают друг друга, должно быть передано только одно.

Table 6. Поля исполнителя
Поле	Type	JSON-тип	Может быть `null`	Описание
`team_uuid`	UUID	Строка	Нет	Идентификатор бригады
`worker_uuid`	UUID	Строка	Нет	Идентификатор сотрудника

Клиент

Table 7. Поля клиента
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор клиета
`external_id`	Строка	Строка	Да	Внешний идентификатор

Участок

Участок это область, где работает исполнитель.

Table 8. Поля участка
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор участка
`name`	Строка	Строка	Нет	Название участка

Навык

Навыки сотрудника используются для подбора исполнителя для наряда.

Table 9. `skill` fields
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор навыка
`name`	Строка	Строка	Нет	Название навыка

Значение из списка

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

Table 10. Поля значения из списка
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор
`name`	Строка	Строка	Нет	Название

Резолюция

Резолюция это результат выполнения наряда. Резолюция может быть успешной или неуспешной.

Table 11. Поля резолюции
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор резолюции
`name`	Строка	Строка	Нет	Название резолючии
`successful`	Булев	Булев	Нет	Является ли резолюция успешной
`comment`	Строка	Строка	Да	Комментарий, заполненный исполнителем при завершении наряда. Это поле присутствует только в резолюции завершенного наряда

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

Дополнительные поля добавляются в наряды через шаблоны. В наряде существует две секции с дополнительными полями: поля наряда (custom_fields) и поля отчета (report_fields). Поля наряда заполняются диспетчером при добавлении нового наряда. Для исполнителя эти поля доступны только на чтение. Поля отчета заполняются исполнителем во время выполнения наряда.

Тип поля value зависит от значения полей field_type и data_type.

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

Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Идентификатор поля
`name`	Строка	Строка	Нет	Название поля
`field_type`	Строка	Строка	Нет	Тип поля
`data_type`	Строка	Строка	Нет	Тип данных
`required`	Булев	Булев	Нет	Является ли поле обязательным. В случае полей наряда (`custom_fields`) диспетчер должен будет заполнить эти поля при добавлении нового наряда. В случае полей отчета (`report_fields`) исполнитель должен будет заполнить эти поля, чтобы успешно завершить наряд
`value`	Смешанный	Смешанный	Да	Значение дополнительного поля. Это поле всегда присутствует в API нарядов, но в API шаблонов оно присутствует только у полей, которые могут быть предзаполнены (например, поле типа «файл» (`file`))
`filled_at`	Дата и время	Строка	Нет	Временная метка, когда значение было изменено в последний раз. Это поле присутствует только для полей отчета с непустым значением

uuid

UUID

Строка

Нет

Идентификатор поля

name

Строка

Нет

Название поля

field_type

Строка

Нет

Тип поля

data_type

Строка

Нет

Тип данных

required

Булев

Нет

Является ли поле обязательным.
В случае полей наряда (custom_fields) диспетчер должен будет заполнить эти поля при добавлении нового наряда.
В случае полей отчета (report_fields) исполнитель должен будет заполнить эти поля, чтобы успешно завершить наряд

value

Смешанный

Да

Значение дополнительного поля. Это поле всегда присутствует в API нарядов, но в API шаблонов оно присутствует только у полей, которые могут быть предзаполнены (например, поле типа «файл» (file))

filled_at

Дата и время

Строка

Нет

Временная метка, когда значение было изменено в последний раз. Это поле присутствует только для полей отчета с непустым значением

Типы полей

image
input
action
checkbox
textarea
barcode
file
dictionary

Типы данных

string
boolean
attachment
dictionary

Поддерживаемые комбинации

Различные комбинации типа поля и типа данных по-разному поддерживаются полями наряда (custom_fields) и полями отчета (report_fields). Ниже «ПН» («поле наряда») и «ПО» («поле отчета») показывают допустимость комбинации типа поля (field_type) и типа данных (data_type) для полей наряда и полей отчета соответственно.

field_type data_type ПН ПО Тип value Может быть null Описание

`field_type`	`data_type`	ПН	ПО	Тип `value`	Может быть `null`	Описание
`input`	`string`	Да	Да	Строка	Да	Текстовое поле (одна строка)
`textarea`	`string`	Нет	Да	Строка	Да	Многострочное текстовое поле
`action`	`boolean`	Нет	Да	Булев	Да	Действие
`checkbox`	`boolean`	Нет	Да	Булев	Да	Да/нет
`barcode`	`string`	Нет	Да	Строка	Да	Штрихкод/QR-код
`file`	`attachment`	Да	Нет	Строка	Да	Файл
`image`	`attachment`	Нет	Да	[Строка]	Нет	Список изображений
`dictionary`	`dictionary`	Да	Да	Значение из списка	Да	Список значений

input

string

Да

Строка

Да

Текстовое поле (одна строка)

textarea

string

Нет

Да

Строка

Да

Многострочное текстовое поле

action

boolean

Нет

Да

Булев

Да

Действие

checkbox

boolean

Нет

Да

Булев

Да

Да/нет

barcode

string

Нет

Да

Строка

Да

Штрихкод/QR-код

file

attachment

Да

Нет

Строка

Да

Файл

image

attachment

Нет

Да

[Строка]

Нет

Список изображений

dictionary

Да

Значение из списка

Да

Список значений

Значения типа attachment содержат URL для загрузки файла.

Права пользователя

Объект с правами пользователя. Он описывает то, какие действия может выполнять пользователь.

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

Поле	Тип	JSON-тип	Обязательно	Может быть `null`	Описание
`web`	Структура	Объект	Нет	Нет	Права в веб-приложении
`mobile`	Структура	Объект	Нет	Нет	Права в мобильном приложении

web

Структура

Объект

Нет

Права в веб-приложении

mobile

Структура

Объект

Нет

Права в мобильном приложении

Пример объекта с правами пользователя

{
  "web": {
    "login": true,
    "jobs": {
      "view": true,
      "edit": true,
      "delete": true
    },
    "clients": {
      "view": true,
      "edit": true
    },
    "schedule": {
      "view": true,
      "edit": true
    },
    "map": {
      "edit": false
    },
    "shifts": {
      "edit": false
    },
    "teams": {
      "view": true,
      "edit": true
    },
    "jobs_export": false
  },
  "mobile": {
    "login": true,
    "jobs": {
      "view": true,
      "complete": true
    }
  }
}