Общие сведения об 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 от логики и окружения конкретного интеграционного механизма и, в случае обращения в поддержку, значительно ускорит время ответа.

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

Сущности могут содержать поля навигации. Например, сущность 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": {}
    }
}