Открытый API TARGPatrol
External API связывает ваши системы с одной организацией TARGPatrol. Это руководство посвящено доступу, аутентификации и безопасной интеграции. Конкретные поля и примеры отдельных методов находятся в API Reference, а не в этой вводной статье.
Доступность и ключи API
External API доступен на Base и Enterprise, но не на Free. Токены организации создаёт и управляет ими Владелец в веб-приложении. Ключ определяет одну организацию и не является паролем личного кабинета или ID/PIN мобильного пользователя.
Войдите в веб-приложение и откройте нужную организацию под Владельцем.
Перейдите в «Управление → External API» и нажмите «Добавить токен».
Укажите понятное название интеграции, сохраните токен и скопируйте ключ.
Храните ключ в серверном хранилище секретов. По возможности используйте отдельные токены для интеграций и отзывайте ненужные.
Аутентификация запросов
Отправляйте HTTPS-запросы на API-хост из документации с базовым путём /api/v1. Передавайте ключ в заголовке x-api-key. Вход в веб-приложение не аутентифицирует внешний запрос. Не помещайте ключ в URL, браузерный код, скриншоты, публичный репозиторий или журналы.
1x-api-key: <YOUR_API_KEY>Документация и безопасное тестирование
Откройте API Reference и проверьте метод, путь, обязательные поля и схему ответа нужной операции.
Начните с запроса только для чтения и убедитесь, что получены данные нужной организации. Интерактивные запросы документации могут работать с реальными данными.
Используйте пагинацию, фильтрацию и сортировку, описанные для конкретной операции: значения по умолчанию не обязательно одинаковы.
Перед записью уточните семантику POST, PUT или PATCH и поведение пропущенных, null и пустых значений. Сначала проверяйте изменения в тестовой организации.
Обрабатывайте сетевые и серверные ошибки осознанно. Не повторяйте запросы создания вслепую и не записывайте ключи или персональные данные в диагностические журналы.
API Reference и интерактивное тестирование
Проверка проблем доступа
При 401 проверьте заголовок x-api-key и существование токена. При 403 — тариф и требования операции. При 404 — URL, идентификатор и организацию; при 400 — формат запроса и детали валидации. Если ключ раскрыт, замените его и обновите все использующие его интеграции.
Что нового в API Reference
1.1
В Reference 1.1 поле lastName стало обязательным при создании пользователя, а название поля назначения локаций исправлено на locationIds. При подготовке запросов сверяйтесь с актуальной схемой пользователя.
1.2
В Reference 1.2 добавлено получение временных подписанных ссылок для скачивания вложений устаревшего модуля Issues, включая ссылки на миниатюры, если они доступны. Ссылки нужно использовать до истечения срока их действия.
1.3
В Reference 1.3 добавлены просмотр списка и создание комментариев к Задачам, Инцидентам и устаревшим Issues, а также редактирование и удаление комментариев, созданных через API. Существующие вложения комментариев доступны для чтения и скачивания; загрузка вложений и редактирование комментариев пользователей приложения через этот API не поддерживаются.
1.4
В Reference 1.4 появились структурированные данные международных телефонных номеров и их валидация для пользователей. Точные правила запросов и обновлений приведены в актуальных схемах.
1.5
В Reference 1.5 добавлена история изменений отдельных записей только для чтения. Последующие дополнения описывают историю Пользователей, Локаций и Точек, порядок отображения точек и отдельные операции перестановки/перемещения. Поддерживаемые методы и условия совместимости проверяйте в текущем справочнике.
1.6
Версия документации 1.6 описывает повторения задач по локальному календарю с явным часовым поясом и сохранённым шаблоном локального начала и окончания. Перед созданием или изменением серии проверяйте текущую схему повторений.
1.7
Версия документации 1.7 добавляет чтение событий геозоны и связанные поля локаций и пользователей, а также уточняет поддерживаемые операции с тегами. Аутентификация и базовый путь /api/v1 не изменились. Схемы, права и валидацию смотрите в актуальной документации API; вебхуки событий геозоны не входят в это обновление.
Это версии справочника/схемы API, а не новые префиксы URL: базовый путь остаётся /api/v1. Краткая сводка не заменяет полный список методов. Для событийных обновлений отдельно настраиваются webhooks.