tenderplan-api - SKILL.md Agent Skill

name: tenderplan-api description: Use when the user works with Тендерплан (tenderplan.ru) via API — поиск и мониторинг тендеров 44-ФЗ/223-ФЗ, заказчики, поставщики, чек-листы, метки, ключевые слова, фильтры, календарь, экспорт. Triggers: "Тендерплан API", "tenderplan", "тендерплан", "поиск тендеров через API", tenderplan.ru/api.

Тендерплан API

Этот навык помогает обращаться к API Тендерплана (https://tenderplan.ru/api/...). В комплекте — полная OpenAPI 3.0.3-спека (375 путей / 381 операция / 45 секций), выгруженная из https://tenderplan.ru/api/doc/, плюс справочник по OAuth и права доступа.

Спека большая (~4 МБ JSON). Не читай её целиком — используй CLI ниже, чтобы доставать только нужное.

Авторизация

Все запросы требуют заголовок Authorization: Bearer <access_token>. Токен получают одним из трёх способов:

PAT (Personal Access Token) — самый простой путь. Пользователь создаёт токен в личном кабинете Тендерплан и передаёт его. Никаких OAuth-flow запускать не нужно — берёшь PAT и кладёшь в Authorization.

OAuth2 Client Credentials — для зарегистрированных приложений, нужен только для методов с разрешением resources:external (acts/get, bankguarantees/get, информация о тендерах без персональных данных). Получение:

TENDERPLAN_CLIENT_ID=... TENDERPLAN_CLIENT_SECRET=... \
  python3 scripts/get_token.py
# печатает access_token; --json — полный JSON-ответ

или напрямую:

curl -s -X POST https://tenderplan.ru/auth/client/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$TENDERPLAN_CLIENT_ID&client_secret=$TENDERPLAN_CLIENT_SECRET"

OAuth2 Authorization Code — двухэтапный flow для запросов от лица пользователя. Авторизация через /auth/client/authorize, обмен кода на токен — /auth/client/token. Используй, когда пишешь приложение, в котором пользователь нажимает «Войти через Тендерплан».

Кэшируй токен на сессию. На 401 — обнови и повтори запрос ровно один раз.

Полный текст про OAuth, права (comments:read, relations:write, resources:external и т.д.) и квоты — в references/oauth.md.

Лимиты

Не более 250 запросов / 10 секунд и 800 запросов / 60 секунд на одного пользователя или приложения. На превышении — 429. Для долгих сессий используй HTTP Keep-Alive — снижает риск попадания в чёрные списки.

Как найти нужный эндпоинт — DO THIS FIRST

Спека слишком большая, чтобы читать её целиком. В навыке есть CLI:

# 1) Все секции с количеством эндпоинтов
python3 scripts/lookup_endpoint.py tags

# 2) Поиск эндпоинтов по подстроке в path/summary/description/tag
#    (case-insensitive, со стем-fallback'ом для русских словоформ)
python3 scripts/lookup_endpoint.py search тендер
python3 scripts/lookup_endpoint.py search акты
python3 scripts/lookup_endpoint.py search /searchfilters
python3 scripts/lookup_endpoint.py search --tag calendar

# 3) Полные детали операции (parameters, requestBody, responses, security)
python3 scripts/lookup_endpoint.py show /api/tenders/get
python3 scripts/lookup_endpoint.py show /api/searchfilters/get --method get

show раскрывает top-level $ref для читаемости, но вложенные refs оставляет. Если нужно глубже — читай references/tenderplan-api-openapi.json через jq. В этой спеке components.schemas пустой (Тендерплан описывает схемы инлайново в каждой операции), так что ходить по $ref почти не приходится.

description каждой операции содержит строку вида PERMISSION: [resources:external] — именно это право должно быть в скоупе токена.

Секции (44 штуки)

Самые крупные:

Секция	Эндпоинтов	Что внутри
`tenders`	32	Получение тендеров, файлы, аттачменты, история, аналитика, лоты
`lawyers`	25	Юристы — реестр, споры, поиск тендеров с правовыми рисками
`organizations`, `users`	19 каждая	Организации (заказчики/поставщики), пользователи фирмы
`marks`, `relations`	15 каждая	Метки на тендерах, привязки тендеров к меткам/ключам/пользователям
`keys`	14	Ключевые слова, по которым ищутся тендеры
`firms`, `objectTable`	13 каждая	Фирма пользователя, кастомные таблицы атрибутов на тендерах
`comments`, `calendar`, `customers`, `partners`	11–12	Комментарии, календарь, заказчики, кабинет партнёра
`searchfilters`, `export`, `search`, `tasks`	8–10	Фильтры поиска, экспорт CSV/ICS, поиск, задачи
остальные	1–8	acts, bankguarantees, attachments, checklists, csi-feedback, info, invites, notifications, banks, integrations, telegram, products, rnp, payers, orders, myfirms, banks, business-calendar, …

auth (38 операций) — это сам OAuth и управление приложениями (/auth/client/*), регистрация, смена пароля, подтверждение email и т.п. Через сам API его дёргать редко нужно; авторизуешься обычно один раз через UI или Client Credentials.

Полный список секций:

python3 scripts/lookup_endpoint.py tags

Соглашения по запросам

Все эндпоинты под https://tenderplan.ru (без отдельного API-домена). Префикс пути — /api/....
GET-эндпоинты обычно принимают параметры в query string. id тендера или фирмы — это MongoDB ObjectId (24 hex-символа), пример: 507f191e810c19729de860ea.
POST-эндпоинты обычно принимают JSON-тело. Заголовок Content-Type: application/json обязателен.
Многие списочные методы — постраничные. Параметры пагинации (limit/offset, cursor) различаются между секциями — всегда смотри show для конкретной операции.
Даты в API — обычно ISO-8601 (2025-12-31T23:59:59Z); в некоторых местах — unix-секунды. Проверяй параметром в show.

Типичные сценарии

Получить тендер по ID

TOKEN=...  # PAT или сервисный токен
curl -s "https://tenderplan.ru/api/tenders/get?id=507f191e810c19729de860ea" \
  -H "Authorization: Bearer $TOKEN" | jq .

Этот метод доступен и сервисным ключом (PERMISSION: []).

Получить список своих фильтров поиска

python3 scripts/lookup_endpoint.py show /api/searchfilters/getlist
# затем:
curl -s "https://tenderplan.ru/api/searchfilters/getlist" \
  -H "Authorization: Bearer $TOKEN"

Применить чек-лист к тендеру

python3 scripts/lookup_endpoint.py show /api/checklists/apply --method post
# смотришь requestBody → формируешь JSON → POST с Authorization

Экспорт календаря в ICS

Секция calendar имеет операцию /api/calendar/v2/ics/{token} — публичная ссылка с токеном-секретом, можно подписывать в любом календаре. Сам токен получается через /api/calendar/v2/ics.

Когда что-то идёт не так

401 Unauthorized — токен протух или невалиден. Перевыпусти PAT или обнови сервисный токен.
403 Forbidden — у токена не хватает прав. Сравни PERMISSION: [...] в description операции (lookup_endpoint.py show) с правами своего токена.
429 Too Many Requests — упёрся в лимит (250/10s или 800/60s). Подожди, добавь backoff. Включи Keep-Alive.
404 на пути — может быть опечатка или отсутствует /api/ префикс. Проверь через lookup_endpoint.py search.

Файлы навыка

tenderplan-api/
├── SKILL.md                                  # этот файл
├── scripts/
│   ├── lookup_endpoint.py                    # CLI-навигация по спеке
│   └── get_token.py                          # OAuth2 Client Credentials
└── references/
    ├── tenderplan-api-openapi.json           # полная спека OpenAPI 3.0.3
    └── oauth.md                              # OAuth flows, scopes, лимиты