Бесплатный просмотр · прямой контакт с продавцом · без посредников
Латвия
RU
Рубрики

Документация API

Получить API-ключ

JSON REST API для объявлений, кандидатов и статистики. Цены в евро, время в формате ISO 8601.

Сотрудничество, реклама и API: partners@baltic-market.org

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

Добавляйте к каждому запросу заголовок Authorization с ключом из раздела «Интеграции». Храните ключи на сервере.

curl https://baltic-market.org/api/v1/me \
  -H "Authorization: Bearer tg_live_…"

Лимит: 120 запросов в минуту на аккаунт, для всех ключей вместе (заголовки X-RateLimit-*).

Безопасные повторы

Добавляйте к POST-запросам заголовок Idempotency-Key (до 100 символов). Если соединение оборвалось и запрос повторён с тем же ключом и телом, вернётся первый ответ (заголовок Idempotent-Replayed) — объявление не создастся дважды, продвижение не оплатится дважды. Ключи хранятся 24 часа.

curl -X POST https://baltic-market.org/api/v1/listings \
  -H "Authorization: Bearer tg_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: dms-order-1001" -d '{ … }'

Тело запроса — JSON-объект с правильными типами; неизвестные поля и атрибуты отклоняются с пояснением. У каждого ответа есть заголовок X-Request-Id — укажите его, обращаясь в поддержку.

Права ключей

У каждого ключа есть права, отмеченные при его создании; для чтения аккаунта (/me) и объявлений права не нужны. Новые ключи по умолчанию получают listings:write и stats:read. Давайте каждой системе или подрядчику отдельный ключ только с нужными правами. GET /api/v1/me показывает права и расходы вызывающего ключа.

listings:writeсоздавать, изменять и удалять объявления и их фото; публиковать в рамках квоты тарифа и продлевать, если продление бесплатно
credits:spendвместе с listings:write платить с баланса кредитов: платная публикация, продление, TOP место, выделение, «срочно» и поднятие наверх
applicationsчитать отклики на вакансии, включая телефон и e-mail кандидатов, и менять их этап
stats:readпросмотры, открытия контактов и сохранения по дням

У ключа может быть лимит расходов в месяц в кредитах (календарный месяц, время Латвии). Платёж сверх лимита отклоняется с 403 spend_cap_reached, а для ключа без credits:spend — с 403 insufficient_scope; ничего не списывается. Эти отказы не сохраняются для Idempotency-Key, поэтому тот же запрос, отправленный позже (через ключ с большим лимитом или в следующем месяце), обрабатывается заново. Новое объявление, которое стоило бы кредитов, тогда остаётся черновиком, причина — в поле "pending". У ключей, созданных до появления прав, есть все права и нет лимита: замените их новыми.

Объявления

GET/api/v1/listings?status=active&page=1Ваши объявления, по 50 на страницу
POST/api/v1/listingsСоздать и опубликовать
GET/api/v1/listings/:idОдно объявление
PATCH/api/v1/listings/:idИзменить цену, заголовок, описание или статус (active/inactive)
DELETE/api/v1/listings/:idУдалить
POST/api/v1/listings/:id/imagesДобавить фото (multipart-поле "photos", до 10)
DELETE/api/v1/listings/:id/images/:imageУдалить фото
POST/api/v1/listings/:id/promoteTOP, выделение, срочно, поднятие или продление за кредиты
curl -X POST https://baltic-market.org/api/v1/listings \
  -H "Authorization: Bearer tg_live_…" -H "Content-Type: application/json" \
  -d '{
    "category": "transport/cars", "deal": "sell",
    "title": "Volkswagen Golf 1.6 TDI, 2015",
    "body": "Serviced at the dealer, one owner, winter tyres included.",
    "price": 8500, "region": "riga", "city": "Purvciems",
    "attrs": { "brand": "Volkswagen", "model": "Golf", "year": 2015, "mileage": 180000, "fuel": "diesel" },
    "days": 30,
    "seller_kind": "trader",
    "trader": { "name": "Auto SIA", "reg_no": "40003000000", "address": "Brīvības iela 1, Rīga", "certified": true }
  }'

Публикация использует квоту тарифа, затем кредиты. Если их не хватает, в ответе "pending": "credits", и объявление остаётся черновиком.

Укажите, кто продаёт (Акт ЕС о цифровых услугах): "seller_kind": "private" или "trader"; компания также передаёт "trader" с названием, регистрационным номером, адресом и "certified": true — обязательством предлагать только товары и услуги, соответствующие праву ЕС. Без этого объявление остаётся черновиком (pending "seller_kind"), пока вы хотя бы раз не укажете это на сайте.

curl -X POST https://baltic-market.org/api/v1/listings/123/images   -H "Authorization: Bearer tg_live_…" -F "photos=@front.jpg" -F "photos=@interior.jpg"

curl -X POST https://baltic-market.org/api/v1/listings/123/promote   -H "Authorization: Bearer tg_live_…" -H "Content-Type: application/json"   -d '{ "top": 7, "highlight": 7, "bump": true }'

top / highlight / urgent: 7, 14 или 30 дней; renew: 7, 14, 30 или 60; bump: true. Скидка тарифа применяется, сумма в ответе — "charged".

Отклики

GET/api/v1/applications?listing=:id&page=1Отклики на ваши вакансии
PATCH/api/v1/applications/:idИзменить этап отбора {"stage": "interview"}

Статистика

GET/api/v1/meАккаунт, тариф, кредиты
GET/api/v1/stats?days=30Просмотры, контакты, сохранения по дням

Ошибки

400invalid_json · bad_requestНеверный JSON
401unauthorizedНет или неверный ключ
402insufficient_creditsНедостаточно кредитов для публикации или продвижения
403plan_required · account_disabledТариф не включает API или аккаунт заблокирован
403insufficient_scope · spend_cap_reachedУ ключа нет права, указанного в поле "scope", или платёж превысил бы его месячный лимит расходов
404not_foundНе найдено или не ваше
405method_not_allowedМетод не поддерживается (см. заголовок Allow)
409expired · not_published · auction_price_locked · withdrawn · closed · request_in_progress · invalid_status_change · not_deliverable · drafts_limitДействие невозможно в текущем состоянии
413payload_too_largeСлишком большой запрос (JSON до 100 kB, фото до 8 MB)
415unsupported_media_typeОтправляйте Content-Type: application/json
422validation_failed · idempotency_key_reused · incomplete · banned_textОшибки полей: "fields" (текст) и "codes" (коды)
429rate_limitedПревышен лимит запросов
500server_errorОшибка на нашей стороне; в ответе есть X-Request-Id — укажите его в обращении

MCP-сервер для ИИ

Подключите данные рынка Tirgus к Claude или другому MCP-клиенту: ИИ сможет искать объявления, оценивать цены, находить лучшие предложения, следить за трендами цен и находить способы заработать. Только публичные данные и только чтение — без контактов и личных данных.

search_listingsПоиск по тексту, категории, региону, цене и фильтрам
get_listingДанные объявления, оценка цены, история цен, аукцион, доверие к продавцу
check_priceХорошая ли цена? Сравнение с похожими авто, квартирами, домами, телефонами
best_offersСамая дешёвая четверть рынка и крупнейшие снижения цен
price_trendsНедельные медианные цены, снижения цен и продажи
market_overviewВесь рынок: объёмы, спрос, цены авто и квартир
find_opportunitiesПодработки, вакансии, объявления «куплю», уроки, аукционы, отдам даром
list_categoriesКатегории, фильтры и регионы

Удалённо (HTTP)

Claude: Настройки → Коннекторы → Добавить свой коннектор, и укажите этот адрес. Ключ не нужен; лимит 120 единиц в минуту: каждый запрос — 1, а check_price, best_offers, price_trends, market_overview и find_opportunities — 5. Лимит считается для каждого IPv4-адреса или IPv6-сети /48; когда сервис загружен, клиенты с несколькими запросами в минуту по-прежнему обслуживаются, и только при перегрузке ждать приходится всем (см. Retry-After).

https://baltic-market.org/mcp

Локально (stdio)

В конфигурации Claude Desktop или IDE (на копии сервера с той же базой):

{
  "mcpServers": {
    "tirgus": {
      "command": "node", "args": ["/path/to/market/scripts/mcp-stdio.js"],
      "env": { "MARKET_DB": "/path/to/market/data/production/market.db", "MARKET_ORIGIN": "https://baltic-market.org" }
    }
  }
}

Готовые подсказки: market_report, deal_hunter, earn_money.

CSV

Первая строка CSV — названия колонок; атрибуты с префиксом a_ (как в фильтрах). Несколько значений разделяйте |. Подходит запятая и точка с запятой.

category,deal,title,body,price,region,city,a_brand,a_model,a_year
transport/cars,sell,"Škoda Octavia 2.0 TDI","Serviced, new tyres, two keys.",9900,riga,Teika,Skoda,Octavia,2017