Fraim.ru Tenders API V2 — документация для ИИ-агентов

HTTP API по тендерам и контрактам России (44-ФЗ, 223-ФЗ, коммерческие торги): поиск закупок, живые ленты изменений по сохранённому фильтру, карточки тендеров и контрактов, история по ИНН заказчика и поставщика. Только server-to-server, авторизация Bearer-токеном, оплата — за доставленный объект, а не за запрос.

Документ самодостаточен: его можно целиком положить в контекст модели. Справочник эндпоинтов, параметры и схемы объектов сгенерированы из OpenAPI-схемы API. Всё, что схемой не выражается — модель данных, биллинг, формы ошибок, лимиты — описано ниже по боевому поведению; расхождения между схемой и API оговорены там, где они есть.

• Base URL: https://public.fraim.ru/api/v2
• Версия API: 2.0.0 (OpenAPI 3.1.0, снапшот схемы от 2026-09-10)
• Этот документ одним файлом: https://fraim.ru/ai.md
• Машинная схема (OpenAPI 3.1): https://public.fraim.ru/api/v2/openapi.json
• Документация для людей: https://fraim.ru/docs
• Личный кабинет (токены, баланс, пополнение и счёт, песочница): https://lk.fraim.ru
• Поддержка (ошибки, интеграция, доступы): support@fraim.ru
• Любые вопросы (цены, объёмы, договор): info@fraim.ru

Кратко: правила интеграции

1. Ходите в API только с сервера. Токен — это доступ к балансу; CORS отключён намеренно, из браузера API не работает.
2. Авторизация — заголовок Authorization: Bearer <token>. Легаси-заголовок X-API-Token не используйте: с ним не работает песочница.
3. Поиск — это POST /tenders/query с JSON-телом, а не GET со строкой запроса. Отдельного /search нет.
4. Множество задаётся ровно одним способом: критерии | filter_id | list_id (у контрактов ещё tender_ids). Смешение → 400 validation_error.
5. Пагинация только курсорная. Возьмите next_cursor из ответа и пришлите {"cursor": "cur_…"} — остальные поля повторять не нужно, курсор несёт фильтр внутри. Параметров page/offset не существует.
6. Выдача — живой список, а не снапшот: каждая страница отражает состояние тендеров на момент запроса. Повторный запрос с тем же курсором может вернуть меньше объектов или те же объекты с обновлёнными данными; пустой results с next_cursor — валидный ответ, а не конец ленты.
7. total — справочное поле: сколько объектов сейчас подходит под фильтр, а не размер вашей выборки. Считается фоном (пересчёт раз в несколько минут), поэтому меняется между запросами, в том числе прямо во время листания: гарантии «показали 693 — вытащите ровно 693» нет. Конец выборки определяйте по пустому results, а не по total и не по next_cursor (он не бывает пустым — лента живая). total: null — нормальный ответ, а не ошибка. Точное число приходит только на запросе по ids или list_id: это размер списка.
8. Потоки выбираются один раз, в первом запросе: events попадает в курсор, при чтении с курсором значение из тела игнорируется. Нужны изменения — сразу шлите events: ["created","updated"].
9. 202 preparing — не ошибка: идёт фоновый сбор. Повторите тот же запрос через retry_after секунд. state: "partial" в 200-ответе значит «читать уже можно, лента ещё дособирается».
10. Опрашивайте фильтр не реже раза в сутки: подписка живёт 14 дней от последнего чтения, а новая — первые сутки в пробном режиме. Умершая подписка означает 409 и потерю событий за период молчания.
11. Тарифицируется первая доставка версии объекта, а не запрос. Лишняя пагинация «на всякий случай» стоит денег; пустые ответы и повторы бесплатны.
12. На мутациях (POST/DELETE) заголовок Idempotency-Key обязателен — иначе 400 idempotency_key_required. Кладите UUID v4 и повторяйте его при ретрае; тот же ключ с ДРУГИМ телом — 409 idempotency_key_reused_with_different_payload.
13. При 429 дождитесь Retry-After и повторите — заголовок есть всегда. Ограничителя два: минутный на аккаунт (Retry-After: 60; считается на аккаунт, а не на токен — заводить новые токены ради частоты бессмысленно) и лимит всплесков по IP (Retry-After: 1). Параллельная выгрузка в несколько потоков упирается во второй раньше: держите 2–3 потока, а не 20.
14. Другого способа аутентификации, кроме вечного API-токена (fraim_live_…), нет: возьмите его в кабинете или создайте через POST /auth/tokens. Сессия браузера для интеграции не годится.
15. Объект приходит целиком прямо в ленте — в results[].tender (и results[].contract) лежит весь списочный объект, а не заглушка из пары полей. Не делайте GET /tenders/{id} на каждый элемент выдачи: это лишние запросы и лишние деньги. Карточка нужна только ради позиций, документов, лотов и полной организации.
16. Тело ошибки вложено в detail: {"detail": {"error": {…}}} — у всех кодов без исключений, включая 422 и 429. Особый случай один: у 409 cursor_expired внутри detail рядом с error лежит свежий срез ленты (detail.results, detail.next_cursor).
17. Документы качайте по download_url из карточки, а не по link. link — адрес у первоисточника (ЕИС, площадка, сайт заказчика), он может стать недоступен или потребовать входа на площадку; download_url ведёт на наш downloads.fraim.ru, работает без заголовка Authorization, срок действия у неё не ограничен. Но файл всё равно берётся у первоисточника (недавно скачанный — из нашего кеша), поэтому удалённый у источника документ не отдаст ни одна из ссылок: 410 document_gone. Документы уже доставленного объекта бесплатны.
18. Слова короче 3 символов в ключевых и минус-словах игнорируются — как и годы (2000–2099) и предлоги. ["насос жд"] ищется как ["насос"], а ["жд"] даёт 400. Отброшенное перечислено в ignored_keywords ответа.
19. keywords обязателен — фильтр без ключевых слов не примут (400), кроме случаев, когда множество задано узко через ids, list_id, supplier или customer. Одиночные слишком общие слова (поставка, услуга, работа, лот, номер…) отбрасываются, внутри фразы остаются, в exception_keywords не трогаются; если после отбрасывания искать нечего — 400.
20. Дедуплицируйте у себя по паре id + version. Поле billed отвечает на вопрос «списали ли деньги», а не «видел ли я этот объект».
21. Даты — ISO-8601. По умолчанию status: ["active"] и events: ["created"]; ленту изменений включайте явно.
22. regions, platforms, placement_types, purchase_types принимают внутренние id Fraim.ru — это не ОКАТО, не коды регионов на автомобильных номерах и не коды ЕИС. Москва — 1, Санкт-Петербург — 34, а 77 — Республика Бурятия. Коды всех четырёх справочников напечатаны ниже, в разделе «Справочники кодов» — берите оттуда. Не угадывайте номер: ошибки не будет, придёт выдача по другому региону.
23. Лишние поля верхнего уровня тела запроса игнорируются молча (page, offset, status у контрактов). Опечатка в имени (region вместо regions) не даст ошибки, а тихо изменит фильтр — сверяйте applied в ответе с тем, что вы посылали. Строго проверяются только вложенные customer и supplier: незнакомое поле там → 422.

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

Все маршруты требуют токен:

Authorization: Bearer fraim_live_…

API-токен вечный — живёт до явного отзыва. Создаётся в личном кабинете или запросом POST /auth/tokens; секрет показывается один раз, дальше виден только маскированный token_preview — короткий hex-хвост вида 064c...3b80, без префикса fraim_. Активных токенов — до 20. У только что созданного токена last_used_at приходит null, хотя схема помечает поле обязательным.

Два окружения различаются только префиксом токена, адрес и тело запроса те же:

• fraim_test_… — песочница на демо-данных, баланс не списывается;
• fraim_live_… — боевые данные, тарифицируется.

Переключение теста и боя определяется по заголовку Authorization. Легаси-заголовок X-API-Token ещё принимается для боевых токенов, но с ним тестовый токен уйдёт на боевой бэкенд и получит 401 — используйте Bearer.

Модель данных

Четыре понятия, без которых ответы API читаются неправильно.

Фильтр — сохранённый запрос, определяющий множество закупок. Создаётся неявно любым QUERY-запросом; filter_id — детерминированный хеш нормализованных параметров, поэтому одинаковые по смыслу запросы (другой порядок ключей, регистр, дубли) дают один и тот же фильтр.

Лента (feed) — поток событий по фильтру. У фильтра две ленты: тендерная и контрактная. Событие бывает created (объект впервые появился в вашем фильтре — неважно, только что опубликован или изменился и стал подходить под критерии) и updated (изменился объект, который уже был в фильтре); потоки читаются независимо, каждый своим курсором. Поле event описывает вашу историю, а не историю объекта: изменившийся тендер, которого вы раньше не получали, приедет как created.

Подписка — связка «вы ↔ фильтр» с TTL: она хранит вашу позицию в ленте и продлевается любым чтением.

Курсор — непрозрачная подписанная строка cur_<payload>.<sig>: позиция в конкретной ленте для конкретного набора событий. Возвращайте её как есть. Курсор идёт по оси индексации (когда объект обнаружен нами), а не по датам публикации, поэтому «отставшая» закупка не проваливается за курсор, а доезжает следующим запросом. Хронологию сортируйте у себя.

Версия — счётчик изменений объекта. Пара id + version — ключ дедупликации на вашей стороне.

Первый запрос отдаёт всё, что подходит под фильтр сейчас, дальше идёт поток того, что появится позже. Читается это одним и тем же способом — курсором.

Как работают ключевые слова

Поиск идёт не по подстроке, а по нормализованным словам: текст разбивается на слова и приводится к начальной форме, поэтому «поставка насосов» находит «поставку насоса». Многословный элемент keywords — это фраза (слова должны встретиться вместе), разные элементы списка — ИЛИ.

Слово короче 3 символов в поиске не участвует — оно выбрасывается вместе с остальным «шумом»:

• слова из 1–2 символов (жд, ip, а);
• годы (2024, 2025 и любой год 2000–2099);
• служебные части речи — предлоги, союзы, частицы (для, и, с).

Игнорируется только «голое» число — само по себе, без соседних букв или символов. Составные обозначения, где число сцеплено с буквами, дефисом, слэшем, подчёркиванием или точкой, поиском не игнорируются и ищутся как есть, даже если это год или короткий фрагмент:

• коды с буквами: ГОСТ 12345-78, ГОСТ Р 52948-2008, 38-09/зк, М-24-10, Ф10.5-2, 5w-40, 10w-30, 20w-50;
• число + дефис/слэш + число: 123-456, 2024-2025, 123/456, 220401/123;
• артикулы с несколькими дефисами: 12312-12312-выв, 123-4567-890, ABC-123-XYZ;
• размеры с x/х: 12.5x20, 10x20x30 мм, 12х20;
• обозначения с подчёркиванием: abc_123, файл_2024;
• смешанные буквенно-цифровые обозначения: ДИТ-2024-ГП, приказ-123, SN123456, S/N12345678, abc123, 123asd, asd123;
• дефисные цепочки: 8-800-555-35-35.

Из того, что эти обозначения не игнорируются, не следует, что ими стоит сужать поиск. Номер ГОСТа, ТУ или другой точный код почти всегда есть только в приложенной документации к закупке, а не в тексте самой карточки — такой запрос находит единицы объектов вместо всей номенклатуры. Правильный паттерн: широкое ключевое слово (кабель силовой, а не ГОСТ 32144-2013; электротехническая продукция, а не ТУ 27.32.13-001-12345678-2022) плюс последующий отбор найденного — вручную, через ИИ-анализ карточек или через exception_keywords. См. также таблицу антипаттернов ниже.

Что из этого следует на практике:

Всё выброшенное перечислено в поле ignored_keywords ответа ([{keyword, reason}]) — по нему видно, что именно осталось от запроса. Короткие обозначения (жд, кс, ip) в фильтр закладывать бессмысленно: ищите по полному слову (железнодорожный) или отбирайте такие закупки у себя после выдачи.

Слишком общий запрос не принимается

Фильтр — это подписка на ленту, а не разовая выгрузка реестра. Запрос, под который подходит половина закупок страны, даёт нечитаемую ленту, поэтому действуют четыре ограничения.

keywords обязателен. Запрос без них — 400. Исключение: множество задано узко другим способом — ids, list_id, supplier или любое поле customer. «Все активные закупки Москвы» фильтром быть не может, «все закупки заказчика по ИНН» — может.

Слишком общие слова выбрасываются. поставка встречается у 41.8% активных закупок, лот — у 19.6%, услуга — у 17.1%: как фильтр они не сужают ничего. В том же списке работа, оказание, выполнение, вид, тип, номер, заявка, нужда, закупка и ещё около двадцати служебных слов. Отбрасывается только элемент из одного слова: внутри фразы такое слово остаётся.

Список целиком, сверка идёт по начальной форме (поставки, поставку, поставок — одно и то же слово):

адрес, вид, выполнение, год, закупка, заявка, использование, количество, лот, назначение, наличие, номер, нужда, обеспечение, область, общий, объем, оказание, описание, определение, поставка, применение, проведение, работа, размер, соответствие, тип, услуга, форма, часть, являться

В минус-словах не выбрасывается ничего. exception_keywords: ["поставка"] работает как написано: «услуги, но не поставки» — осмысленный запрос.

Если после этого искать нечего — 400, а не пустая выдача.

Чистка происходит до вычисления filter_id, поэтому ["поставка","насос"] и ["насос"] — один и тот же фильтр: одна подписка вместо двух. На стоимость это не влияет — тарифицируется первая доставка версии объекта, и один и тот же тендер не списывается дважды, даже если подходит под несколько ваших фильтров.

Как читать выдачу: это живой список

Выдача всегда актуальна. Каждая страница отражает текущее состояние тендеров на момент запроса. Если фильтр задан со status: ["active"], в выдаче будут только тендеры, активные прямо сейчас: тендер, который завершился после попадания в вашу подписку, из выдачи исчезает автоматически. За такие тендеры баланс не списывается.

Страницы не повторяются байт-в-байт. Повторный запрос с тем же курсором может вернуть меньше объектов (часть перестала подходить под фильтр) или те же объекты с обновлёнными данными. Это нормальное поведение живой ленты, а не ошибка. Не стройте логику на том, что страница воспроизводится.

Пустая страница — валидный ответ. results: [] с next_cursor означает «на этом отрезке ленты сейчас нет подходящих объектов, продолжайте с нового курсора», а не «лента кончилась».

Гарантии курсора

• Каждое событие ленты доставляется не более одного раза. Повтор запроса со старым курсором не приводит ни к дублям, ни к повторным списаниям.
• События не теряются: всё, что появилось в ленте после вашей позиции, будет выдано при следующих чтениях — независимо от того, как часто вы опрашиваете (в пределах срока жизни подписки).
• Тендер, который вошёл в фильтр и вышел из него между вашими опросами (например, успел завершиться), не доставляется — на него уже нельзя отреагировать.
• 409 cursor_expired — лента была пересобрана (подписка истекала). Тело ответа содержит свежий срез и новый next_cursor — под ключом detail: продолжайте с него. История за период отсутствия недоступна.
• 402 balance_exhausted — пополните баланс и повторите запрос с тем же курсором: выдача продолжится с первого неоплаченного объекта.

Подписки и TTL

• Подписка на фильтр продлевается любым чтением и живёт 14 дней от последнего запроса.
• Новая подписка первые сутки живёт в пробном режиме: если вы не повторили запрос в течение 24 часов, она удаляется. Первый же запрос спустя 3+ часа после создания переводит её на полный срок (14 дней).
• Рекомендация: опрашивайте фильтр не реже раза в сутки. Если подписка умерла, ваш курсор вернёт 409 со свежим срезом — события за пропущенный период будут недоступны.

Состояния ответа

Под пиковой нагрузкой на поиск API не отказывает, а отвечает 202 preparing. С частотой запросов это не связано: 429 приходит от ограничителей частоты — вашего минутного лимита на аккаунт (Retry-After: 60) или лимита всплесков по IP (Retry-After: 1). Параллельная выгрузка в несколько потоков упирается во второй раньше. Оба отвечают обычным JSON-конвертом ошибки.

Конверт ответа QUERY

{
  "filter_id": "flt_6a40ebde3711b9b2",
  "state": "ready",
  "applied": { "events": ["created"], "status": ["active"] },
  "results": [
    { "event": "created", "version": 1, "billed": true,
      "tender": {
        "id": 4821337,
        "etp_id": "0173200001425000456",
        "name": "Ремонт кровли школы №12",
        "price": 4850000.0,
        "publish_date": "2026-08-01T09:00:00Z",
        "start_date": "2026-08-01T09:00:00Z",
        "end_date": "2026-08-14T23:59:00Z",
        "update_date": "2026-08-05T12:30:00Z",
        "end_date_computed": false,
        "positions_inserted": 10,
        "source_url": "https://zakupki.gov.ru/…",
        "region": { "id": 1, "name": "Москва" },
        "platform": { "id": 3, "name": "РТС-тендер" },
        "placement_type": { "id": 7, "name": "Электронный аукцион" },
        "purchase_type": { "id": 1, "name": "Закупка по 44ФЗ" },
        "status": { "id": 1, "name": "Подача заявок" },
        "organization": { "name": "ГБОУ Школа №12", "inn": "7707083893",
                          "kpp": "770701001", "ogrn": "1037739…" }
      } }
  ],
  "next_cursor": "cur_eyJ…",
  "total": 5000,
  "billed": { "created": 50, "updated": 0, "free": 0,
              "period_total": 50, "balance_exhausted": false },
  "expires_at": "2026-08-12T09:00:00Z"
}

Про поля конверта, о которые чаще всего спотыкаются:

• applied — что API реально применил после нормализации. Форма непостоянна: у запроса критериями там есть status, у запроса с list_id или ids — нет, а у контрактной ленты появляется status: ["completed"], хотя параметра status у контрактов не существует. Полезен как проверка «меня правильно поняли»: лишнее поле верхнего уровня в запросе игнорируется молча, и разойтись с ожиданием можно тихо.
• total — справочное число: сколько закупок сейчас подходит под фильтр («столько в базе под эти условия»), а не размер вашей выборки. Считается фоном, не в момент запроса: отдельная задача пересчитывает каждый фильтр раз в несколько минут, а запрос отдаёт последнее посчитанное значение — поэтому total не замедляет ответ и поэтому же он живой. Между двумя запросами число меняется, в том числе прямо во время листания: гарантии «показали 693 — вытащите ровно 693» нет. Конец выборки по total не определяют — конец это пустой results (next_cursor пустым не бывает никогда: лента живая, и по тому же курсору позже приедут новые тендеры). Может быть null, и это нормальный ответ, а не ошибка — клиент обязан его переживать: фильтр слишком тяжёлый, чтобы его считать (например, «все завершённые» — миллионы записей), лента ещё собирается (preparing или partial), поток updated (конечного числа там не существует) или значение ещё ни разу не посчитано. Исключение — запрос по ids или по сохранённому списку (list_id): там total точный, это размер списка.
• freshness.last_polled_at (только контрактная лента) — честная нижняя граница момента, когда мы последний раз опрашивали источник по этому множеству.
• request_id в теле успешного ответа не приходит — он отдаётся заголовком X-Request-Id. В теле ошибок он дополнительно лежит в error.request_id, и по нему же сходятся строки GET /balance/ledger.

Что лежит в results[] — объект целиком

Элемент ленты — это конверт события {event, version, billed} и весь списочный объект в поле tender (у контрактов — contract). Отдельный GET на каждый результат делать не нужно: он ничего не добавит, кроме позиций, документов, лотов и полной организации, зато потратит запросы.

Поля tender в ленте: id, etp_id (бывает null — у части агрегированных лотов нет id на исходной площадке, не вешайте NOT NULL), name, price (число, валюты нет), publish_date, start_date, end_date, update_date, end_date_computed, positions_inserted (сколько у закупки позиций; сами позиции отдаёт карточка), source_url, advance (размер аванса по контракту, % от цены, 0–100; не обеспечение заявки или контракта; 0 — аванса нет или не указан, заполняется только у закупок из ЕИС), region {id, name}, platform {id, name}, placement_type {id, name} (способ размещения), purchase_type {id, name} (закон: 44ФЗ/223ФЗ/…), status {id, name} — объект, не строка, organization {name, inn, kpp, ogrn}.

Поля contract в ленте: id, reestr_number, contract_id, notice_number, name, price, currency — объект {code, name}, а не строка, contract_type {id, name}, conclusion_date, execution_date, registry_date, changed_at, status (здесь как раз строка, в отличие от тендера), suppliers[] (name, inn, kpp, country_code, address, postal_address, phone, email, status), source_url и tender — усечённый блок родительской закупки {id, etp_id, name}, а не закупка целиком: за остальным идите в GET /tenders/{id}.

GET /tenders/{id} и GET /contracts/{id} отвечают тем же конвертом ({event, version, billed, tender|contract}), а не плоским объектом.

Карточка тендера добавляет: lots[] {ordinal, title, price}, positions[], positions_total/positions_page/positions_page_size/positions_pages, documents[] {title, link, extension}, documents_total, purchase_plan_id, placement_type, purchase_type и организацию с address и administrator (последний бывает null). Позиция — {lot_ordinal, position_ordinal, title, characteristics, quantity, unit, price, amount, okpd2 {code, name}, ktru}; ktru бывает null, а okpd2 приходит объектом даже когда кода нет: {"code": null, "name": null}.

Карточка контракта добавляет: positions[] и positions_total/positions_page/positions_page_size/positions_pages (страница задаётся positions_page/positions_limit), documents[], documents_total, execution, customer, а также ikz, plan_position_number, result_date, penalty_withholding, version_number, is_changed, changed_fields. Позиция контракта — {position_ordinal, title, characteristics, quantity, unit, price, amount, okpd2, ktru, nds, mnn, is_vital_drug}.

Список живёт до явного удаления. DELETE /lists/{list_id} убирает его вместе с составом и гасит подписку на ленту фильтра-над-списком. Уже доставленные объекты остаются доставленными — повторно за них деньги не списываются. PATCH нет: поля после создания неизменяемы, меняется только состав.

Состав проверяется. POST /lists/{list_id}/items с несуществующим tender_id отвечает 400 validation_error («ids: unknown tender ids [...]») и не применяет пакет частично — либо входят все id, либо ни одного.

Коллекции (/lists, /filters, /balance/ledger) отвечают другим конвертом: { "data": [...], "has_more": false, "next_cursor": null }, продолжение — параметром starting_after. У GET /lists/{list_id} этот конверт вложен в поле items, а items.data — просто массив tender_id (числа, без дат добавления).

Биллинг

Оплата пообъектная, лицензий и суточных лимитов нет. Балансы раздельные: tenders и contracts.

• Тарифицируется первая доставка версии объекта, а не запрос: пустые ответы, поллинг и ретраи той же страницы бесплатны. Повторное получение того же объекта (тот же фильтр, другой фильтр, карточка, повтор курсора) — бесплатно, billed: false.
• Платны оба события — created и updated (каждая новая версия).
• Тендеры, исключённые из выдачи из-за смены статуса, не списываются.
• Поле total — справочная фоновая оценка «сколько сейчас подходит под фильтр», а не счётчик оплаченного и не размер выборки; бывает null. Планировать расходы по нему нельзя: платите вы за то, что реально пролистали.
• Оплата постранично: нашли 5000, забрали две страницы по 50 — заплатили за 100. Глубину пагинации контролирует клиент.
• Дедуп между фильтрами: объект под двумя вашими фильтрами тарифицируется один раз.
• GET /tenders/{id} и GET /contracts/{id} списывают, только если эта версия вам ещё не доставлялась.
• При нехватке баланса страница отдаётся частично: billed.balance_exhausted: true, next_cursor указывает перед первым неоплаченным объектом, HTTP 200. Если доставить не удалось ничего — 402 balance_exhausted. После пополнения чтение продолжается с того же места без потерь и дублей.
• Документы объекта, который вам уже доставлен, скачиваются бесплатно — сколько угодно раз. Если объект ещё не доставлялся, первое скачивание его документа тарифицируется как доставка самого объекта (одна единица), после чего остальные его документы бесплатны.
• Каждое списание объяснимо построчно: GET /balance/ledger (объект, версия, фильтр, request_id).

Документы закупок и контрактов

У тендера и контракта есть прикреплённые файлы — документация, ТЗ, проекты контрактов, акты. Они приходят в карточке объекта (GET /tenders/{id}, GET /contracts/{id}) в массиве documents[]; в ленте (QUERY) документов нет.

{
  "ordinal": 1,
  "title": "Приложение 3. Обоснование НМЦК",
  "extension": "xlsx",
  "link": "https://zakupki.gov.ru/44fz/filestore/public/1.0/download/priz/file.html?uid=…",
  "id": "d6e9f213bc379a60315d1",
  "download_url": "https://downloads.fraim.ru/f/MzQ6ZDZlOWYyMTNiYzM3…"
}

Качайте по download_url, а не по link. link — это адрес у первоисточника (ЕИС, электронная площадка, сайт заказчика): он может быть недоступен, отдать HTML-страницу вместо файла или потребовать входа на площадку. download_url ведёт на наш сервер и отдаёт файл с корректным именем, а недавно скачанный — из нашего кеша, без обращения к источнику. Но сам файл живёт у первоисточника: если он его убрал, документ не отдаст ни одна из ссылок (410 document_gone).

Две двери к одному файлу

1. Готовая ссылка (download_url). Постоянная, персональная, без срока годности и без заголовка Authorization — её можно открыть в браузере, положить в письмо, в задачу или в CRM. Сама ссылка бессрочна, но ведёт за файлом к первоисточнику, а он свои файлы иногда убирает: нужен документ надолго — храните файл, а не ссылку. Ссылка подписана для вашего аккаунта: по чужой ссылке ваш документ не скачают, и наоборот.

2. Bearer (для серверного кода).

GET https://downloads.fraim.ru/d/{document_id}
Authorization: Bearer fraim_live_…

Тот же файл по id документа из карточки. Рядом — GET https://downloads.fraim.ru/d/{document_id}/meta: состояние документа (state, filename, size, content_type, sha256) без скачивания.

Оплата

Документы объекта, который вам уже доставлен, — бесплатны, сколько угодно раз. Если объект ещё не доставлялся, первое скачивание его документа тарифицируется как доставка объекта (одна единица соответствующего баланса), дальше все его документы бесплатны. При нулевом балансе — 402 balance_exhausted.

Когда файла нет

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

Ни один из этих ответов не списывает баланс.

Ограничения

• Скачивание тестовым токеном (fraim_test_…) недоступно: 409 document_unavailable_in_sandbox — в песочнице демо-данные, а файлы лежат у боевых источников.
• Формат ошибок тот же, что у API: тело вложено в detail.
• id документа стабилен, пока у объекта не изменился состав документов; надёжный порядок работы — брать свежую карточку и download_url из неё.

Типовые сценарии

1. Разовый поиск закупок

POST /tenders/query с критериями → читайте results, при необходимости следующая страница по next_cursor. Ограничивайте выдачу критериями, а не пагинацией: каждая страница платная.

2. Мониторинг новых закупок (основной сценарий)

1. Первый запрос с критериями — получаете первый срез и next_cursor.
2. Сохраняете только next_cursor.
3. По расписанию (например, раз в 5–15 минут) шлёте {"cursor": "<сохранённый>"}. Реже раза в сутки опрашивать нельзя — умрёт подписка.
4. Пустой results — нормально и бесплатно; next_cursor обновляете всегда.
5. 409 cursor_expired — не ошибка: свежий срез и новый курсор уже в теле, под ключом detail (detail.results, detail.next_cursor).

3. Отслеживание изменений

То же самое, но events задаётся в первом запросе: "events": ["created","updated"], если нужны и новые, и изменившиеся, или ["updated"] — только изменения. Дальше значение зашито в курсор и в теле игнорируется; сменить набор потоков можно только начав ленту заново. Потоки независимы — держите по курсору на каждый.

4. Контракты поставщика или заказчика по ИНН

• Контракты конкретного поставщика: POST /contracts/query с {"supplier": {"inn": ["…"]}}.
• Контракты заказчика: те же критерии закупок — {"customer": {"inn": ["…"]}}.
• Можно переиспользовать filter_id тендерного фильтра: передайте его в POST /contracts/query явно — контрактная проекция того же множества соберётся. status на контрактную выдачу не влияет, отдельный фильтр «со status completed» заводить не нужно.
• Но filter_id в ответах двух лент совпадает не всегда. В контрактный хеш всегда входит status: ["completed"], а тендерный по умолчанию берёт ["active"] — поэтому одно и то же тело даёт разные id. Пошлите в /tenders/query явный status: ["completed"] — и id совпадут. Не сравнивайте id двух ответов вслепую: идентификатором множества служит тот, что вы передали сами.
• Первое обращение к контрактной проекции может вернуть 202 preparing — повторите.

5. Свой список объектов

POST /lists (нужен Idempotency-Key) → POST /lists/{list_id}/items → дальше POST /tenders/query с {"list_id": "…"}: над списком работает такая же лента, как над критериями.

Рабочие примеры

Поиск (curl)

curl -X POST https://public.fraim.ru/api/v2/tenders/query \
  -H "Authorization: Bearer $FRAIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["ремонт кровли", "асфальт"],
    "exception_keywords": ["ямочный"],
    "regions": [1],
    "price": {"from": 100000, "to": 5000000},
    "status": ["active"],
    "limit": 50
  }'

Продолжение ленты (curl)

curl -X POST https://public.fraim.ru/api/v2/tenders/query \
  -H "Authorization: Bearer $FRAIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cursor": "cur_eyJ…", "limit": 50}'

Цикл мониторинга (Python)

import os, time, requests

API = "https://public.fraim.ru/api/v2"
H = {"Authorization": f"Bearer {os.environ['FRAIM_TOKEN']}"}

def poll(cursor):
    """Один шаг ленты. Возвращает (события, новый курсор)."""
    body = {"cursor": cursor} if cursor else {
        "keywords": ["асфальт"], "regions": [1], "status": ["active"], "limit": 100,
    }
    r = requests.post(f"{API}/tenders/query", json=body, headers=H, timeout=60)

    if r.status_code == 202:                       # идёт сбор — тот же запрос позже
        time.sleep(r.json().get("retry_after", 5))
        return [], cursor
    if r.status_code == 429:                       # лимит частоты: минутный (60)
        time.sleep(int(r.headers.get("Retry-After", 60)))   # или всплеск (1)
        return [], cursor
    if r.status_code == 409:                       # лента пересобрана: срез уже в теле,
        body = r.json()["detail"]                  # но под detail, а не наверху
        return body["results"], body["next_cursor"]
    if r.status_code == 402:                       # баланс кончился
        raise SystemExit(r.json()["detail"]["error"]["message"])

    r.raise_for_status()
    data = r.json()
    if data["billed"]["balance_exhausted"]:
        raise SystemExit("баланс исчерпан — пополните и продолжите с того же курсора")
    return data["results"], data["next_cursor"]

cursor = None
while True:
    events, cursor = poll(cursor)               # cursor сохраняйте в свою БД
    for e in events:
        upsert(e["tender"], version=e["version"])   # дедуп по (id, version)
    time.sleep(300)

Контракты поставщика по ИНН (Node.js)

const res = await fetch("https://public.fraim.ru/api/v2/contracts/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FRAIM_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ supplier: { inn: ["7701234567"] }, limit: 100 }),
})
if (res.status === 202) {
  // проекция контрактов ещё собирается — повторить тот же запрос
}
const { results, next_cursor } = await res.json()

Создание списка (мутация с Idempotency-Key)

KEY=$(uuidgen)   # один ключ на операцию, тот же при ретрае
curl -X POST https://public.fraim.ru/api/v2/lists \
  -H "Authorization: Bearer $FRAIM_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Проект Юг", "metadata": {"project_id": 42}}'

Справочник эндпоинтов

Всего маршрутов: 17 — все ниже, сгенерированы из OpenAPI-схемы. Ответ 422 (ошибка валидации тела) возможен у любого маршрута с параметрами и ниже не повторяется.

Auth

GET /auth/tokens — Список API токенов

Получить список всех API токенов пользователя

POST /auth/tokens — Создать API токен (для API V2)

Создаёт бессрочный API-токен — его и используют в своём коде. Требует авторизации: подойдёт сессия или уже имеющийся токен. Секрет возвращается один раз, повторно его не показать. Активных токенов у пользователя не больше 20: на следующем приходит 409 api_key_limit_reached, отзовите ненужный через DELETE /auth/tokens/{token_id}. Лимит частоты запросов считается на пользователя, а не на токен, — выпуск дополнительных токенов частоту не увеличивает.

Тело запроса — application/json, схема TokenCreateRequest:

DELETE /auth/tokens/{token_id} — Удалить API токен

Деактивирует API токен. Удалять можно только свои токены; на чужой или несуществующий id — 404. token_id = 0 — заглушечный id сессии кабинета. Успех и no-op он даёт только когда запрос сделан САМОЙ сессией (отзывать нечего). Тот же запрос с API-токеном получит 404: строки с таким id в реестре ключей нет.

Tenders

POST /tenders/query — Поиск и лента тендеров

Единственный способ найти тендеры и следить за изменениями по ним. Ровно один способ задать множество: критерии поиска (keywords/regions/platforms/price/publish_date/customer_inn/status/ids) | filter_id | list_id — смешение способов даёт 400. Курсор из предыдущего ответа продолжает тот же поток событий (created/updated), заданный при первом запросе; events из тела игнорируется, если передан курсор. Ключевые слова ищутся по нормализованным словам, а не по подстроке: «поставка насосов» находит «поставку насоса». Многословный элемент keywords — фраза (слова должны встретиться вместе), разные элементы списка — ИЛИ. Слова короче 3 символов в поиске не участвуют — вместе с годами (2000–2099) и служебными частями речи они молча выбрасываются: ["насос жд"] ищется как ["насос"], ["жд"] теперь отвечает 400 (искать нечего), а короткое минус-слово ничего не исключает. Что именно выброшено — в поле ignored_keywords ответа. Слишком общие слова не принимаются. Однословный элемент keywords из стоп-листа выбрасывается — он не сужает выборку; внутри фразы из нескольких слов такое слово остаётся. Список целиком (сверка по начальной форме): адрес, вид, выполнение, год, закупка, заявка, использование, количество, лот, назначение, наличие, номер, нужда, обеспечение, область, общий, объем, оказание, описание, определение, поставка, применение, проведение, работа, размер, соответствие, тип, услуга, форма, часть, являться. Если после этого искать нечего — 400. keywords обязателен, если множество не задано через ids/list/supplier/customer_*; exception_keywords — только вместе с непустым keywords. Выдача — живой список, а не снапшот. Каждая страница отражает состояние тендеров на момент запроса: при status: ["active"] в ней только активные прямо сейчас, а завершившийся тендер исчезает из выдачи сам и баланс за него не списывается. Поэтому повторный запрос с тем же курсором может вернуть меньше объектов или те же объекты с обновлёнными данными — это нормально. Дедупликация на вашей стороне — по паре id + version, а не по составу страницы. Пустой results с next_cursor — валидный ответ, а не конец ленты: «на этом отрезке сейчас нет подходящих объектов, продолжайте с нового курсора». Пустые ответы бесплатны. Гарантии. Каждое событие доставляется не более одного раза: повтор со старым курсором не даёт ни дублей, ни повторных списаний. События не теряются — всё, что появилось после вашей позиции, выдастся при следующих чтениях (в пределах срока жизни подписки, см. GET /filters). Не доставляется только тендер, который вошёл в фильтр и вышел из него между вашими опросами. В results[].tender объект приходит целиком (name, price, даты, region, platform, status, organization) — GET /tenders/{id} на каждый элемент ленты делать не нужно.

Тело запроса — application/json, схема TenderQueryRequest:

GET /tenders/{tender_id} — Карточка тендера

Полная информация об одном тендере: описание, лоты, позиции (постранично: positions_page/positions_limit, с okpd2/ktru), документы. Структура объекта — как в старом API v2 (эталон). id_type=internal (по умолчанию) — внутренний id, id_type=external — id закупки на площадке (etp_id). Списание — только если версия объекта ещё не доставлялась (общая дедупликация с лентами QUERY /tenders). Ответ завёрнут в тот же конверт события, что и элемент ленты: {event, version, billed, tender}, а не плоский объект. Ходить сюда за каждым элементом ленты не нужно. В results[].tender у QUERY /tenders объект уже целиком; карточка добавляет ровно то, чего в ленте нет: lots, positions[] + positions_total/page/page_size/pages, documents[] (ordinal/title/link/id/download_url/extension) + documents_total, purchase_plan_id и организацию с address и administrator (placement_type/purchase_type с 12.08.2026 и advance с 10.09.2026 есть и в ленте). Документы качаются через наши сервера. download_url — постоянная персональная ссылка на downloads.fraim.ru: работает без заголовка авторизации, срока годности нет. Тот же документ доступен по GET https://downloads.fraim.ru/d/{id} с обычным Bearer-токеном, состояние без скачивания — …/d/{id}/meta. Документы уже доставленного объекта бесплатны; если объект ещё не доставлялся, первое скачивание тарифицируется как его доставка. Недоступный у источника документ отвечает document_gone / document_restricted_at_source / document_temporarily_unavailable, а не 500.

Contracts

POST /contracts/query — Контракты по множеству закупок

Ровно один способ задать множество: критерии закупок (те же поля, что у QUERY /tenders, без ids) | filter_id | list_id | tender_ids (разово) | supplier (подписка на контракты поставщика по ИНН/названию — у такого фильтра нет тендерной проекции). Поиска по остальным полям контракта не существует как операции. Критерии закупок дают тот же filter_id, что и QUERY /tenders с теми же параметрами. supplier вместе с другим способом — пост-фильтр выдачи по поставщику (в filter_id не входит, повторяйте в каждом запросе). Первое обращение может вернуть preparing, пока не отработает contracts poller. Контракты ищутся по тематике фильтра (ключевые слова, регионы, заказчик и т.д.). Параметр status на контрактную выдачу НЕ влияет: один и тот же filter_id годится и для мониторинга активных тендеров, и для получения контрактов по завершившимся закупкам той же темы — отдельный фильтр «со status completed» ради контрактов заводить не нужно. Исключение: у фильтра, заданного ТОЛЬКО статусом (без тематических критериев), контрактная проекция работает по прежним правилам. Контракт публикуется площадкой через несколько дней после завершения закупки и появляется в ленте в течение суток+ после публикации. В results[].contract объект приходит целиком (включая suppliers и блок родительской закупки tender) — GET /contracts/{id} на каждый элемент ленты делать не нужно.Ключевые слова работают так же, как у QUERY /tenders: поиск по нормализованным словам, слова короче 3 символов (а также годы и предлоги) в поиске не участвуют.

Тело запроса — application/json, схема ContractQueryRequest:

GET /contracts/{contract_id} — Карточка контракта

Полная информация об одном контракте, включая позиции (курсор positions_page/positions_limit), поставщиков, исполнение. id_type=internal (по умолчанию) — внутренний id, id_type=reestr — реестровый номер. Списание — только если версия ещё не доставлялась (общая дедупликация с лентой QUERY /contracts). Ответ завёрнут в конверт события: {event, version, billed, contract}, а не плоский объект. Документы качаются через наши сервера. У каждого документа в documents[] есть id и download_url — постоянная персональная ссылка на downloads.fraim.ru (без заголовка авторизации и без срока годности); link по-прежнему ведёт на источник. Документы уже доставленного контракта бесплатны. Подробности и коды ошибок недоступного документа — в описании карточки тендера.

Lists

GET /lists — Мои списки

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

POST /lists — Создать список

Персональная изменяемая коллекция тендеров без TTL — живёт до явного удаления через DELETE /lists/{list_id}. Поля после создания неизменяемы (PATCH нет); состав меняется через POST/DELETE /lists/{list_id}/items.

Тело запроса — application/json, схема ListCreateRequest:

GET /lists/{list_id} — Детали и состав списка

Метаданные списка + состав. Состав лежит во ВЛОЖЕННОМ конверте коллекции items (data/has_more/next_cursor), а не полями верхнего уровня; items.data — просто массив tender_id (числа), момент добавления не отдаётся. Продолжение — starting_after = последний tender_id страницы.

DELETE /lists/{list_id} — Удалить список

Удаляет список целиком вместе с его составом. Гасит и вашу подписку на ленту фильтра-над-списком, если она была. Сам фильтр (общий кеш параметров) остаётся — его чистит TTL-пруннинг, как и у DELETE /filters/{filter_id}. Уже доставленные объекты остаются доставленными: повторно за них деньги не списываются, а история списаний в /balance/ledger не переписывается.

POST /lists/{list_id}/items — Добавить тендеры в список

Идемпотентно — повторное добавление существующего id не создаёт дублей. Долив в тендерную ленту фильтра-над-списком синхронный: добавленный тендер сразу виден через QUERY /tenders/contracts {list_id}.

Тело запроса — application/json, схема ListItemsRequest:

DELETE /lists/{list_id}/items — Убрать тендеры из списка

Идемпотентно. Уже доставленное остаётся доставленным (не отзывается); будущие события убранного тендера в ленты списка не попадают.

Тело запроса — application/json, схема ListItemsRequest:

Filters

GET /filters — Мои живые подписки

Отладочная обвязка, не happy path — фильтры создаются только неявно любым QUERY. Срок жизни подписки. Подписка продлевается ЛЮБЫМ чтением и живёт 14 дней от последнего запроса (expires_at в ответе). Новая подписка первые сутки живёт в пробном режиме: если запрос не повторить в течение 24 часов, она удаляется; первый же запрос спустя 3+ часа после создания переводит её на полный срок. Рекомендация — опрашивать фильтр не реже раза в сутки: если подписка умерла, курсор вернёт 409 со свежим срезом, а события за пропущенный период будут недоступны.

DELETE /filters/{filter_id} — Погасить подписку досрочно

Сам фильтр (общий кеш параметров) не удаляется — гасится только ваша персональная подписка на него.

Balance

GET /balance — Баланс и расход за сегодня

Баланс по типам (tenders/contracts) и количество тарифицированных доставок за текущие сутки (справочно, НЕ лимит). Валюты нет: единица баланса — одна доставленная версия объекта.

GET /balance/ledger — Журнал списаний

Каждая строка — одна тарифицированная доставка: объект, версия, фильтр, request_id. Курсорная пагинация: starting_after = id последней строки (целое число, оно же приходит в next_cursor).

Схемы объектов

Вложенные объекты фильтров и модели ответов, на которые ссылается справочник выше. Тела ответов QUERY-эндпоинтов схемой не описаны — их структура показана в разделе «Конверт ответа QUERY».

CustomerFilter

Заказчик/организатор ЗАКУПКИ (единый стиль с supplier — вложенный объект). inn — список (мониторинг нескольких заказчиков — обычный кейс). extra=forbid: незнакомое поле (напр. kpp) — явный 422, не молчаливое игнорирование.

DateRangeFilter

ListCreated

Ответ POST /lists.

ListDeleted

Ответ DELETE /lists/{list_id}.

ListItemsAdded

Ответ POST /lists/{list_id}/items.

ListItemsRemoved

Ответ DELETE /lists/{list_id}/items.

RangeFilter

SupplierFilter

Поставщик контракта (единый стиль с customer — вложенный объект, inn — список, name — подстрока названия). Поставщик существует только в контракте — на множество ЗАКУПОК не влияет и в filter_id обычных фильтров не входит (ТЗ §6); сам по себе — supplier-режим (§6.1). ogrn (в отличие от customer) отсутствует: у поставщиков в БД нет ОГРН — матчить не по чему (резолв через справочник организаций покрыл бы ~2% поставщиков). kpp удалён 20.07.2026 ради симметрии с customer. Требуется хотя бы одно из inn/name (иначе 400).

TokenDeleteResponse

Ответ при удалении токена

TokenInfo

Информация о токене с маскированным превью

TokenListResponse

Список токенов

TokenResponse

Ответ с секретом — и при создании токена, и при входе (сессия)

Справочники кодов

Значения для regions, platforms, placement_types, purchase_types. Это внутренние id Fraim.ru: не ОКАТО, не коды регионов на автомобильных номерах, не коды ЕИС. Отдельного маршрута справочников у API нет и не планируется — коды берите отсюда либо одним файлом: https://fraim.ru/refs.json. Снимок сверен с боевым API 2026-08-09; те же таблицы с поиском — в личном кабинете: https://lk.fraim.ru/refs.

Если нужного значения здесь нет, посмотрите его в самой выдаче: объекты несут region {id, name} и platform {id, name}, карточка тендера — placement_type и purchase_type.

Регионы — regions

Нумерация внутренняя: это НЕ ОКАТО, не коды на автомобильных номерах и не коды ЕИС. Москва — 1, Санкт-Петербург — 34, а 77 — Республика Бурятия.

Пример: "regions": [1]

Площадки (ЭТП) — platforms

Здесь наиболее используемые площадки; всего их в индексе несколько сотен. Код нужной площадки всегда виден в поле platform {id, name} любой выдачи.

Справочник неполный: перечислены ходовые значения, а не все.

Пример: "platforms": [2]

Типы закупки — purchase_types

Закон или режим, по которому проводится закупка.

Пример: "purchase_types": [1]

Способы размещения — placement_types

Форма процедуры. Приходит в карточке тендера полем placement_type.

Пример: "placement_types": [7]

Коды ошибок

Тело ошибки вложено в detail (так его отдаёт FastAPI):

{ "detail": { "error": { "type": "invalid_request_error",
                         "code": "validation_error",
                         "message": "…",
                         "param": "cursor",
                         "request_id": "req_…" } } }

Форма одна для всех кодов, включая 422 и оба вида 429 — исключений нет. Особый случай один — 409 cursor_expired: в его detail лежит не только error, но и свежий срез ленты — detail.state, detail.results, detail.next_cursor.

request_id возвращается заголовком X-Request-Id в каждом ответе — и в успешном тоже, — а в теле ошибок ещё и полем error.request_id (значение то же). По нему же сходятся строки GET /balance/ledger. Если пришлёте свой X-Request-Id в запросе, API вернёт его: сквозная трассировка работает. Ровно одно место без него — отказ лимитера всплесков: он формируется до приложения, поэтому там request_id: null и заголовка нет. Опознать его можно по Retry-After: 1 и сообщению burst limit exceeded.

Обращения по ошибкам — на support@fraim.ru, с request_id из ответа.

Лимиты

Частые ошибки агентов

Ссылки

• Этот документ в Markdown: https://fraim.ru/ai.md
• Карта документации для ИИ: https://fraim.ru/llms.txt
• Справочники кодов одним JSON: https://fraim.ru/refs.json
• OpenAPI 3.1: https://public.fraim.ru/api/v2/openapi.json
• Документация для людей: https://fraim.ru/docs
• Регистрация и токены: https://lk.fraim.ru
• Поддержка: support@fraim.ru (в письме укажите request_id из ответа)
• Любые вопросы: info@fraim.ru