Публичный API

Публичный API TrucklineMP — это REST-интерфейс только для чтения, предназначенный для сторонних интеграций. Он предоставляет доступ к данным каталога VTC, мероприятиям, новостям, поиску пользователей, записям модерации и метаданным платформы.

Все эндпоинты доступны без аутентификации. Передача ключа API из Консоли разработчика увеличивает ваши лимиты запросов и привязывает запросы к вашему проекту.

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

Отправьте ваш ключ API в заголовке Authorization:

Authorization: Bearer tlmp_api_YOUR_API_KEY

Ключи API:

• Используют префикс tlmp_api_ (например, tlmp_api_a1b2c3...). Старые ключи, выпущенные с устаревшим префиксом tl_, всё ещё работают.
• Создаются для каждого проекта в Консоли разработчика.
• Отображаются один раз при создании. Храните их в безопасности.
• Предоставляют доступ только для чтения к публичным данным. Они не открывают доступ к приватным действиям аккаунта или операциям записи.
• Могут быть отозваны в любое время из консоли.

Недействительные или отозванные ключи игнорируются. Запрос рассматривается как анонимный и получает анонимные лимиты запросов.

Если ваш API-ключ оказался в открытом доступе (например, был закоммичен в репозиторий), немедленно смените его — см. Утечка API-ключей и секретов.

Сессионные cookie

Некоторые эндпоинты возвращают дополнительные поля, когда вы авторизованы на trucklinemp.com и отправляете сессионные cookie с запросом (например, поля VTC, доступные только участникам). Это необязательно и предназначено для внутреннего использования. Сторонние интеграции должны полагаться на ключи API и OAuth, где это применимо.

Базовые URL-адреса

Среда	Базовый URL	Примечания
Рабочая	https://api.trucklinemp.com	Хост публичного API
Тот же источник	https://trucklinemp.com/api/v1	Используется в браузере

Важно: не дублируйте /v1

Рабочий хост api.trucklinemp.com маршрутизируется через nginx. Запрос к:

https://api.trucklinemp.com/vtcs

проксируется к /api/v1/vtcs в приложении. Не добавляйте /v1 к URL-адресу хоста.

Запросы из того же источника используют /api/v1 напрямую:

https://trucklinemp.com/api/v1/vtcs

Пример запроса

curl "https://api.trucklinemp.com/version"

curl -H "Authorization: Bearer tlmp_api_YOUR_API_KEY" \
  "https://api.trucklinemp.com/vtcs?limit=10"

Лимиты запросов

Лимиты применяются к каждому IP-адресу клиента для анонимного трафика и к каждому ключу API (и IP-адресу), когда предоставлен действительный ключ. Лимиты действуют в течение 1-минутного и 5-минутного окон. Превышение любого из них возвращает HTTP 429 с ошибкой RATE_LIMITED.

Анонимные (без ключа API)

Окно	Лимит
1 минута	100 запросов
5 минут	400 запросов

Уровни ключей API

Уровень	1 минута	5 минут
free (по умолчанию)	1,000	5,000
basic	2,500	12,000
premium	5,000	25,000
unlimited	20,000	80,000

Назначение уровней управляется администрацией TrucklineMP. Обратитесь в поддержку, если вашей интеграции требуется более высокий уровень.

Лучшие практики

• Кэшируйте ответы, где это возможно. Многие эндпоинты списков поддерживают пагинацию.
• Делайте паузу при получении ответов 429. Уменьшите параллельность запросов перед повторной попыткой.
• Всегда отправляйте действительный ключ API в рабочей среде. Анонимные лимиты предназначены только для легкого тестирования.

Обзор эндпоинтов

Спецификация OpenAPI на trucklinemp.com/api/v1/openapi.json является главным источником истины. Основные группы ресурсов:

Группа	Примеры
Платформа	GET /version, GET /status, GET /rules, GET /partners, GET /stats
VTC	GET /vtcs, GET /vtcs/{idOrHandle}, GET /vtcs/{id}/members, GET /vtcs/{id}/news, GET /vtcs/{id}/events, GET /vtcs/{id}/roles
Мероприятия	GET /events, GET /events/{eventId}, GET /events/{eventId}/attendees, GET /events/{eventId}/slots
Новости	GET /news, GET /news/{newsId}
Пользователи	GET /users/search, GET /users/{handleOrId}, GET /users/steam/{steamId}, GET /users/batch, GET /users/{id}/bans, GET /users/{id}/events

Публичные объекты пользователя включают поле steamId (строка SteamID64 или null, если аккаунт не привязан). Вы также можете получить профиль с помощью GET /users/{steamId} или через специальный маршрут GET /users/steam/{steamId}. | Баны | GET /bans, GET /bans/{id} | | Программы | GET /programs/badges/{slug}, GET /programs/recognition | | Сессия | GET /session (самоанализ сессии на основе cookie) |

Параметры пути, такие как {idOrHandle}, принимают либо числовой ID, либо публичный никнейм там, где это отмечено в спецификации.

TypeScript SDK

Для интеграций на базе Node.js вы можете использовать официальный клиент вместо написания запросов fetch вручную. См. TypeScript SDK.

Ответы с ошибками

Распространенные коды ошибок:

Код	HTTP	Значение
UNAUTHORIZED	401	Отсутствующие или недействительные учетные данные на защищенном маршруте
FORBIDDEN	403	Действительная аутентификация, но недостаточно прав
NOT_FOUND	404	Ресурс не существует
RATE_LIMITED	429	Превышен лимит запросов
VALIDATION_ERROR	400	Неверные параметры пути или запроса

Интерактивные инструменты

• API Playground: отправляйте запросы из браузера (использует тот же /api/v1).
• Swagger UI: просматривайте полную схему интерактивно, прямо здесь в документации.

Связанные руководства

• Обзор платформы для разработчиков
• Приложения OAuth (вход пользователей, не требуется для публичных эндпоинтов чтения)
• Вебхуки (push-уведомления о событиях)
• Утечка API-ключей и секретов (устранение последствий компрометации ключа)