API интерфейс предназначен для разработчиков и используется для интеграции ваших приложений с системой Bitcop. Если у вас имеются вопросы по работе API или требуются дополнительные возможности интеграции, свяжитесь с нами по адресу: support@bitcop.ru
API работает по протоколу HTTP и представляет собой набор методов, с помощью которых совершаются запросы и возвращаются ответы для каждой операции. Все ответы приходят в виде JSON структур.
Начало работы с API
Чтобы работать с API необходимо:
- Получить ключ API (apikey) в личном кабинете администратора в разделе
[Настройки] - [Токены доступа] - [API-ключ]
.
- Использовать данный ключ в каждом запросе к API в параметрах URL.
Формат запроса
URL любого API-запроса составляется следующим образом:
https://<имя_вашего_аккаунта>.bitcop.ru:4443/api/v1/
Пример:
https://demo.bitcop.ru:4443/api/v1/employees?&apikey=cb3436c284d34d748212bd92842f813d
Получение списка сотрудников
Данный метод позволяет получить список всех зарегистрированных сотрудников в системе.
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"
}