Перейти к содержимому
СервисАпп API

Публичный API

Все 278 методов Получить токен

Доступен на «Энтерпрайз» и «Энтерпрайз Про». Как подключить

1. Проверить подключение

Подставьте HTTPS-домен своей организации и токен. Как получить токен. Пример использует Bash, curl и jq.

export SERVICEAPP_ORIGIN='https://organization.example'
export SERVICEAPP_TOKEN='<SERVICEAPP_TOKEN>'
export API="$SERVICEAPP_ORIGIN/api/v1"

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header 'Accept: application/json' \
  "$API/context" | jq .

Центральный сайт и домен другой организации не подходят. Укажите адрес без завершающего /.

Проверьте data.access.status, data.features.public_api, data.scopes, data.workshop_ids, data.timezone и data.currency. Для действующего токена контекст доступен также при отключённом API или завершившейся подписке. При недействительном токене он вернёт 401.

Подготовить доступ к остальным методам

Понадобятся Bash, curl и jq. В панели вашей организации откройте «Настройки → Каналы связи и интеграции → API», создайте персональное подключение, выберите разрешения подключения и мастерские, задайте срок действия. Сохраните показанный один раз секрет. Раздел доступен с правом «Системные настройки → Информация о компании»; подключение выполняет команды от имени создавшего его сотрудника. Для примера нужны customers:read, customers:write и соответствующие права сотрудника.

API должен быть включён для организации. Поддерживаются «Энтерпрайз», «Энтерпрайз Про» и действующий trial. Полные правила доступа.

2. Прочитать список клиентов

curl --fail-with-body --silent --show-error --globoff --get \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header 'Accept: application/json' \
  --data-urlencode 'page[size]=10' \
  --data-urlencode 'sort=id' \
  "$API/customers" | jq .

Следующая страница находится в links.next; конец обхода — meta.has_more=false и links.next=null. include, номер страницы и offset не поддерживаются. Параметры клиентов.

3. Создать клиента

Сохраните тело и ключ до отправки. Этот ключ относится к одному действию в пределах подключения; при сетевом сбое повторите тот же запрос с тем же телом и ключом. Для создания другого клиента выберите новый ключ.

cat > customer-create.json <<'JSON'
{
  "name": "Демонстрационный клиент",
  "phone": "+79990000001",
  "email": "integration@example.com",
  "external_id": "demo-customer-001"
}
JSON

export CUSTOMER_CREATE_KEY='demo:customer:create:001'

curl --fail-with-body --silent --show-error --request POST \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CUSTOMER_CREATE_KEY" \
  --data-binary '@customer-create.json' \
  --dump-header customer-create.headers \
  --output customer-response.json \
  "$API/customers"

jq . customer-response.json
export CUSTOMER_ID="$(jq -r '.data.id' customer-response.json)"
export OPERATION_ID="$(jq -r '.meta.operation_id' customer-response.json)"

Ожидается 201. Ответ содержит карточку в data, запись об операции meta.operation_id, изменённые ресурсы meta.affected_resources и предупреждения meta.warnings. Заголовок Location ведёт на операцию. Повтор того же принятого запроса возвращает сохранённый 201 и Idempotency-Replayed: true, без создания второго клиента.

external_id уникален для этого типа ресурса в текущем подключении. Он дополняет Idempotency-Key. ИНН, КПП, банковские реквизиты и серийные номера передаются строками с сохранением ведущих нулей.

4. Изменить клиента с проверкой версии

Сначала прочитайте актуальную карточку. Версия из ответа создания могла устареть.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --dump-header customer-get.headers \
  --output customer-current.json \
  "$API/customers/$CUSTOMER_ID"

export RESOURCE_VERSION="$(jq -r '.data.version' customer-current.json)"
export CUSTOMER_UPDATE_KEY='demo:customer:update:001'

cat > customer-update.json <<'JSON'
{"address":"Демонстрационный город, Тестовая улица, дом 1"}
JSON

curl --fail-with-body --silent --show-error --request POST \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CUSTOMER_UPDATE_KEY" \
  --header "If-Resource-Version: $RESOURCE_VERSION" \
  --data-binary '@customer-update.json' \
  "$API/customers/$CUSTOMER_ID/update" | jq .

Версия передаётся без кавычек, ровно как получена в data.version. ETag из заголовка GET сюда не подставляется. При 412 перечитайте карточку и согласуйте изменение; изменённое действие отправляйте с новым ключом. При потере ответа повторите исходную команду с сохранённой версией и ключом.

5. Проверить исход по журналу

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $SERVICEAPP_TOKEN" \
  "$API/api-operations/$OPERATION_ID" | jq .

Для журнала нужен api_operations:read. Если ответ первой команды потерян и ID операции неизвестен, повторите исходный POST с прежним ключом. GET журнала читает исход, не исполняя команду повторно. Все состояния и правила опрос состояния.

После знакомства выполните создание акта и ТО с выездом. Общий формат ошибок помогает различать исправление данных, конфликт версии и неопределённый исход.

Справочник методов

278 операций

Выберите ресурс в навигации или найдите метод по действию и адресу.

GET/acts/{act_id}/equipmentСписок: Оборудование в акте POST/acts/{act_id}/equipmentДобавить оборудование в акт POST/acts/{act_id}/equipment/{equipment_id}/removeУдаление единицы из состава с проверкой последствий GET/acts/{act_id}/mediaСписок: Фотографии и документы акта POST/acts/{act_id}/mediaДобавление одного вложения. Разделитель частей multipart/form-data не влияет на повтор запроса GET/acts/{act_id}/media/{id}Карточка: Фотографии и документы акта GET/acts/{act_id}/media/{id}/downloadЗащищённое скачивание. В Range не поддерживается POST/acts/{act_id}/media/{id}/deleteУдалить вложение акта GET/acts/{act_id}/operationsСписок: Работы в акте POST/acts/{act_id}/operationsСоздать работу в акте GET/acts/{act_id}/operations/{id}Карточка: Работы в акте POST/acts/{act_id}/operations/{id}/updateИзменить работу в акте POST/acts/{act_id}/operations/{id}/deleteУдалить работу в акте GET/acts/{act_id}/productsСписок: Товары и запчасти в акте POST/acts/{act_id}/productsСоздать товар в акте GET/acts/{act_id}/products/{id}Карточка: Товары и запчасти в акте POST/acts/{act_id}/products/{id}/updateИзменить товар в акте POST/acts/{act_id}/products/{id}/deleteУдалить товар в акте POST/acts/{id}/apply-kitПрименение комплекта работ и товаров POST/acts/{id}/duplicateКопирование по обычным правилам GET/actsСписок: Акты ремонта, монтажа и ТО POST/actsСоздать акт GET/acts/{id}Карточка: Акты ремонта, монтажа и ТО POST/acts/{id}/updateИзменить акт POST/acts/{id}/statusСмена статуса акта с согласованным обновлением склада, гарантий и обслуживания POST/acts/{id}/deleteУдалить акт GET/api-operationsСписок: Журнал API-операций GET/api-operations/{id}Карточка: Журнал API-операций GET/reference/categoriesСписок: Категории товаров и работ POST/reference/categoriesСоздать категорию GET/reference/categories/{id}Карточка: Категории товаров и работ POST/reference/categories/{id}/updateИзменить категорию POST/reference/categories/{id}/deleteУдалить категорию GET/contextОрганизация, сотрудник и возможности текущего подключения GET/custom-fields/{field_id}/optionsСписок: Варианты дополнительных полей POST/custom-fields/{field_id}/optionsСоздать вариант дополнительного поля GET/custom-fields/{field_id}/options/{id}Карточка: Варианты дополнительных полей POST/custom-fields/{field_id}/options/{id}/updateИзменить вариант дополнительного поля POST/custom-fields/{field_id}/options/{id}/archiveАрхивировать вариант дополнительного поля GET/custom-fieldsСписок: Определения дополнительных полей POST/custom-fieldsСоздать дополнительное поле GET/custom-fields/{id}Карточка: Определения дополнительных полей POST/custom-fields/{id}/updateИзменить дополнительное поле POST/custom-fields/{id}/archiveАрхивировать дополнительное поле POST/customer-sitesСоздать объект обслуживания клиента GET/customer-sitesСписок: Объекты обслуживания клиента POST/customer-sites/{id}/updateИзменить объект обслуживания клиента POST/customer-sites/{id}/archiveАрхивировать объект обслуживания клиента GET/customer-sites/{id}Карточка: Объекты обслуживания клиента GET/customersСписок: Клиенты и контрагенты POST/customersСоздать клиента GET/customers/{id}Карточка: Клиенты и контрагенты POST/customers/{id}/updateИзменить клиента POST/customers/{id}/deleteУдалить клиента POST/customers/{id}/restoreВосстановить клиента GET/reference/defectsСписок: Справочник неисправностей POST/reference/defectsСоздать неисправность GET/reference/defects/{id}Карточка: Справочник неисправностей POST/reference/defects/{id}/updateИзменить неисправность POST/reference/defects/{id}/deleteУдалить неисправность GET/reference/device-partsСписок: Узлы и комплектация устройств POST/reference/device-partsСоздать узел устройства GET/reference/device-parts/{id}Карточка: Узлы и комплектация устройств POST/reference/device-parts/{id}/updateИзменить узел устройства POST/reference/device-parts/{id}/deleteУдалить узел устройства GET/reference/device-typesСписок: Виды оборудования POST/reference/device-typesСоздать вид оборудования GET/reference/device-types/{id}Карточка: Виды оборудования POST/reference/device-types/{id}/updateИзменить вид оборудования POST/reference/device-types/{id}/deleteУдалить вид оборудования GET/equipment/{id}/historyИстория обслуживания и связанных актов POST/equipmentСоздать оборудование GET/equipmentСписок: Оборудование клиентов POST/equipment/{id}/updateИзменить оборудование POST/equipment/{id}/statusСмена эксплуатационного состояния GET/equipment/{id}Карточка: Оборудование клиентов GET/equipment/{id}/assignmentsСписок: Установленное оснащение POST/equipment/{id}/assignmentsСоздать назначение оснащения GET/equipment/{id}/assignments/{assignment}Карточка: Установленное оснащение POST/equipment/{id}/assignments/{assignment}/endЗавершение действия оснащения GET/equipment/{parentId}/checklist-itemsСписок: Шаблон чек-листа оборудования POST/equipment/{parentId}/checklist-itemsСоздать пункт чек-листа оборудования GET/equipment/{parentId}/checklist-items/{id}Карточка: Шаблон чек-листа оборудования POST/equipment/{parentId}/checklist-items/{id}/updateИзменить пункт чек-листа оборудования POST/equipment/{parentId}/checklist-items/{id}/deleteУдалить пункт чек-листа оборудования GET/equipment-defectsСписок: Дефекты оборудования POST/equipment-defectsСоздать дефект оборудования GET/equipment-defects/{id}Карточка: Дефекты оборудования POST/equipment-defects/{id}/updateИзменить дефект оборудования POST/equipment-defects/{id}/resolveФиксация устранения POST/equipment-defects/{id}/create-maintenanceСоздание корректирующей заявки ТО POST/equipment-defects/{id}/create-warranty-actСоздание гарантийного акта GET/equipment-downtimesСписок: Отказы и простои POST/equipment-downtimesСоздать простой GET/equipment-downtimes/{id}Карточка: Отказы и простои GET/equipment-downtimes/{id}/eventsИстория этапов простоя POST/equipment-downtimes/{id}/updateИзменить простой POST/equipment-downtimes/{id}/transitionПереход stopped / repair / waiting_parts / restored GET/equipment/{equipment_id}/mediaСписок: Фото и документы оборудования POST/equipment/{equipment_id}/mediaДобавление документа или установка основного фото, multipart/form-data GET/equipment/{equipment_id}/media/{id}Карточка: Фото и документы оборудования GET/equipment/{equipment_id}/media/{id}/downloadЗащищённое скачивание содержимого POST/equipment/{equipment_id}/media/{id}/deleteУдалить файл оборудования GET/equipment-modelsСписок: Модели оборудования POST/equipment-modelsСоздать модель оборудования GET/equipment-models/{id}Карточка: Модели оборудования POST/equipment-models/{id}/updateИзменить модель оборудования GET/equipment/{id}/usageКарточка: Показания наработки POST/equipment/{id}/usageРегистрация показания GET/leadsСписок: Обращения POST/leadsСоздать обращение GET/leads/{id}Карточка: Обращения POST/leads/{id}/updateИзменить обращение POST/leads/{id}/statusДопустимое изменение статуса POST/leads/{id}/assignНазначение ответственного POST/leads/{id}/convertКонвертация в клиента с явным выбором соответствия GET/maintenance-schedules/{schedule_id}/checklist-resultsСписок: Выполнение чек-листа ТО POST/maintenance-schedules/{schedule_id}/checklist-resultsДобавить ручной пункт чек-листа ТО POST/maintenance-schedules/{schedule_id}/checklist-results/initializeПодготовка сохранённого чек-листа заявки POST/maintenance-schedules/{schedule_id}/checklist-results/{id}/updateИзменить пункт чек-листа ТО GET/maintenance-plansСписок: Индивидуальные планы оборудования POST/maintenance-plansСоздать план ТО GET/maintenance-plans/{id}Карточка: Индивидуальные планы оборудования POST/maintenance-plans/{id}/updateИзменить план ТО POST/maintenance-plans/{id}/pauseПауза плана POST/maintenance-plans/{id}/resumeВозобновление POST/maintenance-plans/{id}/endЗавершение POST/maintenance-plans/{id}/generateСоздание заявки текущего допустимого цикла GET/maintenance-regulationsСписок: Общие регламенты обслуживания POST/maintenance-regulationsСоздать регламент обслуживания GET/maintenance-regulations/{id}Карточка: Общие регламенты обслуживания POST/maintenance-regulations/{id}/updateИзменить регламент обслуживания POST/maintenance-regulations/{id}/pauseПриостановка действия регламента POST/maintenance-regulations/{id}/resumeВозобновление действия регламента POST/maintenance-regulations/{id}/endЗавершение регламента POST/maintenance-regulations/{id}/syncСогласование состава оборудования и индивидуальных планов GET/maintenance-reports/calendarПрогноз и существующие работы за ограниченный период GET/maintenance-reports/plan-factПлан/факт и исполнение ППР GET/maintenance-reports/partsПрогноз потребности в расходниках GET/maintenance-reports/reliabilityОтказы, простои и показатели восстановления GET/maintenance-scenariosСписок: Шаблоны работ и сценарии ТО POST/maintenance-scenariosСоздать шаблон ТО GET/maintenance-scenarios/{id}Карточка: Шаблоны работ и сценарии ТО POST/maintenance-scenarios/importПроверяемый импорт шаблона POST/maintenance-scenarios/{id}/updateИзменить шаблон ТО POST/maintenance-scenarios/{id}/archiveАрхивировать шаблон ТО POST/maintenance-scenarios/{id}/simulateПроверка расчётных правил без изменения оборудования GET/maintenance-scenarios/{id}/exportЭкспорт схемы шаблона GET/maintenance-schedulesСписок: Заявки ТО POST/maintenance-schedulesСоздать заявку ТО GET/maintenance-schedules/{id}Карточка: Заявки ТО POST/maintenance-schedules/plan-visitОбщий акт ТО и необязательный выезд для выбранного парка/заявок POST/maintenance-schedules/{id}/create-actСоздание или получение связанного акта ТО POST/maintenance-schedules/{id}/updateИзменить заявку ТО POST/maintenance-schedules/{id}/startНачало выполнения POST/maintenance-schedules/{id}/rescheduleИзменение даты и ответственного POST/maintenance-schedules/{id}/executionСохранение прогресса, результата и типизированных полей POST/maintenance-schedules/{id}/completeЗавершение только этой заявки POST/maintenance-schedules/{id}/cancelОтмена заявки с причиной POST/maintenance-schedules/{id}/reopenВозврат заявки в работу GET/reference/markupsСписок: Наценки POST/reference/markupsСоздать наценку GET/reference/markups/{id}Карточка: Наценки POST/reference/markups/{id}/updateИзменить наценку POST/reference/markups/{id}/deleteУдалить наценку GET/reference/money-typesСписок: Статьи движения денег POST/reference/money-typesСоздать статью движения денег GET/reference/money-types/{id}Карточка: Статьи движения денег POST/reference/money-types/{id}/updateИзменить статью движения денег POST/reference/money-types/{id}/deleteУдалить статью движения денег POST/operationsСоздать работу GET/operationsСписок: Справочник работ POST/operations/{id}/updateИзменить работу POST/operations/{id}/archiveАрхивировать работу POST/operations/{id}/restoreВосстановить работу GET/operations/{id}Карточка: Справочник работ GET/reference/placesСписок: Места хранения POST/reference/placesСоздать место хранения GET/reference/places/{id}Карточка: Места хранения POST/reference/places/{id}/updateИзменить место хранения POST/reference/places/{id}/deleteУдалить место хранения GET/reference/product-typesСписок: Типы товаров POST/reference/product-typesСоздать тип товара GET/reference/product-types/{id}Карточка: Типы товаров POST/reference/product-types/{id}/updateИзменить тип товара POST/reference/product-types/{id}/deleteУдалить тип товара POST/productsСоздать товар GET/productsСписок: Товары и запчасти POST/products/{id}/updateИзменить товар POST/products/{id}/archiveАрхивировать товар POST/products/{id}/restoreВосстановить товар GET/products/{id}Карточка: Товары и запчасти GET/reference/propertiesСписок: Определения свойств товаров POST/reference/propertiesСоздать свойство товара GET/reference/properties/{id}Карточка: Определения свойств товаров POST/reference/properties/{id}/updateИзменить свойство товара POST/reference/properties/{id}/deleteУдалить свойство товара GET/referenceКаталог доступных справочников и перечислений GET/reference/enums/{name}Карточка: Системные перечисления и каталог справочников GET/reference/rolesСписок: Системные перечисления и каталог справочников GET/maintenance-scenarios/{parentId}/checklist-itemsСписок: Пункты шаблона ТО POST/maintenance-scenarios/{parentId}/checklist-itemsСоздать пункт шаблона ТО GET/maintenance-scenarios/{parentId}/checklist-items/{id}Карточка: Пункты шаблона ТО POST/maintenance-scenarios/{parentId}/checklist-items/{id}/updateИзменить пункт шаблона ТО POST/maintenance-scenarios/{parentId}/checklist-items/{id}/deleteУдалить пункт шаблона ТО GET/service-contracts/{contract_id}/chargesСписок: Начисления по договорам GET/service-contracts/{contract_id}/charges/{id}Карточка: Начисления по договорам GET/service-contractsСписок: Договоры обслуживания POST/service-contractsСоздать договор обслуживания GET/service-contracts/{id}Карточка: Договоры обслуживания POST/service-contracts/{id}/updateИзменить договор обслуживания POST/service-contracts/{id}/equipmentУстановка согласованного состава оборудования GET/service-contracts/{id}/equipmentСписок: Договоры обслуживания POST/service-contracts/{id}/statusИзменение состояния договора GET/service-kits/{kit_id}/itemsСписок: Позиции комплекта POST/service-kits/{kit_id}/itemsСоздать позицию комплекта GET/service-kits/{kit_id}/items/{id}Карточка: Позиции комплекта POST/service-kits/{kit_id}/items/{id}/updateИзменить позицию комплекта POST/service-kits/{kit_id}/items/{id}/deleteУдалить позицию комплекта GET/service-kitsСписок: Комплекты работ и товаров POST/service-kitsСоздать комплект работ и товаров GET/service-kits/{id}Карточка: Комплекты работ и товаров POST/service-kits/{id}/updateИзменить комплект работ и товаров POST/service-kits/{id}/archiveАрхивировать комплект работ и товаров GET/reference/statusesСписок: Статусы актов и переходы POST/reference/statusesСоздать статус акта GET/reference/statuses/{id}Карточка: Статусы актов и переходы POST/reference/statuses/{id}/updateИзменить статус акта POST/reference/statuses/{id}/transitionsНастройка доступных следующих статусов POST/reference/statuses/{id}/accessНастройка допуска ролей/сотрудников POST/reference/statuses/{id}/deleteУдалить статус акта GET/stocks/{stock_id}/levelsСписок: Остатки и доступность товаров GET/stocks/{stock_id}/levels/{product_id}Карточка: Остатки и доступность товаров GET/stocksСписок: Склады GET/stocks/{id}Карточка: Склады GET/reference/usage-unitsСписок: Единицы наработки POST/reference/usage-unitsСоздать единицу наработки GET/reference/usage-units/{id}Карточка: Единицы наработки POST/reference/usage-units/{id}/updateИзменить единицу наработки POST/reference/usage-units/{id}/deleteУдалить единицу наработки GET/users/{user_id}/availabilityКарточка: Доступность сотрудников POST/users/{user_id}/availabilityСохранение явного набора недельных окон POST/users/{user_id}/days-offСоздать запись: Доступность сотрудников POST/users/{user_id}/days-off/{id}/deleteУдалить запись: Доступность сотрудников GET/usersСписок: Сотрудники для назначения GET/users/{id}Карточка: Сотрудники для назначения GET/reference/vendorsСписок: Производители POST/reference/vendorsСоздать производителя GET/reference/vendors/{id}Карточка: Производители POST/reference/vendors/{id}/updateИзменить производителя POST/reference/vendors/{id}/deleteУдалить производителя GET/visits/{visit_id}/eventsСписок: События выполнения выезда POST/visits/{visit_id}/en-routeСотрудник выехал POST/visits/{visit_id}/arriveСотрудник прибыл POST/visits/{visit_id}/completeЗавершение по допустимому закрывающему статусу акта POST/visits/{visit_id}/reopenОткрытие акта и связанного выполнения по допустимому статусу GET/visits/{visit_id}/mediaСписок: Фотографии и документы выезда POST/visits/{visit_id}/mediaЗагрузка multipart/form-data GET/visits/{visit_id}/media/{id}Карточка: Фотографии и документы выезда GET/visits/{visit_id}/media/{id}/downloadЗащищённое получение содержимого POST/visits/{visit_id}/media/{id}/deleteУдалить вложение выезда POST/visit-route-plansСоздать расчёт маршрута GET/visit-route-plans/{id}Карточка: Расчёт и применение маршрута выездов POST/visit-route-plans/{id}/cancelОстановка незавершённого расчёта POST/visit-route-plans/{id}/advanceПродолжение ограниченного шага расчёта POST/visit-route-plans/{id}/applyПрименение актуального предложения GET/visitsСписок: Выезды POST/visitsСоздать выезд GET/visits/{id}Карточка: Выезды POST/visits/{id}/updateИзменить выезд POST/visits/{id}/scheduleНазначение или перенос времени и бригады POST/visits/{id}/assignИзменение состава бригады POST/visits/{id}/unscheduleСнятие назначения с сохранением акта и заявок POST/visits/{id}/deleteУдалить выезд GET/workshopsСписок: Мастерские POST/workshopsСоздать мастерскую GET/workshops/{id}Карточка: Мастерские POST/workshops/{id}/updateИзменить мастерскую