API BioTime использует протокол авторизации OAuth 2.0

Для подключения кроме логина и пароля пользователя, потребуется указать что за приложение подключается к API. Для этого потребуются идентификатор приложения (ClientId) и Секретный ключ (ClientSecret), которые можно создать в биотайм в разделе "Управление->Настройки системы" на вкладке "Приложения".

Нажмите на кнопку "Добавить ключ доступа для приложения" и введите необходимые данные. По умолчанию доступ для нового приложения разрешён (параметр "Состояние - Подключение разрешено"), если его запретить, то приложение не сможет подключиться к API. Нажмите кнопку "Сохранить". На следующем шаге потребуются введённые Вами ClientId и ClientSecret.

Для выполнения запросов необходимо авторизоваться и получить токен доступа (Bearer token)

Допустим, Вы добавили ключи доступа для приложения с параметрами ClientId:MyApplication1 и ClientSecret:552EDF9B24544043923AF7B05F553BA9

Теперь нам потребуется создать пользователя для приложения. Это можно сделать в разделе "Управление-Пользователи". Если назначить пользователю роль с ограниченными правами, то API может ограничивать вызов некоторых соответствующих методов или отдавать лишь те данные, на которые у пользователя есть права.

По умолчанию в системе есть пользователь с логином admin и паролем admin

Пример авторизации на языке C#

                    
static void Main( string[] args )
{
    string baseUrl = "http://localhost:9000/";

    //по протоколу OAuth 2.0 описываем что за приложение обращается к API
    string APIClientId = "MyApplication1";//Это Ваш ClientId
    string APIClientSecret = "552EDF9B24544043923AF7B05F553BA9";//Это Ваш ClientSecret

    //получаем токен доступа(он не вечный, перестанет действовать через сутки, но можно его продлить (см. OAuth 2.0 refresh token) или получить новый токен)
    var token = GetAccessToken(baseUrl, APIClientId, APIClientSecret, "admin", "admin").GetAwaiter().GetResult();
    Console.WriteLine(token.AccessToken);
}
                
public static async Task GetAccessToken( string baseUrl, string clientId, string clientSecret, string login, string passwordHash )
{
    HttpClient client = new HttpClient();

    using (HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, baseUrl + "oauth/token"))
    {
        var values = new List> {
            new KeyValuePair(GrantType, Password),
            new KeyValuePair(Username, login),
            new KeyValuePair(Password, passwordHash),
        };

        request.Headers.Authorization = new AuthenticationHeaderValue("Basic", EncodeToBase64(string.Format("{0}:{1}", clientId, clientSecret)));
        request.Content = new FormUrlEncodedContent(values);
        HttpResponseMessage response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();
        var resultJSON = await response.Content.ReadAsStringAsync();
        return Newtonsoft.Json.JsonConvert.DeserializeObject(resultJSON);

    }
}

private static string EncodeToBase64( string value )
{
    var toEncodeAsBytes = Encoding.UTF8.GetBytes(value);
    return Convert.ToBase64String(toEncodeAsBytes);
}


[DataContract]
public class AccessTokenResponse
{
[DataMember(Name = "access_token")]
public string AccessToken { get; set; }

[DataMember(Name = "token_type")]
public string TokenType { get; set; }

[DataMember(Name = "expires_in")]
public uint ExpiresIn { get; set; }

[DataMember(Name = ".issued")]
public DateTime Issued { get; set; }

[DataMember(Name = ".expires")]
public DateTime Expires { get; set; }

[DataMember(Name = "refresh_token")]
public string RefreshToken { get; set; }
}
                        
                    

По умолчанию API доступно по адресу http://localhost:9000/api/v1/

Далее указывается ресурс(Controller) и действие(Action). Например, метод получения сотрудников вызывается по такому адресу: http://localhost:9000/api/v1/Employees/GetAllNotHidden

Для GET методов параметры передаются в строке запроса (http://localhost:9000/api/v1/Employees/Get?id=BCB59AA3-2281-4340-ACC1-C148211E3C67)

Для POST методов параметры передаются в теле запроса (body) в JSON формате

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

                    
static void Main( string[] args )
{
    string baseUrl = "http://localhost:9000/";

    //по протоколу OAuth 2.0 описываем что за приложение обращается к API
    string APIClientId = "MyApplication1";//Это Ваш ClientId
    string APIClientSecret = "552EDF9B24544043923AF7B05F553BA9";//Это Ваш ClientSecret

    //получаем токен доступа(он не вечный, перестанет действовать через сутки, но можно его продлить (см. OAuth 2.0 refresh token) или получить новый токен)
    var token = GetAccessToken(baseUrl, APIClientId, APIClientSecret, "admin", "admin").GetAwaiter().GetResult();
    
    var allEmployees = GetAllEmployees(baseUrl, token.AccessToken);
}

public static List GetAllEmployees( string baseUrl, string token )
{
    using (var client = new WebClient())
    {
        client.BaseAddress = baseUrl;
        client.Headers[HttpRequestHeader.Authorization] = "Bearer " + token;
        client.Headers[HttpRequestHeader.ContentType] = "application/json; charset=utf-8";
        client.Headers[HttpRequestHeader.Accept] = "application/json; charset=utf-8";
        client.Encoding = Encoding.UTF8;


        string json = client.DownloadString("api/v1/Employees/GetAllNotHidden");
        //Console.WriteLine(json);

        var allEmployees = Newtonsoft.Json.JsonConvert.DeserializeObject>(json);

        return allEmployees;
    }
}


public class Employee
{
    public Guid Id { get; set; }

    public DateTimeOffset LastModified { get; set; }


    public string FirstName { get; set; }

    public string MiddleName { get; set; }

    public string LastName { get; set; }

    public DateTimeOffset? BirthDate { get; set; }

    public string Number { get; set; }

    public string Email { get; set; }

    public string WorkPhone { get; set; }

    public string HomePhone { get; set; }

    public string MobilePhone { get; set; }

    public int Gender { get; set; }

    public bool IsHidden { get; set; }

    public string FullName
    {
        get
        {
            string s = LastName;

            if (!string.IsNullOrEmpty(FirstName))
                s += " " + FirstName;

            if (!string.IsNullOrEmpty(MiddleName))
                s += " " + MiddleName;

            return s;
        }
    }

    public string ShortName
    {
        get
        {
            string s = FirstName;

            if (!string.IsNullOrEmpty(LastName))
                s += " " + LastName;

            return s;
        }
    }

    public int IdDevice { get; set; }
}
                    
                

Отметки - это исходные данные для расчёта отработанных интервалов и статистики отработанного времени. В Биотайм реализована логика расчёта статистики, гораздо более сложная чем простое вычисление интервала Приход-Уход.

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

Описание полей типа данных Event:

                    
{
  "Id": "00000000-0000-0000-0000-000000000000",//идентификатор отметки, заполняется автоматически при добавлении

  "LastModified": "0001-01-01T00:00:00+00:00",//дата последней модификации записи, заполняется автоматически

  "OwnerId": "00000000-0000-0000-0000-000000000021",//идентификатор владельца отметки (Id сотрудника или гостевой карты)

  "CheckpointId": "53ea91ce-30a4-e3dc-ebdc-39f231307ee9",//идентификатор проходной

  "EventTime": "2022-06-06T09:00:00+00:00",//время отметки

  "EventType": 1,//тип отметки. При получении данных из API у отметки могут быть следующие 3 типа: 
                 //Приход = 1, 
                 //Уход = 2, 
                 ///Системное(не участвует в учёте времени) = 5. 
                 //Кроме того при добавлении отметки можно указать тип Авто = -1, 
                 //который перед сохранением в БД преобразуется в приход или уход в соответствии с логикой чередования направления прохода.

  "CreatedBy": "00000000-0000-0000-0000-000000000000",//Id пользователя, добавившего событие, заполняется автоматически

  "DeviceNumber":"CF4S190460077"//Номер устройства, с которого добавлено

  "Mode": 0,//Режим, в котором поступило (Offline=0, Online=1)

  "IsDeleted": false,//Удалено, не участвует в расчётах

  "VerifyMethod": 0//Способ авторизации на терминале (FP_OR_PW_OR_RF=0, FP=1, PIN=2, PW=3, RF=4)
}
                     
                

Для добавления отметки можно заполнить только обязательные поля:

                    
{ 

  "OwnerId": "00000000-0000-0000-0000-000000000021",//идентификатор владельца отметки (Id сотрудника или гостевой карты)

  "CheckpointId": "53ea91ce-30a4-e3dc-ebdc-39f231307ee9",//идентификатор проходной

  "EventTime": "2022-06-06T09:00:00+00:00",//время отметки

  "EventType": 1,//тип отметки. 
}