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"
}