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

Обновлено: 09.08.2025

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

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

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

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

1. Timetta реализует OData v4 API, доступный на конечной точке https://api.timetta.com/odata.
2. Метаданные API в формате XML доступны по адресу https://api.timetta.com/odata/$metadata.
3. Описание сущностей можно найти в приложении Настройка -> Менеджер сущностей.

Для аутентификации используется отдельный 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": {}
    }
}