tenderplan-api

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>. Токен получают одним из трёх способов:

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

3. 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, лимиты