Swagger и документация

Документация для интеграции по API с kamaz.tech

PROD окружение

https://services.sc.kamaz.tech | IP: 89.169.141.16

Для доступа к ресурсам требуется аутентификация

Пройдите модерацию в личном кабинете. В профиле должна появиться надпись "Профиль подтвержден".

Основные ресурсы

Swagger

Личный кабинет

Если у вас есть вопросы напишите в поддержку support@kamaz.tech

200

Код ответа в случае успеха

422

Код ответа в случае некорректно переданных данных в запросе

404

Код ответа в случае, если ресурс не найден

403

Код ответа в случае, если пользователь не уполномочен на взаимодействие с сервисом

Общие правила ответа сервера для всех запросов

Метод служит для получения access_token, который используется во всех последующих методах

Для авторизации вы можете использовать учетные данные из вашего профиля:

POST https://{api_address}/auth/token

Аутентификация

Пример запроса: параметры прописываются в body

curl -X 'POST' \
  'https://services.npe.sc.kamaz.tech/auth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username={почта УЗ из Кора}&password={пароль к этой УЗ}

Пример ответа 200

{
   "access_token": "eyJhbGciOiJSUzI1NiIsInR",
   "refresh_token": "eyJhbGciOiJSUzI1NiIsIn"
}

В заголовке x-refresh-token передается полученный рефреш-токен, в ответе возвращается новый токен доступа

Обновление можно делать неограниченное количество раз пока действует рефреш-токен:

POST https://{api_address}/users_id/auth/v2/refresh

Обновление токена доступа

Пример ответа 200

{
   "access_token": "eyJhbGciOiJSUzI1NiIsInR",
   "refresh_token": "eyJhbGciOiJSUzI1NiIsIn"
}

Пример запроса: параметры прописываются в body

curl -X 'POST' \
  'https://services.npe.sc.kamaz.tech/auth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username={почта УЗ из Кора}&password={пароль к этой УЗ}

Метод принимает на вход информацию о текущем состоянии загрузки сервисного центра.
На вход принимаются либо посты, либо сотрудники, либо и то и другое.

Отправлять данные раз в сутки
Вперед минимум на 1 неделю

Рекомендуем 1 месяц

POST https://{api_address}/v1/services/load

Доступность сервисного центра

workers и posts приравниваются друг к другу, их часы складываются, разница только в названии

1

Идентификатор Сервисного центра устанавливается благодаря токену доступа, отправляемому в запросе. Таким образом понимается к какому сервисному центру принадлежит нагрузка.
2

В таблице сервисных центров хранится информация о расписании работы сервиса по дням (schedule). Если сервис не работает в переданный день, то загруженность на этот день не будет сохранена.
3

Из данных переданным в запросе на основе free_hours и total_hours вычисляется количества загруженных часов путем вычитания free_hours из total_hours. Таким образом, получается количество часов, которое сервис занят в этот день. Это количество часов делится на интервал времени записи по умолчанию (default_interval_min), и получается количество занятых слотов, которое надо создать для сервиса.
4

Если количество часов не делится без остатка на интервал записи по умолчанию, то результат деления округляется в большую сторону.
5

Перед созданием новых занятых слотов все старые занятые слоты удаляются на этот день для сервисного центра.
6

Если количество слотов, которые требуется создать, превышет максимальное время работы сервиса в указанный день (на основе данных таблицы schedule), то будет создано максимально допустимое количество слотов, остальные будут отброшены.

Типы полей

{
  "posts": [
    {
      "name": string,
      "date": string($date),
      "free_hours": integer,
      "total_hours": integer
    }
  ],
  "workers": [
    {
      "name": string,
      "date": string($date),
      "free_hours": integer,
      "total_hours": integer
    }
  ]
}

Пример запроса

{
  "posts": [
    {
      "name": "1",
      "date": "2022-06-11",
      "free_hours": 20,
      "total_hours": 30
    }
  ],
  "workers": [
    {
      "name": "1",
      "date": "2022-06-11",
      "free_hours": 20,
      "total_hours": 30
    }
  ]
}

Пример ответа 200

[
  {
    "date": "2025-02-28",
    "total_hours": 0,
    "loading": 0,
    "count": 0,
    "working_count": 0,
    "slot_size_min": 0,
    "can_accept_car": 0,
    "free_hours": 0
  }
]

Расшифровка ответа

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

Метод возвращает список заявок на ремонт предназначенных сервисному центру

GET https://{api_address}/v1/services/orders?new_order=false

Получение списка заявок

Пример ответа 200

{
  "ok": true,
  "data": {
    "items": [
      {
        "order_id": "string",
        "external_order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "arrival_date": "2025-07-10",
        "VIN": "string",
        "tax_num": 0,
        "preferred_time_in": "2025-07-10T18:53:33.580Z",
        "preferred_time_out": "2025-07-10T18:53:33.580Z",
        "state_number": "string",
        "handling_reason": "string",
        "dealer_comment": "string",
        "org_name": "string",
        "contact_phone": "string",
        "contact_name": "string",
        "contact_email": "string",
        "driver_phone": "string",
        "driver_name": "string",
        "status": "unknown",
        "repair_type": [
          "routine_maintenance"
        ],
        "odd": 0,
        "availability_trailer": true
      }
    ]
  },
  "errors": [
    "string"
  ],
  "query": {
    "additionalProp1": {}
  }
}

Расшифровка ответа

Параметр	Описание	Тип
order_id*	ID заявки	uuid
arrival_date*	Дата записи	string($date)
VIN	VIN номер шасси	string
tax_num	ИНН организации	integer
preferred_time_in	Время и дата начала желаемого интервала на запись (формат UTC)	string($date-time)
state_number	Гос. номер. Без пробелов	string
handling_reason	Причина обращения	string
contact_phone	Номер телефона для контакта. Без пробелов	string
contact_name	ФИО контактного лица	string
contact_email	E-mail адрес контактного лица	string
org_name	Организация	string
driver_phone	Номер телефона водителя. Без пробелов	string
driver_name	ФИО водителя	string
repair_type*	Вид ремонта: - Регламентное ТО: “routine_maintenance” - Ремонт ходовой, подвески, моста, тормозной системы: “repair_chassis_suspension_bridge_brake_sys” - Ремонт ДВС, КПП: “repair_ice_gearbox” - Ремонт рамы, сцепного устройства: “repair_frame_coupling_device” - Ремонт электрооборудования: “repair_electrical_equipment”	List(string)
odd	Пробег	integer
availability_trailer	Наличие прицепа	bool
status	"unknown" - Неопределено “head_approval" - "Отправлена в сервис" "service_approval" - "Согласование сервиса" "recorded_in_service" -"Записан в сервис" "under_repaired" -"В ремонте" "ready_to_issue" - "Готов к Выдаче" "issued" - "Выдан"	string
dealer_comment	Комментарий дилера к заявке	string

Данный метод принимает на вход информацию об изменении статуса заявки

POST https://{api_address}/v1/services/orders

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

Пример запроса

{
  "order_id": "string",
  "order_status": "unknown",
  "order_comment": "string",
  "dealer_comment": "string",
  "preferred_time_in": "2025-07-10T18:56:33.751Z",
  "date_time_issue": "2025-07-10T18:56:33.751Z",
  "external_order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Расшифровка ответа

Параметр	Описание	Тип
order_id*	ID заявки	uuid
arrival_date*	Статус заявки. Возможные варианты: - ready_to_work - заявка получена сервисом - автоматически отправляется, когда данные по заявке пришли в 1С - rejected - заявка отклонена - отправляется на любом статусе, если заявка по каким-либо причинам отклоняется - recorded_in_service - “Записан в сервис” - вы подтвердили заявку, у автомобиля появилась дата записи на сервис - under_repaired - “В ремонте” - период начиная с даты открытия заказ-наряда - ready_to_issue - “Готов к выдаче” - вы завершили все работы по автомобилю и он готов к выдаче - issued - “Выдан” - заказчик забрал автомобиль из сервиса (дата закрытия заказ-наряда)	string
order_comment	Комментарий клиента к заявке	string
dealer_comment*	Комментарий дилера к заявке	string
preferred_time_in	Время и дата реальной записи на приемку - начало (формат UTC)	string($date-time)
date_time_issue	Когда сервис планово/фактически готов выдать машину (формат UTC)	string($date-time)

Пример ответа 200

{
    "ok": true,
    "data": {
        "order_id": "5825ff40-c901-4603-8774-1cd9465023d3",
        "arrival_date": "2022-07-06",
        "VIN": "XTC934293859248592835",
        "tax_num": null,
        "preferred_time_in": "2022-05-21T12:00:00Z",
        "preferred_time_out": "2022-05-21T15:00:00Z",
        "state_number": "X279YP29",
        "handling_reason": "Вырвало колесо",
        "org_name": "ООО ремонт и сервис",
        "contact_phone": "+79817774545",
        "contact_name": "Андрей",
        "contact_email": "Мое@мыло.ру",
        "driver_phone": "+79817774546",
        "driver_name": “Анатолий”,
        "repair_type": [
            "unknown"
        ],
        "odd": null
    },
    "errors": [],
    "query": {}

GET https:// /skenters/{skenters_id}

Получение СЦ по ИД

Ограничения передачи расписания занятости СЦ

В СЦ на конкретную дату и время можно записаться только, если он (сервис) работает в это время. Режим работы сервиса можно посмотреть в деталке сервиса по следующему запросу:

Режим работы находится в поле schedule, например:

"schedule": {
        "0": {
          "work_interval": {
            "start": "08:00:00",
            "end": "17:00:00"
          },
          "break_interval": null
        },
        "1": {
          "work_interval": {
            "start": "08:00:00",
            "end": "17:00:00"
          },
          "break_interval": null
        },
        "2": {
          "work_interval": {
            "start": "08:00:00",
            "end": "17:00:00"
          },
          "break_interval": null
        },
        "3": {
          "work_interval": {
            "start": "08:00:00",
            "end": "17:00:00"
          },
          "break_interval": null
        },
        "4": {
          "work_interval": {
            "start": "08:00:00",
            "end": "17:00:00"
          },
          "break_interval": null
        },
        "5": null,
        "6": null
      }

Сервис из примера работает с ПН (ключ дня 0) по ПТ (ключ дня 4) с 8 утра до 17 вечера по часовому поясу Сервиса. Часовой пояс сервиса находится в том же запросе по ключу time_shift, например для этого сервиса часовой пояс - Москва:

"time_shift": "Europe/Moscow"

А вот этот сервис не передал данные о своем режиме работы, поэтому показывается, что он не работает.

"schedule": {
        "0": null,
        "1": null,
        "2": null,
        "3": null,
        "4": null,
        "5": null,
        "6": null
    }

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

PUT https:// /skenters/{skenters_id}

Обновить данные о СЦ

Приведенная ручка защищена авторизацией на предмет правомерности доступа к редактируемому СЦ. Таким образом, только администратор или лцио, за которым таблицой правил закреплено право доступа к конкретному СЦ, может редактировать информацию о нём.

Ручка редактирования изменяет сразу все поля СЦ, поэтому передавать надо все значения как есть из ручки детализации.

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

{
  "polygons": null,
  "center": [
    12.345678,
    98.765432
  ],
  "radius_m": 130,
  "created_at": "2025-04-16T16:08:39.905462",   
  "updated_at": "2025-07-23T09:21:45.186659",   
  "name": "Случайный сервис для примера",
  "address": "Адрес случайного сервиса для примера",
  "type": "Дилер по реализации запасных частей и оказанию услуг сервиса",
  "phone": "(1234) 567-890, 123-456",
  "schedule": { # тут менять
    "0": {
      "work_interval": {
        "start": "08:00:00",
        "end": "17:00:00"
      },
      "break_interval": null
    },
    "1": {
      "work_interval": {
        "start": "08:00:00",
        "end": "17:00:00"
      },
      "break_interval": null
    },
    "2": {
      "work_interval": {
        "start": "08:00:00",
        "end": "17:00:00"
      },
      "break_interval": null
    },
    "3": null, # а в ЧТ больше не работает
    "4": {
      "work_interval": {
        "start": "08:00:00",
        "end": "17:00:00"
      },
      "break_interval": null
    },
    "5": {
      "work_interval": {    # например так, теперь сервис работаает и в СБ
        "start": "08:00:00",
        "end": "17:00:00"
      },
      "break_interval": null
    },,
    "6": null
  },
  "is_connected": false,
  "posts_amount": 1,
  "free_posts_amount": 1, 
  "status": "new", 
  "time_shift": "Asia/Vladivostok", # а тут менять в таком же формате, теперь сервис работает по часовому поясу Владивостока
  "default_interval_min": 180,
  "email": null,
  "manager": "service@example.net; "
}

После изменения значений в интересующих полях, копируем всю структуру даных и вставляем в полезную нагрузку запроса на редактирование сервиса по его идентификатору. Лишние поля будут отброшены автоматически и не учтены при редактировании.