API Timetta может использоваться при создании сторонних интеграции для манипулирования данными абонента в обход веб-интерфейса Timetta.
Timetta реализует OData v4 API доступный на конечной точке https://api.timetta.com/odata.
Примечание
Спецификация OData доступна на официальном сайте — https://www.odata.org. Если вы не знакомы с этим протоколом, то рекомендуем до разработки интеграции освоить, как минимум, базовые понятия — https://www.odata.org/getting-started/understand-odata-in-6-steps.
Для аутентификации используется отдельный OAuth 2.0 сервис доступный по адресу https://auth.timetta.com. Подробнее — Аутентификация.
В большинстве случаев любая сущность управляется стандартными методами (POST, GET, PUT, PATCH, DELETE). Поддерживается язык запросов OData. Для отдельных сущностей доступны специализированные действия и функции.
Важно
Timetta — развиваемая система. Версионирования API нет. Мы прилагаем все усилия для недопущения критических изменений, если таковые есть — предупреждаем минимум за 14 дней, но при разработке интеграций необходимо быть готовым поддерживать её актуальность.
Сущности могут содержать поля навигации. Например, сущность 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": {}
}
}
Перед разработкой интеграции с Timetta, рекомендуется тестировать обращения к API отдельно, например, с помощью Postman. Это позволит отделить потенциальные проблемы с использованием API от логики и окружения конкретного интеграционного механизма и, в случае обращения в поддержку, значительно ускорит время ответа.
Примечание
Примеры запросов доступны на узле https://postman.timetta.com.
Для изучения и отладки запросов скопируйте коллекцию в свой аккаунт Postman.
Перейти на русскую версию?