Общие сведения об API
Обновлено: 26.12.2023
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 нет. Мы прилагаем все усилия для недопущения критических изменений, если таковые есть — предупреждаем минимум за 14 дней, но при разработке интеграций необходимо быть готовым поддерживать её актуальность.
Сущности могут содержать поля навигации. Например, сущность User содержит навигационное свойство Department. Такое поле всегда идет в паре с ключом, в данном случае departmentId.
Примечание
В описании сущностей мы опускаем упоминание о наличии ключа навигации.
Поля навигации можно «раскрывать» при запросе, используя параметр expand:
[GET] https:
$select=name,departmentId&$expand=department($select=name)
Response:
{
"name": "Иван Агафонов",
"departmentId": "9468cd5c-ea04-4adb-a1d7-94b6b910ab2e"
"department":
{
"name": "Департамент корпоративного аудита 02"
}
}
Для обновления полей навигации необходимо использовать их ключи, например:
[PATCH] https:
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": {}
}
}
Перед разработкой интеграции с Timetta, рекомендуется тестировать обращения к API отдельно, например, с помощью Postman. Это позволит отделить потенциальные проблемы с использованием API от логики и окружения конкретного интеграционного механизма и, в случае обращения в поддержку, значительно ускорит время ответа.
Для изучения и отладки запросов скопируйте коллекцию в свой аккаунт Postman.
- Для отладки потребуется действующий пользователь.
- В настройках коллекции введите значение для переменных user_email и user_password.
- Все запросы требуют авторизации через токен доступа. Для получения токена доступа выполните запрос Get Access Token. Запрос использует учетные данные пользователя из настроенных переменных, получает access_token, и записывает его в переменную access_token. Далее этот токен используется во всех прочих запросах.
- Время жизни access_token — 1 час. Далее необходимо выполнить запрос Get Access Token повторно.