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