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 /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 Да Дата, за которую необходимо получить данные. Задается в виде количества секунд, прошедших с 01.01.1970 (Unix-time)
employees Нет Идентификаторы сотрудников через запятую. Если параметр не указан, то запрос будет выполнен по всем сотрудникам.
Пример запроса:
GET /api/v1/workperiods?date=1484524800&employees=6,7
Структура ответа:
{
  "status": "success",
  "items": [
    {
      "id": 6,
      "name": "Смирнова Татьяна",
      "date": "1484524800",
      "begin": 31834,
      "end": 65263
    },
    {
      "id": 7,
      "name": "Королев Алексей",
      "date": "1484524800",
      "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 /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 Участники. Идентификаторы сотрудников через запятую. Если список сотрудников не задан, задача будет доступна всем сотрудникам.
Пример запроса:
POST /api/v1/tasks

JSON:
{
  "name":"Задача 1"
}
Структура ответа:
{
  "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 Участники. Идентификаторы сотрудников через запятую. Если список сотрудников не задан, задача будет доступна всем сотрудникам.
Данный метод изменяет только те параметры, которые переданы запросе.
Пример запроса:
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"
}