Bitcop Web API

API интерфейс предназначен для разработчиков и используется для интеграции ваших приложений с системой Bitcop. Если у вас имеются вопросы по работе API или требуются дополнительные возможности интеграции, свяжитесь с нами по адресу: support@bitcop.ru

API работает по протоколу HTTP и представляет собой набор методов, с помощью которых совершаются запросы и возвращаются ответы для каждой операции. Все ответы приходят в виде JSON структур.

Начало работы с API

Чтобы работать с API необходимо:

  1. Получить ключ API (apikey) в личном кабинете администратора в разделе [Настройки] - [Токены доступа] - [API-ключ].
  2. Использовать данный ключ в каждом запросе к API в параметрах URL.

Формат запроса

URL любого API-запроса составляется следующим образом:

https://<имя_вашего_аккаунта>.bitcop.ru:4443/api/v1/
Пример:
https://demo.bitcop.ru:4443/api/v1/employees?&apikey=cb3436c284d34d748212bd92842f813d

Список методов API

API-методОписание
GET /employeesПолучение списка сотрудников
GET /workperiodsОпределение старта/окончания работ по сотруднику
GET /activityПолучение статистики работы по сотруднику
GET /productivityПолучение продуктивности работы по сотруднику
GET /screenshotsПолучение скриншотов
Задачи
GET /tasksПолучение списка задач
GET /tasks/activityПолучение активности работы сотрудников по задачам
POST /tasksСоздать задачу
POST /tasks/{id}Создать подзадачу
PUT /tasks/{id}Редактировать задачу
GET /taskgroups/{id}/tasksПолучение списка задач из определенной группы
POST /taskgroups/{id}/tasksСоздать задачу в группе
POST /tasks/{id}/archiveАрхивировать задачу
POST /tasks/{id}/unarchiveРазархивировать задачу
Группы задач
GET /taskgroupsПолучение списка групп задач
POST /taskgroupsСоздать группу задач
POST /taskgroups/{id}Создать подгруппу задач
POST /taskgroups/{id}/archiveАрхивировать группу задач
POST /taskgroups/{id}/unarchiveРазархивировать группу задач

Получение списка сотрудников

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

GET /employees
Входные параметры:
ПараметрОбязательныйТипОписание
activeНетBooleanСтатус сотрудника (активный/неактивный)
Пример запроса:
GET /api/v1/employees
Структура ответа:
{
  "status": "success",
  "items": [
    {
      "id": 6,
      "firstName": "Татьяна",
      "lastName": "Смирнова",
      "email": "tsmirnova@bitcop.local",
      "active": true
    },
    {
      "id": 7,
      "firstName": "Алексей",
      "lastName": "Королев",
      "email": "akorolev@bitcop.local",
      "active": true
    },
]
Описание полей ответа:
ПараметрОписание
idИдентификатор сотрудника
firstNameИмя сотрудника
lastNameФамилия сотрудника
emailАдрес эл. почты сотрудника
activeСтатус сотрудника (активный/неактивный)

Определение старта/окончания работ по сотруднику

Данный метод позволяет получить начало и окончание работы по каждому сотруднику

(вариант 1)
GET /workperiods
Входные параметры:
ПараметрОбязательныйОписание
dateДаДата, за которую необходимо получить данные. Задается в формате ISO 8601. Например, 20210430
employeesНетИдентификаторы сотрудников через запятую. Если параметр не указан, то запрос будет выполнен по всем сотрудникам.
Пример запроса:
GET /api/v1/workperiods?date=20210430&employees=6,7
Структура ответа:
{
  "status": "success",
  "items": [
    {
      "id": 6,
      "name": "Смирнова Татьяна",
      "date": "20210430",
      "begin": 31834,
      "end": 65263
    },
    {
      "id": 7,
      "name": "Королев Алексей",
      "date": "20210430",
      "begin": 33058,
      "end": 64963
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор сотрудника
nameФИО сотрудника
dateДата. Задается в виде количества секунд, прошедших с 01.01.1970 (Unix-time)
beginВремя начала работы равное кол-ву секунд, прошедших после полуночи (00:00:00)
endВремя окончания работы равное кол-ву секунд, прошедших после полуночи (00:00:00)
(вариант 2)
GET /workperiods2
Входные параметры:
ПараметрОбязательныйОписание
beginДаДата начала работы. Задается в формате ISO 8601. Например, 20170920T070000 - 20 сентября 2017 07:00:00
endДаДата окончания работы. Задается в формате ISO 8601. Например, 20170921 - 21 сентября 2017 00:00:00
employeesНетИдентификаторы сотрудников через запятую. Если параметр не указан, то запрос будет выполнен по всем сотрудникам.
Пример запроса:
GET /api/v1/workperiods2?begin=20170920T070000&end=20170921&employees=6,7
Структура ответа:
{
  "status": "success",
  "items": [
    {
      "id": 6,
      "name": "Смирнова Татьяна",
      "begin": "20170920T085835",
      "end": "20170920T180244"
    },
    {
      "id": 7,
      "name": "Королев Алексей",
      "begin": "20170920T090324",
      "end": "20170920T175346"
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор сотрудника
nameФИО сотрудника
beginДата начала работы. Задается в формате ISO 8601. Например, 20170920T070000 - 20 сентября 2017 07:00:00
endДата окончания работы. Задается в формате ISO 8601. Например, 20170921 - 21 сентября 2017 00:00:00

Получение статистики работы по сотруднику

Данный метод позволяет получить статистику работы по сотруднику за определенный период

GET /activity
Входные параметры:
ПараметрОбязательныйОписание
beginДаДата начала работы. Задается в формате ISO 8601. Например, 20170920T070000 - 20 сентября 2017 07:00:00
endДаДата окончания выборки. Задается в формате ISO 8601. Например, 20170921 - 21 сентября 2017 00:00:00
employeesНетИдентификаторы сотрудников через запятую. Если параметр не указан, то запрос будет выполнен по всем сотрудникам.
Пример запроса:
GET /api/v1/activity?begin=20170920T070000&end=20170921&employees=6,7
Структура ответа:
{
  "status": "success",
  "items": [
    {
      "id": 6,
      "name": "Смирнова Татьяна", 
      "totalTime": 817983,
      "activeTime": 416221,
      "downTime": 401762,
      "lateTime": 2784,
      "lateCount": 4,
      "earlyEndTime": 3425,
      "earlyEndCount": 5,
      "overTime": 0,
      "absenteism": 2,
      "workDayCount": 20,
      "scheduleDayCount": 22
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор сотрудника
nameФИО сотрудника
totalTimeОбщее время работы
activeTimeВремя активной работы
downTimeВремя простоя
lateTimeВремя опозданий в секундах
lateCountКол-во опозданий
earlyEndTimeКол-во ранних уходов
earlyEndCountВремя ранних уходов в секундах
overTimeСверхурочное время
absenteismКол-во прогулов
workDayCountКол-во отработанных дней
scheduleDayCountКол-во рабочих дней по расписанию

Получение продуктивности работы по сотруднику

Данный метод позволяет получить статистику продуктивности по сотруднику за определенный период

GET /productivity
Входные параметры:
ПараметрОбязательныйОписание
beginДаДата начала работы. Задается в формате ISO 8601. Например, 20170920T070000
endДаДата окончания работы. Задается в формате ISO 8601. Например, 20170921T000000 или 20170921
employeesНетИдентификаторы сотрудников через запятую. Если параметр не указан, то запрос будет выполнен по всем сотрудникам.
Пример запроса:
GET /api/v1/productivity?begin=20170920T070000&end=20170921&employees=6,7
Структура ответа:
{
  "status": "success",
  "items": [
    {
      "id": 6,
      "name": "Смирнова Татьяна", 
      "totalTime": 139446,
      "productiveTime": 59796,
      "unproductiveTime": 603,
      "neutralTime": 79047
    },
    {
      "id": 7,
      "name": "Королев Алексей", 
      "totalTime": 313521,
      "productiveTime": 117551,
      "unproductiveTime": 22405,
      "neutralTime": 173565
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор сотрудника
nameФИО сотрудника
totalTimeОбщее время работы
productiveTimeВремя продуктивной работы
unproductiveTimeВремя непродуктивной работы
neutralTimeВремя нейтральной работы

Получение скриншотов

Данный метод позволяет получить список скриншотов.

GET /screenshots
Входные параметры:
ПараметрОбязательныйТипОписание
beginДаDateДата начала выборки. Задается в формате ISO 8601. Например, 20170920T070000 - 20 сентября 2017 07:00:00
endДаDateДата окончания выборки. Задается в формате ISO 8601. Например, 20170921 - 21 сентября 2017 00:00:00
usersНетint[]Идентификаторы сотрудников через запятую. Если параметр не указан, то запрос будет выполнен по всем сотрудникам.
tasksНетint[]Идентификаторы задач через запятую. Если параметр не указан, то запрос будет выполнен по всем задачам.
Пример запроса:
GET /api/v1/screenshots?begin=20170920T070000&end=20170921&users=6,7&tasks=1,2
Структура ответа:
{
{
  "status": "success",
  "data": {
    "screenshots": [
      {
        "createdOn": "20210317T094250",
        "user": {
          "id": 6,
          "name": "Смирнова Татьяна"
        },
        "program": "Microsoft Word",
        "task": {
          "id": 1,
          "name": "Задача в проекте Redmine 4.1.1"
        },
        "title": "Договор на выполнение работ - Microsoft Word",
        "url": "https://url"
      }
    ]
}
Описание полей ответа:
ПараметрОписание
createdOnВремя создания скриншота
userИмя сотрудника
programИнформация о программе
taskИнформация о задаче
titleЗаголовок окна программы
urlСсылка на скриншот

Задачи

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

Данный метод позволяет получить список задач.

GET /tasks
Входные параметры:
ПараметрОбязательныйТипОписание
archivedНетBooleanПоказать только архивные или не архивные задачи. Если параметр не указан, будут показаны все задачи.
taskNumberНетstringПоказать задачу только с указанным номером.
Пример запроса:
GET /api/v1/tasks
Структура ответа:
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Задача 1",
      "parent": null,
      "group": {
        "id": 1,
        "name": "Группа 1"
      },
      "taskNumber": null,
      "archived": false,
      "changedOn": "20171124T110630"
    },
    {
      "id": 2,
      "name": "Задача 2",
      "parent": {
        "id": 1,
        "name": "Задача 1"
      },
      "group": {
        "id": 1,
        "name": "Группа 1"
      },
      "taskNumber": null,
      "archived": false,
      "changedOn": "20171125T163255"
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание задачи
parentРодительская задача
groupГруппа, в которой находится задача
taskNumberНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная задача
changedOnДата создания (изменения) задачи

Получение активности работы сотрудников по задачам

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

GET /tasks/activity
Входные параметры:
ПараметрОбязательныйТипОписание
beginДаDateДата начала работы. Задается в формате ISO 8601. Например, 20170920T070000 - 20 сентября 2017 07:00:00
endДаDateДата окончания выборки. Задается в формате ISO 8601. Например, 20170921 - 21 сентября 2017 00:00:00
groupДаstring group=user - для получения трудозатрат с группировкой данных по сотрудникам,
group=task - для получения трудозатрат с группировкой данных по задачам
usersНетint[]Идентификаторы сотрудников через запятую. Если параметр не указан, то запрос будет выполнен по всем сотрудникам.
tasksНетint[]Идентификаторы задач через запятую. Если параметр не указан, то запрос будет выполнен по всем задачам.
Пример запроса (группировка по сотрудникам):
GET /api/v1/tasks/activity?begin=20170920T070000&end=20170921&group=user
Структура ответа:
{
  "status": "success",
  "data": [
    {
      "user": {
        "id": 6,
        "name": "Смирнова Татьяна"
      },
      "tasks": [
        {
          "task": {
            "id": 2,
            "name": "Задача 2"
          },
          "periods": [
            [
              "20180418T091122",
              "20180418T130330"
            ],
            [
              "20180418T140532",
              "20180418T180234"
            ]
          ],
          "totalTime": 28150
        }
      ],
      "totalTime": 28150
    }
  ]
}
Пример запроса (группировка по задачам):
GET /api/v1/tasks/activity?begin=20170920T070000&end=20170921&group=task
Структура ответа:
{
  "status": "success",
  "data": [
    {
      "task": {
        "id": 2,
        "name": "Задача 2"
      },
      "users": [
        {
          "user": {
            "id": 6,
            "name": "Смирнова Татьяна"
          },
          "totalTime": 28150
        }
      ],
      "totalTime": 28150
    }
  ]
}

Создать задачу

Данный метод позволяет создать новую задачу.

POST /tasks
JSON:
{
  "name":"Название задачи"
}
Входные параметры:
ПараметрОбязательныйТипОписание
nameДаstringНазвание задачи
taskNumberНетstringНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
membersНетstringУчастники. Идентификаторы сотрудников через запятую. Чтобы назначить задачу сразу на всех сотрудников, укажите -1
Пример запроса:
POST /api/v1/tasks
JSON:
{
  "name":"Задача 1",
  "members":"1,2,3"
}
Структура ответа:
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Задача 1",
    "parent": null,
    "group": null,
    "taskNumber": null,
    "archived": false,
    "changedOn": "20171124T110630"
  }
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание задачи
parentРодительская задача
groupГруппа, в которой находится задача
taskNumberНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная задача
changedOnДата создания (изменения) задачи

Создать подзадачу

Данный метод позволяет создать подзадачу.

POST /tasks/{id}
JSON:
{
  "name":"Название подзадачи"
}
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор родительской задачи
nameДаstringНазвание задачи
taskNumberНетstringНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
Пример запроса:
POST /api/v1/tasks/1
JSON:
{
  "name":"Задача 2"
}
Структура ответа:
{
  "status": "success",
  "data": {
    "id": 2,
    "name": "Задача 2",
    "parent": {
      "id": 1,
      "name": "Задача 1"
    },
    "group": null,
    "taskNumber": null,
    "archived": false,
    "changedOn": "20171125T163255"
  }
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание задачи
parentРодительская задача
groupГруппа, в которой находится задача
taskNumberНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная задача
changedOnДата создания (изменения) задачи

Редактировать задачу

Данный метод позволяет редактировать задачу.

PUT /tasks/{id}
JSON:
{
  "name":"Новое название задачи"
}
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор задачи
nameНетstringНазвание задачи
taskNumberНетstringНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
membersНетstringУчастники. Идентификаторы сотрудников через запятую. Чтобы назначить задачу сразу на всех сотрудников, укажите -1
Данный метод изменяет только те параметры, которые переданы запросе.
Пример запроса:
PUT /api/v1/tasks/1
JSON:
{
  "name":"Новое название задачи"
}
Структура ответа:
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Новое название задачи",
    "parent": null,
    "group": null,
    "taskNumber": null,
    "archived": false,
    "changedOn": "20171125T163255"
  }
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание задачи
parentРодительская задача
groupГруппа, в которой находится задача
taskNumberНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная задача
changedOnДата создания (изменения) задачи

Получение списка задач из группы

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

GET /taskgroups/{id}/tasks
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор группы задач
archivedНетBooleanПоказать только архивные или не архивные задачи. Если параметр не указан, будут показаны все задачи.
taskNumberНетstringПоказать задачу только с указанным номером.
Пример запроса:
GET /api/v1/taskgroups/2/tasks
Структура ответа:
{
  "status": "success",
  "data": [
    {
      "id": 3,
      "name": "Задача 3",
      "parent": null,
      "group": {
        "id": 2,
        "name": "Группа 2"
      },
      "taskNumber": null,
      "archived": false,
      "changedOn": "20171126T162353"
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание задачи
parentРодительская задача
groupГруппа, в которой находится задача
taskNumberНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная задача
changedOnДата создания (изменения) задачи

Создать задачу в группе

Данный метод позволяет создать новую задачу в определенной группе.

POST /taskgroups/{id}/tasks
JSON:
{
  "name":"Название задачи"
}
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор группы задач
nameДаstringНазвание задачи
taskNumberНетstringНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
Пример запроса:
POST /api/v1/taskgroups/2/tasks
JSON:
{
  "name":"Задача 3"
}
Структура ответа:
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Задача 3",
    "parent": null,
    "group": {
      "id": 2,
      "name": "Группа 2"
    },
    "taskNumber": null,
    "archived": false,
    "changedOn": "20171126T162353"
  }
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание задачи
parentРодительская задача
groupГруппа, в которой находится задача
taskNumberНомер задачи. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная задача
changedOnДата создания (изменения) задачи

Архивировать задачу

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

POST /tasks/{id}/archive
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор задачи
Пример запроса:
POST /api/v1/tasks/1/archive
Структура ответа:
{
  "status": "success"
}

Разархивировать задачу

Данный метод позволяет восстановить задачу из архива.

POST /tasks/{id}/archive
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор задачи
Пример запроса:
POST /api/v1/tasks/1/unarchive
Структура ответа:
{
  "status": "success"
}

Группы задач

Получение списка групп задач

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

GET /taskgroups
Входные параметры:
ПараметрОбязательныйТипОписание
archivedНетBooleanПоказать только архивные или не архивные группы. Если параметр не указан, будут показаны все группы.
groupNumberНетstringПоказать группу только с указанным номером.
Пример запроса:
GET /api/v1/taskgroups
Структура ответа:
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Группа 1",
      "parent": null,
      "groupNumber": null,
      "archived": false,
      "changedOn": "20171123T143142"
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор группы
nameНазвание группы
parentРодительская группа
groupNumberНомер группы. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная группа
changedOnДата создания (изменения) группы

Создать группу задач

Данный метод позволяет создать новую группу задач.

POST /taskgroups
JSON:
{
  "name":"Название группы"
 }
 
Входные параметры:
ПараметрОбязательныйТипОписание
nameДаstringНазвание группы
groupNumberНетstringНомер группы. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
Пример запроса:
POST /api/v1/taskgroups
JSON:
{
  "name":"Группа 1"
 }
Структура ответа:
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Группа 1",
      "parent": null,
      "groupNumber": null,
      "archived": false,
      "changedOn": "20171123T143142"
    }
  ]
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание группы
parentРодительская группа
groupNumberНомер группы. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная группа
changedOnДата создания (изменения) группы

Создать подгруппу задач

Данный метод позволяет создать подгруппу задач.

POST /taskgroups/{id}
JSON:
{
  "name":"Группа 2"
 }
 
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор родительской группы
nameДаstringНазвание группы
groupNumberНетstringНомер группы. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
Пример запроса:
POST /api/v1/taskgroups/1
JSON:
{
  "name":"Группа 2"
 }
Структура ответа:
{
  "status": "success",
  "data": {
    "id": 2,
    "name": "Группа 2",
    "parent": {
      "id": 1,
      "name": "Группа 1"
    },
    "groupNumber": null,
    "changedOn": "20171126T133141"
  }
}
Описание полей ответа:
ПараметрОписание
idИдентификатор задачи
nameНазвание группы
parentРодительская группа
groupNumberНомер группы. Может быть использован для интеграции с другими системами задач (например, 1c, Redmine, Bitrix)
archivedАрхивная/не архивная группа
changedOnДата создания (изменения) группы

Архивировать группу задач

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

POST /taskgroups/{id}/archive
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор группы
Пример запроса:
POST /api/v1/taskgroups/1/archive
Структура ответа:
{
  "status": "success"
}

Разархивировать группу задач

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

POST /taskgroups/{id}/unarchive
Входные параметры:
ПараметрОбязательныйТипОписание
idДаintИдентификатор группы
Пример запроса:
POST /api/v1/taskgroups/1/unarchive
Структура ответа:
{
  "status": "success"
}