Общие сведения об API

Обновлено: 10.07.2024

НазначениеНазначение

API Timetta может использоваться при создании сторонних интеграции для манипулирования данными абонента в обход веб-интерфейса Timetta.

ИспользованиеИспользование

АрхитектураАрхитектура

Timetta реализует OData v4 API доступный на конечной точке https://api.timetta.com/odata. 
Метаданные API в виде XML доступны по адресу https://api.timetta.com/odata/$metadata

Для аутентификации используется отдельный OAuth 2.0 сервис доступный по адресу https://auth.timetta.com. Подробнее — Аутентификация.

В большинстве случаев любая сущность управляется стандартными методами (POST, GET, PUT, PATCH, DELETE). Поддерживается язык запросов OData. Для отдельных сущностей доступны специализированные действия и функции.

Тестирование и отладкаТестирование и отладка

Перед разработкой интеграции с Timetta, рекомендуется тестировать обращения к API отдельно, например, с помощью Postman. Это позволит отделить потенциальные проблемы с использованием API от логики и окружения конкретного интеграционного механизма и, в случае обращения в поддержку, значительно ускорит время ответа.

Примеры использования APIПримеры использования API

Для изучения и отладки запросов скопируйте коллекцию в свой аккаунт Postman.

• Для отладки потребуется действующий пользователь.
• В настройках коллекции введите значение для переменных user_email и user_password.
• Все запросы требуют авторизации через токен доступа. Для получения токена доступа выполните запрос Get Access Token. Запрос использует учетные данные пользователя из настроенных переменных, получает access_token, и записывает его в переменную access_token. Далее этот токен используется во всех прочих запросах.
• Время жизни access_token — 1 час. Далее необходимо выполнить запрос Get Access Token повторно.

Важно: примеры не могут охватить всю функциональность API и зачастую в них используется несколько параметров $select,$expand и т. д. для демонстрации возможностей OData.
После ознакомления с примерами, рекомендуется так же попробовать использовать запросы без параметров.
Например, чтобы получить все поля какой-либо сущности, нужно запросить ее без параметра $select или же с $select=*.

Поля навигацииПоля навигации

Сущности могут содержать поля навигации. Например, сущность User содержит навигационное свойство Department. Такое поле всегда идет в паре с ключом, в данном случае departmentId.

Поля навигации можно «раскрывать» при запросе, используя параметр expand:

[GET] https://api.timetta.com/odata/Users(a5e16802-23d9-48be-99bb-02d9e34c7409)?
$select=name,departmentId&$expand=department($select=name)

Response: 
{
   "name": "Иван Агафонов",
   "departmentId": "9468cd5c-ea04-4adb-a1d7-94b6b910ab2e"
   "department": 
   {
      "name": "Департамент корпоративного аудита 02"
   }
}

Для обновления полей навигации необходимо использовать их ключи, например:

[PATCH] https://api.timetta.com/odata/Users(a5e16802-23d9-48be-99bb-02d9e34c7409)  

Payload: 
{   
   "departmentId": "9468cd5c-ea04-4adb-a1d7-94b6b910ab2e"   
}

Обработка ответаОбработка ответа

В случае успешного выполнения операции возвращается ответ с HTTP кодом 200-204.

В случае ошибки аутентификации (чаще всего ввиду не переданного/истекшего Bearer token) возвращается ответ с HTTP кодом 401.

В случае ошибки доступа к сущности из-за отсутствия прав (см. статью Как работают права доступа) может вернуться ответ с HTTP кодом 403-404.

В случае ошибки в бизнес-логике возвращается ответ с HTTP кодом 500 и телом в формате:

{
    "error": {
        "code": "error code",
        "message": "error description",        
        "details": {}
    }
}