API

Описание Kickidler API

API предоставляет возможность использовать функционал системы учёта рабочего времени Kickidler в личных проектах.

API предназначен для разработчиков и сопровождается документацией.

Kickidler API работает согласно настройкам Центрального Сервера по протоколам HTTP, HTTPS.

Внимание! Центральный сервер по умолчанию работает с протоколом http, для обеспечения безопасной работы с API через интернет рекомендуем выполнить настройку https.

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

<протоколЦС>://<хостЦС>:<портЦС>/api/<версия API>/<запрос>

При работе с Kickidler API каждый запрос должен содержать вводный контент.

<header> Content-Type: application/json
 

Kickidler API позволяет получать ответ в формате JSON объекта.

Описание формата
<протоколЦС> протокол обращения к Центральному Серверу http/https.
<хостЦС> доменное имя Центрального Сервера в системе DNS или IP-адрес Центрального Сервера.
<портЦС> порт для подключения к Центральному Серверу. Порт по умолчанию 8123.
<версия API> номер версии API. На текущий момент в программе реализованы следующие версии API:
  • v1.0

Ошибки

Kickidler использует обычные коды ответа HTTP, чтобы указать на успешность или неудачу API запроса.

В том случае, если API-ресурс указан правильно, но сам запрос выполнен с ошибкой, то вместе с кодом возврата приходит json с информацией об ошибке.

Коды состояний HTTP
200 - OK Все отработало так, как ожидалось.
400 - Bad Request Неприемлемый запрос, часто из-за отсутствия обязательного параметра.
403 - Forbidden У токена API нет или закончилось  разрешений на выполнение запроса.
404 - Not Found Запрошенный ресурс не существует.

Авторизация

Kickidler использует токены для аутентификации запросов, которым в дальнейшем должен быть подписан каждый запрос к API.

Срок действия токена 30 минут с последнего обращения.

После истечения срока токена, его необходимо получить заново.

Чтобы получить токен, нужно выполнить авторизацию.

Запрос

auth

Параметры запроса

Аргумент Описание
username Логин пользователя из системы учетных записей Центрального Сервера
password Пароль пользователя из системы учетных записей Центрального Сервера

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

curl  127.0.0.1:8123/api/v1.0/auth \
--request GET \
--header "Content-Type: application/json" \
--data '{"username":"API","password":"APIPASSWORD"}'

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


{
    "token": "{11b9c22a-219a-44cd-a9e0-a146d24f4d8c}",
    "username": "admin"
}

Запросы

Внимание! Для всех запросов существует опциональный аргумент id, который служит идентификатором отправленного запроса. В случае большого количества запросов, при его использовании в ответе отобразится идентификатор отправленного запроса.

Список сотрудников и отделов

Метод

GET

Запрос

organization-structure

Параметры запроса

Аргумент Описание
id Идентификатор запроса. Необязательный аргумент, который приходит в ответе при использовании аргумента id в запросе.
token токен для аутентификации запроса
 

Параметры ответа

Атрибут Тип данных Описание
request_id строка идентификатор запроса. необязательный атрибут, который приходит в ответе при использовании аргумента id в запросе.
structure объект структура организации
 
Объект structure
Атрибут Тип данных Описание
id строка идентификатор корневого отдела
parent_id строка идентификатор родительского отдела, для корневого отдела null
name строка наименование корневого отдела
departments массив массив с дочерними отделами department
employees массив массив с сотрудниками employee, для корневого отдела null
Массив department
Атрибут Тип данных Описание
id строка идентификатор отдела
parent_id строка идентификатор родительского отдела
name строка наименование отдела
departments массив массив с дочерними отделами department
employees массив массив с сотрудниками employee
Объект employee
Атрибут Тип данных Описание
id строка идентификатор сотрудника
department_id строка идентификатор отдела, в котором находится сотрудник
name строка имя сотрудника
surname строка фамилия сотрудника

Структура запроса


curl  127.0.0.1:8123/api/v1.0/organization-structure \
--request GET \
--header "Content-Type: application/json" \
--data '{
        "id":" ",
        "token":"{ }"
    }'

Структура ответа


{
    "request_id" : " ",
    "structure" : {
        "id" : " ",
        "parent_id" : " ",
        "name" : " ",
        "departments" : [
            department
        ]
        "employees" : [
            employee
        ]
}

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


{
    "request_id": "1",
    "structure": {
        "departments": [
            {
                "departments": [],
                "employees": [
                    {
                        "department_id": "1",
                        "id": "a37aeb2279fd4a0f8d506075ec93347f",
                        "name": "Jeff",
                        "surname": "Smith"
                    }
                ],
                "id": "1",
                "name": "Default department",
                "parent_id": "0"
            }
        ],
        "employees": [],
        "id": "0",
        "name": "Company",
        "parent_id": ""
    }
}

Данные из отчета по времени/эффективности

Метод

GET

Запрос

report-productivity

Параметры запроса

Аргумент Формат Описание
id строка Идентификатор запроса. Необязательный аргумент, который приходит в ответе при использовании аргумента  id в запросе.
token строка токен для аутентификации запроса
period_begin  строка по формату ISO: "YYYY-MM-DDThh:mm" начальная точка периода для запроса отчета. Дата должна приходить в UTC

не может быть больше period_end

period_end строка по формату ISO: "YYYY-MM-DDThh:mm" конечная точка периода для запроса отчета. Дата должна приходить в UTC.

не может быть меньше period_begin и больше текущего момента времени.

worktime_only строка параметр, отвечающий за необходимость учитывать в запросе только рабочее время. При значении 1 в ответе будет включено только рабочее время за указанный период. При значении 0 - полное время.
timezone_offset строка по формату ISO:

 +-hhmm

 разница между местным временем и UTC для правильной работы производственного календаря.

например: смещение для Москвы "+0300"
department_id строка 

Идентификатор отдела или сотрудника по которому нужно построить отчет.

В запросе нужно указать либо department_id  либо employee_id. 

Для работы по всей компании нужно использовать идентификатор корневого отдела 0.
employee_id строка 
 

Параметры ответа

Атрибут Тип данных Описание
request_id объект идентификатор запроса. необязательный атрибут, который приходит в ответе при использовании аргумента id в запросе.
departments массив массив с объектами department
 
Массив department
Атрибут Тип данных Описание
id строка идентификатор отдела
parent_id строка идентификатор родительского отдела, для корневого отдела null
name строка наименование отдела
productivity объект сгруппированные по элементу структуры организации отчетные данные productivity_data
departments массив массив с дочерними отделами department
employees массив массив с сотрудниками employee, для корневого отдела null
Объект productivity_data
Атрибут Тип данных Описание
total_time целое число общее количество времени активности и бездействия в секундах,
activity_time целое число количество времени активности в секундах,
unproductive_time целое число количество времени непродуктивной активности в секундах,
neutral_time целое число количество времени нейтральной активности в секундах,
productive_time целое число количество времени продуктивной активности в секундах,
uncategorized_time целое число количество времени активности "без категории" в секундах
idle_time целое число количество времени бездействия в секундах
Объект employee
Атрибут Тип данных Описание
id строка идентификатор сотрудника
department_id строка идентификатор отдела, в котором находится сотрудник
department_name строка название родительского отдела,
name строка имя сотрудника
surname строка фамилия сотрудника
productivity массив сгруппированные по сотруднику отчетные данные productivity_data

Структура запроса


curl --request GET --header "Content-Type: application/json" \
--data '{"id": "", 
        "token": "{ }",
        "period_begin": "YYYY-MM-DDThh:mm", 
        "period_end": "YYYY-MM-DDThh:mm", 
        "timezone_offset": "+-hhmm", 
        "worktime_only": "0", 
        "department_id": "0", 
        "employee_id": "" 
    }' 127.0.0.1:8123/api/v1.0/report-productivity

Структура ответа


{
    "request_id" : " ",
    "departments" : [
        department,
    ]
}

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


{
    "departments": {
        "departments": [
            {
                "departments": [],
                "employees": [
                    {
                        "department_id": "1",
                        "department_name": "Default department",
                        "id": "a37aeb2279fd4a0f8d506075ec93347f",
                        "name": "Jeff",
                        "productivity": {
                            "activity_time": 237,
                            "idle_time": 830,
                            "neutral_time": 0,
                            "productive_time": 196,
                            "total_time": 1067,
                            "uncategorized_time": 41,
                            "unproductive_time": 0
                        },
                        "surname": "Smith"
                    }
                ],
                "id": "1",
                "name": "Default department",
                "parent_id": "0",
                "productivity": {
                    "activity_time": 237,
                    "idle_time": 830,
                    "neutral_time": 0,
                    "productive_time": 196,
                    "total_time": 1067,
                    "uncategorized_time": 41,
                    "unproductive_time": 0
                }
            }
        ],
        "employees": [],
        "id": "0",
        "name": "Company",
        "parent_id": "",
        "productivity": {
            "activity_time": 237,
            "idle_time": 830,
            "neutral_time": 0,
            "productive_time": 196,
            "total_time": 1067,
            "uncategorized_time": 41,
            "unproductive_time": 0
        }
    },
    "request_id": "2"
}

Данные из отчета по рабочему времени

Метод

GET

Запрос

report-workinghours

Параметры запроса

Аргумент Формат Описание
id строка Идентификатор запроса. Необязательный аргумент, который приходит в ответе при использовании аргумента  id в запросе.
token строка токен для аутентификации запроса
period_begin  строка по формату ISO: "YYYY-MM-DDThh:mm" начальная точка периода для запроса отчета. Дата должна приходить в UTC

не может быть больше period_end

period_end строка по формату ISO: "YYYY-MM-DDThh:mm" конечная точка периода для запроса отчета. Дата должна приходить в UTC.

не может быть меньше period_begin и больше текущего момента времени.

timezone_offset строка по формату ISO:

 +-hhmm

 разница между местным временем и UTC для правильной работы производственного календаря.

например: смещение для Москвы "+0300"
department_id строка 

Идентификатор отдела или сотрудника по которому нужно построить отчет.

В запросе нужно указать либо department_id  либо employee_id. 

Для работы по всей компании нужно использовать идентификатор корневого отдела 0.
employee_id строка 
 

Параметры ответа

Атрибут Тип данных Описание
request_id объект идентификатор запроса. необязательный атрибут, который приходит в ответе при использовании аргумента id в запросе.
summary_data объект сгруппированные по всем сотрудникам отчетные данные workinghours
employee_rows массив массив с данными по сотрудникам rows
 
Объект workinghours
Атрибут Тип данных Описание
latenesses целое число суммарное время опозданий в секундах
number_of_latenesses целое число суммарное количество опозданий
undertimes целое число суммарное время ранних уходов в секундах
number_of_undertimes целое число суммарное количество ранних уходов
work_time целое число суммарное время на работе в секундах
absences целое число суммарное количество прогулов
business_trips целое число суммарное количество командировок
vacations целое число суммарное количество отпусков
sick_leaves целое число суммарное количество больничных
Массив rows
Атрибут Тип данных Описание
date строка дата, для которой представлены данные
id строка идентификатор сотрудника
department_id строка идентификатор родительского отдела,
department_name строка название родительского отдела,
name строка имя сотрудника
surname строка фамилия сотрудника
first_activity строка время первой активности сотрудника за день в формате hh:mm:ss,
last_activity строка время последней активности сотрудника за день в формате  hh:mm:ss. для текущего дня время последней активности сотрудника 00:00:00
workinghours объект сгруппированные по сотруднику отчетные данные workinghours

Структура запроса

curl --request GET --header "Content-Type: application/json" \
--data '{"id": " ", 
    "token": "{ }",
    "period_begin": "YYYY-MM-DDThh:mm", 
    "period_end": "YYYY-MM-DDThh:mm", 
    "timezone_offset": "+-hhmm", 
    "department_id": "0", 
    "employee_id": "" 
}' 127.0.0.1:8123/api/v1.0/report-workinghours

Структура ответа


{
    "request_id" : " ",
    "summary_data" : {
        workinghours
    }
    "employee_rows" : [
        rows
    ]

}

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


{
    "employee_rows": [
        {
            "date": "2022-01-11",
            "department_id": "1",
            "department_name": "Default department",
            "first_activity": "09:09:00",
            "id": "a37aeb2279fd4a0f8d506075ec93347f",
            "last_activity": "18:59:00",
            "name": "Jeff",
            "surname": "Smith",
            "workinghours": {
                "absences": 0,
                "business_trips": 0,
                "latenesses": 540,
                "number_of_latenesses": 1,
                "number_of_undertimes": 0,
                "sick_leaves": 0,
                "undertimes": 0,
                "vacations": 0,
                "work_time": 0
            }
        }
    ],
    "request_id": "2",
    "summary_data": {
        "absences": 0,
        "business_trips": 0,
        "latenesses": 540,
        "number_of_latenesses": 1,
        "number_of_undertimes": 0,
        "sick_leaves": 0,
        "undertimes": 0,
        "vacations": 0,
        "work_time": 0
    }
}