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

Обновлено: 09.08.2025

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

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

С помощью API можно:

• читать и изменять данные сущностей;
• создавать и удалять записи;
• выполнять специализированные действия и функции;
• строить аналитические выборки и отчёты;
• интегрировать Timetta с внешними системами.

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

Timetta предоставляет API на базе протокола OData v4.

Основная конечная точка API:

https://api.timetta.com/odata

Метаданные API доступны по адресу:

https://api.timetta.com/odata/$metadata

Описание структуры сущностей доступно в приложении:

Настройка → Менеджер сущностей

Именно описание сущностей рекомендуется использовать как основной источник информации о:

• доступных свойствах;
• обязательных полях;
• типах данных;
• навигационных свойствах;
• дочерних коллекциях.

АутентификацияАутентификация

Для доступа к API используется отдельный OAuth 2.0 сервис:

https://auth.timetta.com

Подробное описание процесса получения токена приведено в статье Аутентификация.

Все запросы к API выполняются с использованием Bearer Token.

Общий принцип работыОбщий принцип работы

Большинство сущностей API поддерживают стандартный набор операций OData:

• чтение коллекций;
• чтение одной записи;
• создание;
• обновление;
• удаление.

Также поддерживаются стандартные возможности OData:

• фильтрация ($filter);
• сортировка ($orderby);
• выбор полей ($select);
• раскрытие связанных сущностей ($expand);
• пагинация ($top, $skip);
• получение общего количества ($count).

Для отдельных сущностей могут быть доступны специализированные Actions и Functions.

Описание этих операций приводится в документации соответствующих сущностей.

Навигационные свойства и связиНавигационные свойства и связи

Сущности могут содержать ссылки на другие сущности и дочерние коллекции.

Например:

• ссылка на руководителя проекта (manager);
• ссылка на организацию (organization);
• коллекция строк документа (lines).

Для ссылочных свойств используется отдельное ключевое поле:

• manager → managerId
• organization → organizationId

При создании и обновлении связей используются именно идентификаторы.

Подробное описание работы со связями приведено в отдельных статьях документации.

Версионность APIВерсионность API

Timetta является развиваемой системой.

Версионирование API не используется.

Мы стремимся сохранять обратную совместимость, однако при внесении изменений, способных повлиять на интеграции, уведомляем клиентов не менее чем за 14 дней.

При разработке интеграций рекомендуется учитывать возможность развития API.

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

Перед реализацией интеграции рекомендуется тестировать запросы отдельно от прикладного кода.

Для этого можно использовать:

• Postman
• Insomnia
• curl

Это позволяет:

• быстрее проверять гипотезы;
• отлаживать запросы;
• изолировать ошибки интеграционной логики.

Структура документацииСтруктура документации

Документация API разделена на несколько групп:

• Общие принципы работы — базовые операции OData;
• Справочник сущностей — описание конкретных моделей данных;
• Actions и Functions — специализированные операции;
• Аутентификация — получение и использование токенов доступа.

Рекомендуется начинать изучение API с раздела общих принципов.