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

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

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

• Base URL: https://public.fraim.ru/api/v2
• Версия API: 2.0.0 (OpenAPI 3.1.0, снапшот схемы от 2026-08-05)
• Этот документ одним файлом: https://api.fraim.ru/ai.md
• Машинная схема (OpenAPI 3.1): https://public.fraim.ru/api/v2/openapi.json
• Документация для людей: https://api.fraim.ru/docs
• Личный кабинет (токены, баланс, песочница): https://lk.api.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. 202 preparing — не ошибка: идёт фоновый сбор. Повторите тот же запрос через retry_after секунд. state: "partial" в 200-ответе значит «читать уже можно, лента ещё дособирается».
7. Тарифицируется первая доставка версии объекта, а не запрос. Лишняя пагинация «на всякий случай» стоит денег; пустые ответы и повторы бесплатны.
8. На мутациях (POST/DELETE) заголовок Idempotency-Key обязателен — иначе 400 idempotency_key_required. Кладите UUID v4 и повторяйте его при ретрае.
9. При 429 дождитесь Retry-After и повторите. Лимит считается на аккаунт, а не на токен: заводить новые токены ради частоты бессмысленно.
10. Не пытайтесь логиниться по email-коду: /auth/request-code и /auth/login-code — вход человека в кабинет, они отдают сессию на 30 дней. Агенту нужен вечный API-токен (fraim_live_…) из кабинета или POST /auth/tokens.
11. Дедуплицируйте у себя по паре id + version. Поле billed отвечает на вопрос «списали ли деньги», а не «видел ли я этот объект».
12. Даты — ISO-8601. По умолчанию status: ["active"] и events: ["created"]; ленту изменений включайте явно.

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

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

Authorization: Bearer fraim_live_…

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

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

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

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

Маршруты входа человека в кабинет (/auth/request-code, /auth/login-code) в этой документации и в OpenAPI-схеме отсутствуют намеренно: они отдают сессию на 30 дней, для интеграции она не годится.

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

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

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

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

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

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

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

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

Под пиковой нагрузкой API не отказывает, а отвечает 202 preparing; 429 означает только ваш лимит, но не перегрузку сервиса.

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

{
  "filter_id": "flt_8a3c9d12",
  "state": "ready",
  "applied": { "events": ["created"], "status": ["active"] },
  "results": [
    { "event": "created", "version": 1, "billed": true,
      "tender": { "id": 4821337, "etp_id": "0173…" } }
  ],
  "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"
}

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

Биллинг

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

• Тарифицируется первая доставка версии объекта, а не запрос: пустые ответы, поллинг и ретраи той же страницы бесплатны.
• Платны оба события — created и updated (каждая новая версия).
• Оплата постранично: нашли 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).

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

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 — не ошибка: в теле уже лежит свежий срез и новый курсор, продолжайте с него.

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

То же самое, но при первом запросе "events": ["updated"]. Потоки created и updated независимы — держите по курсору на каждый.

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

• Контракты конкретного поставщика: POST /contracts/query с {"supplier": {"inn": ["…"]}}.
• Контракты заказчика: те же критерии закупок — {"customer": {"inn": ["…"]}}.
• Первое обращение к контрактной проекции может вернуть 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": [77],
    "okpd2": ["42.11"],
    "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": [77], "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:                       # свой лимит частоты
        time.sleep(int(r.headers.get("Retry-After", 60)))
        return [], cursor
    if r.status_code == 409:                       # лента пересобрана: срез уже в теле
        data = r.json()
        return data["results"], data["next_cursor"]

    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}}'

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

Всего маршрутов: 16. Сгенерировано из 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 соответствует сессии из POST /auth/login: отзывать нечего, запрос возвращает успех и ничего не меняет.

Tenders

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

Единственный способ найти тендеры и следить за изменениями по ним. Ровно один способ задать множество: критерии поиска (keywords/regions/platforms/price/publish_date/customer_inn/status/ids) | filter_id | list_id — смешение способов даёт 400. Курсор из предыдущего ответа продолжает тот же поток событий (created/updated), заданный при первом запросе; events из тела игнорируется, если передан курсор.

Тело запроса — 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).

Contracts

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

Ровно один способ задать множество: критерии закупок (те же поля, что у QUERY /tenders, без ids) | filter_id | list_id | tender_ids (разово) | supplier (подписка на контракты поставщика по ИНН/названию — у такого фильтра нет тендерной проекции). Поиска по остальным полям контракта не существует как операции. Критерии закупок дают тот же filter_id, что и QUERY /tenders с теми же параметрами. supplier вместе с другим способом — пост-фильтр выдачи по поставщику (в filter_id не входит, повторяйте в каждом запросе). Первое обращение может вернуть preparing, пока не отработает contracts poller.

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

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

Полная информация об одном контракте, включая позиции (курсор positions_page/positions_limit), поставщиков, исполнение. id_type=internal (по умолчанию) — внутренний id, id_type=reestr — реестровый номер. Списание — только если версия ещё не доставлялась (общая дедупликация с лентой QUERY /contracts).

Lists

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

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

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

Персональная изменяемая коллекция тендеров без TTL — живёт до явного удаления.

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

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

Метаданные списка + состав (tender_id, курсорная пагинация).

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.

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

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

Balance

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

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

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

Каждая строка — одна тарифицированная доставка: объект, версия, фильтр, request_id. Курсорная пагинация.

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

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

CustomerFilter

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

DateRangeFilter

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

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

Коды ошибок

Тело ошибки: {"error": {"code": "…", "message": "…", "request_id": "…"}}. request_id есть в каждом ответе и в журнале списаний — указывайте его в обращениях в поддержку.

Лимиты

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

Ссылки

• Этот документ в Markdown: https://api.fraim.ru/ai.md
• Карта документации для ИИ: https://api.fraim.ru/llms.txt
• OpenAPI 3.1: https://public.fraim.ru/api/v2/openapi.json
• Документация для людей: https://api.fraim.ru/docs
• Регистрация и токены: https://lk.api.fraim.ru