Объекты обслуживания клиента
Все операции. Авторизация. Запросы и повторы.
Все пути в этом файле дополняют /api/v1 на домене организации.
Описание и ограничения
Назначение
Адреса и площадки клиента, к которым относятся оборудование, договоры и выезды.
Доступные возможности и ограничения
Реализованы GET списка/карточки и POST для создания, изменения и архивирования. Изменения используют обязательные Idempotency-Key и, кроме создания, If-Resource-Version. Записи об операциях сохраняются вместе с бизнес-записью и событием; повтор заново проверяет текущий доступ. Доступ к API — «Энтерпрайз», «Энтерпрайз Про» или действующий пробный период; «Энтерпрайз Лайт» не включает API.
Требуются customer_sites:read и текущее «Клиенты и поставщики → Просмотр». Доступ ограничивается доступным клиентом; скрытый клиент не раскрывается через объект. GET не меняет координаты, контакты или связи. Сортировка в API: id или -id; фильтры customer_id, is_active и q.
data.version — строка Unix-секунд из updated_at. Два изменения в одну секунду могут иметь одинаковую версию. Для проверки изменений используйте правила синхронизации. Карточка также возвращает отдельный ETag своего представления.
Архивирование сохраняет историю оборудования и документов. Объект без связанных записей можно перенести к другому доступному клиенту через customer_id. Если с ним связаны оборудование, карта помещений, выезд, договор или регламент ТО, возвращается 409 RESOURCE_IN_USE; остальные поля запроса также не меняются. Параллельное создание связи учитывается при проверке переноса.
Создание, изменение и архивирование объекта формируют соответствующие события. Уведомление содержит только идентификатор, версию и признак удаления. Перед доставкой проверяется доступ к текущему клиенту объекта; после переноса событие прежнего клиента не доставляется. is_active=false отключает объект, а архивирование выполняется отдельной командой.
Поля и назначение
| Публичное поле | Формат и смысл | Доступ |
|---|---|---|
id |
id |
только чтение |
customer_id |
обязательный id клиента |
чтение и запись |
name, code |
наименование и внешний код | чтение и запись |
address, latitude, longitude |
адрес и проверенные координаты | чтение и запись |
contact_name, phone, email |
контакт на объекте | чтение и запись |
note, is_active |
строка/null и логическое значение | чтение и запись |
Обязательность и null указаны в схемах каждой операции ниже.
Доступ и выборка
customer_sites:read/write и права клиента; использование объекта дополнительно проверяется в операции с оборудованием, договором или выездом.
Фильтры: customer_id, is_active, q.
Правила и связи
- Объект связан с одним клиентом; оборудование и договор должны относиться к нему же.
- Архивный объект сохраняется в истории, но недоступен для новой привязки.
- Смена клиента не должна незаметно перенести существующее оборудование и договоры.
- Пустой объект переносится атомарно, объект с любым из пяти видов зависимостей возвращает
RESOURCE_IN_USE.
Операции
| Метод | Путь | Назначение |
|---|---|---|
| POST | /customer-sites |
Создание |
| GET | /customer-sites |
Список с фильтрами и пагинацией |
| POST | /customer-sites/{id}/update |
Изменение разрешённых полей |
| POST | /customer-sites/{id}/archive |
Архивация |
| GET | /customer-sites/{id} |
Карточка |
POST /customer-sites
Создание.
Доступ. Разрешения подключения: customer_sites:write. Права сотрудника: «Клиенты и поставщики → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
| Поле | Тип | Обязательно | null | Ограничения и смысл |
|---|---|---|---|---|
customer_id |
целое число | да | нет | ≥ 1 |
name |
строка | да | нет | не менее 1 символов; не более 255 символов |
code |
строка / null | нет | да | не более 255 символов |
address |
строка / null | нет | да | не более 2000 символов |
latitude |
число / null | нет | да | ≥ -90.0; ≤ 90.0 |
longitude |
число / null | нет | да | ≥ -180.0; ≤ 180.0 |
contact_name |
строка / null | нет | да | не более 255 символов |
phone |
строка / null | нет | да | не более 255 символов |
email |
строка / null (email) |
нет | да | не более 255 символов |
note |
строка / null | нет | да | не более 10000 символов |
is_active |
логическое значение | нет | нет | — |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 201 | Создано. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 201 | Location |
строка | |
| 201 | Idempotency-Replayed |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff --request POST \
"$API/customer-sites" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-customer-sites-store:001" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.customer-sites.store.json'
GET /customer-sites
Список с фильтрами и пагинацией.
Доступ. Разрешения подключения: customer_sites:read. Права сотрудника: «Клиенты и поставщики → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
sort |
параметр запроса | строка | нет | нет | Допустимо: "id", "-id" |
page[size] |
параметр запроса | целое число | нет | нет | ≥ 1; ≤ 100 |
page[cursor] |
параметр запроса | строка | нет | нет | не более 8192 символов |
filter[customer_id] |
параметр запроса | целое число | нет | нет | ≥ 1 |
filter[is_active] |
параметр запроса | строка | нет | нет | Допустимо: "true", "false" |
filter[q] |
параметр запроса | строка | нет | нет | не более 200 символов |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/customer-sites" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"
POST /customer-sites/{id}/update
Изменение разрешённых полей.
Доступ. Разрешения подключения: customer_sites:write. Права сотрудника: «Клиенты и поставщики → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
If-Resource-Version |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._~-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
| Поле | Тип | Обязательно | null | Ограничения и смысл |
|---|---|---|---|---|
customer_id |
целое число | нет | нет | ≥ 1 |
name |
строка | нет | нет | не менее 1 символов; не более 255 символов |
code |
строка / null | нет | да | не более 255 символов |
address |
строка / null | нет | да | не более 2000 символов |
latitude |
число / null | нет | да | ≥ -90.0; ≤ 90.0 |
longitude |
число / null | нет | да | ≥ -180.0; ≤ 180.0 |
contact_name |
строка / null | нет | да | не более 255 символов |
phone |
строка / null | нет | да | не более 255 символов |
email |
строка / null (email) |
нет | да | не более 255 символов |
note |
строка / null | нет | да | не более 10000 символов |
is_active |
логическое значение | нет | нет | — |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 412 | Версия устарела. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 428 | Нужно предусловие версии. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | Location |
строка | |
| 200 | Idempotency-Replayed |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff --request POST \
"$API/customer-sites/101/update" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-customer-sites-update:001" \
--header "If-Resource-Version: $RESOURCE_VERSION" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.customer-sites.update.json'
POST /customer-sites/{id}/archive
Архивация.
Доступ. Разрешения подключения: customer_sites:write. Права сотрудника: «Клиенты и поставщики → Изменение». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
Idempotency-Key |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._:-]+$ |
If-Resource-Version |
заголовок | строка | да | нет | не менее 1 символов; не более 128 символов; Шаблон: ^[A-Za-z0-9._~-]+$ |
Тело запроса
Content-Type: application/json. Тело обязательно.
Тело — пустой JSON-объект {}. Другие ключи не принимаются.
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 409 | Конфликт состояния или повтора. Коды и формат ошибки |
| 412 | Версия устарела. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 428 | Нужно предусловие версии. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | Location |
строка | |
| 200 | Idempotency-Replayed |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
У принятого POST Location и meta.operation_id указывают на журнал операции; ETag отсутствует. При повторе запроса сохраняются исходные data/meta, добавляется Idempotency-Replayed: true. Версии передавайте по назначению, указанному в описании ресурса.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff --request POST \
"$API/customer-sites/101/archive" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json" \
--header "Idempotency-Key: example:v1-customer-sites-archive:001" \
--header "If-Resource-Version: $RESOURCE_VERSION" \
--header "Content-Type: application/json" \
--data-binary '@examples/requests/v1.customer-sites.archive.json'
GET /customer-sites/{id}
Карточка.
Доступ. Разрешения подключения: customer_sites:read. Права сотрудника: «Клиенты и поставщики → Просмотр». Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
id |
путь | строка | да | нет | Шаблон: ^(?:[0-9]+)$ |
If-None-Match |
заголовок | строка | нет | нет | — |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 304 | Представление не изменилось, без тела. Условный GET |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 403 | Недостаточно допуска. Коды и формат ошибки |
| 404 | Не найдено или недоступно. Коды и формат ошибки |
| 422 | Ошибка входных данных. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
| HTTP | Заголовок ответа | Тип | Описание |
|---|---|---|---|
| 200 | ETag |
строка | |
| 304 | ETag |
строка |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/customer-sites/101" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"