API dokumentacija
Gauti API raktąJSON REST API skelbimams, kandidatams ir statistikai valdyti. Kainos nurodomos eurais, laikas — ISO 8601 formatu.
Bendradarbiavimas, reklama ir API: partners@baltic-market.org
Autentifikavimas
Kiekvienoje užklausoje siųskite antraštę Authorization su raktu iš skilties „Integracijos“. Raktus laikykite savo serveryje.
curl https://baltic-market.org/api/v1/me \ -H "Authorization: Bearer tg_live_…"
Limitas: 120 užklausų per minutę vienai paskyrai, visiems raktams kartu (antraštės X-RateLimit-*).
Saugūs pakartojimai
Su POST užklausomis siųskite antraštę Idempotency-Key (iki 100 simbolių). Jei ryšys nutrūksta ir užklausą kartojate su tuo pačiu raktu ir turiniu, gausite pirmąjį atsakymą (antraštė Idempotent-Replayed): skelbimas nebus sukurtas dukart, o mokestis nebus nuskaitytas dukart. Raktai saugomi 24 valandas.
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 '{ … }'
Užklausų turinys — JSON objektai su teisingais tipais; nežinomi laukai ir atributai atmetami pateikiant paaiškinimą. Kiekviename atsakyme yra antraštė X-Request-Id — nurodykite ją kreipdamiesi į pagalbos komandą.
Raktų leidimai
Kiekvienas raktas turi leidimus, pažymėtus jį kuriant; paskyrai (/me) ir skelbimams skaityti leidimų nereikia. Nauji raktai pagal numatytuosius nustatymus gauna listings:write ir stats:read. Kiekvienai sistemai ar tiekėjui duokite atskirą raktą tik su tuo, ko reikia. GET /api/v1/me rodo kviečiančio rakto leidimus ir išlaidas.
listings:write | kurti, redaguoti ir šalinti skelbimus bei jų nuotraukas; skelbti pagal plano kvotą ir pratęsti, kai pratęsimas nemokamas |
credits:spend | kartu su listings:write mokėti iš kreditų likučio: mokamas skelbimas, pratęsimas, TOP pozicija, paryškinimas, „skubu“ ir pakėlimas į viršų |
applications | skaityti darbo paraiškas, įskaitant kandidatų telefoną ir el. paštą, ir keisti jų etapą |
stats:read | peržiūros, kontaktų atvėrimai ir išsaugojimai pagal dienas |
Raktas gali turėti mėnesio išlaidų ribą kreditais (kalendorinis mėnuo, Latvijos laikas). Mokėjimas virš ribos atmetamas su 403 spend_cap_reached, o raktui be credits:spend — su 403 insufficient_scope; niekas nenuskaitoma. Šie atmetimai nesaugomi Idempotency-Key tikslais, todėl ta pati užklausa, vėliau išsiųsta dar kartą (per raktą su didesne riba arba kitą mėnesį), apdorojama iš naujo. Naujas skelbimas, kuris kainuotų kreditų, tada lieka juodraštis, o priežastis nurodoma lauke "pending". Raktai, sukurti prieš atsirandant leidimams, turi visus leidimus ir neturi ribos: pakeiskite juos naujais.
Skelbimai
GET | /api/v1/listings?status=active&page=1 | Jūsų skelbimai, po 50 puslapyje |
POST | /api/v1/listings | Sukurti ir paskelbti |
GET | /api/v1/listings/:id | Vienas skelbimas |
PATCH | /api/v1/listings/:id | Keisti kainą, pavadinimą, aprašymą arba būseną (active/inactive) |
DELETE | /api/v1/listings/:id | Ištrinti |
POST | /api/v1/listings/:id/images | Pridėti nuotraukų (multipart laukas "photos", iki 10) |
DELETE | /api/v1/listings/:id/images/:image | Pašalinti nuotrauką |
POST | /api/v1/listings/:id/promote | TOP, paryškinimas, skubu, pakėlimas arba pratęsimas už kreditus |
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 }
}'
Skelbiant naudojama plano kvota, vėliau — kreditai. Jei kreditų nepakanka, atsakyme pateikiama "pending": "credits", o skelbimas lieka juodraštyje.
Nurodykite, kas parduoda (ES skaitmeninių paslaugų aktas): "seller_kind": "private" arba "trader"; įmonė taip pat nurodo "trader" su pavadinimu, registracijos numeriu, adresu ir "certified": true – įsipareigojimu siūlyti tik ES teisės aktus atitinkančias prekes ir paslaugas. Be to skelbimas lieka juodraštis (pending "seller_kind"), kol bent kartą tai nurodysite svetainėje.
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 arba 30 dienų; renew: 7, 14, 30 arba 60; bump: true. Taikoma jūsų plano nuolaida; suma pateikiama lauke "charged".
Paraiškos
GET | /api/v1/applications?listing=:id&page=1 | Paraiškos į jūsų darbo skelbimus |
PATCH | /api/v1/applications/:id | Perkelti į etapą {"stage": "interview"} |
Statistika
GET | /api/v1/me | Paskyra, planas, kreditai |
GET | /api/v1/stats?days=30 | Peržiūros, kontaktai ir išsaugojimai per dieną |
Klaidos
400 | invalid_json · bad_request | Užklausos turinys nėra galiojantis JSON |
401 | unauthorized | Trūksta rakto arba jis netinkamas |
402 | insufficient_credits | Nepakanka kreditų paskelbti ar iškelti |
403 | plan_required · account_disabled | Jūsų plane API nėra arba paskyra išjungta |
403 | insufficient_scope · spend_cap_reached | Raktas neturi lauke "scope" nurodyto leidimo arba mokėjimas viršytų jo mėnesio išlaidų ribą |
404 | not_found | Nerasta arba nepriklauso jums |
405 | method_not_allowed | Šis metodas čia nepalaikomas (žr. antraštę Allow) |
409 | expired · not_published · auction_price_locked · withdrawn · closed · request_in_progress · invalid_status_change · not_deliverable · drafts_limit | Neįmanoma esant dabartinei būsenai |
413 | payload_too_large | Užklausa per didelė (JSON iki 100 kB, nuotraukos iki 8 MB) |
415 | unsupported_media_type | Siųskite Content-Type: application/json |
422 | validation_failed · idempotency_key_reused · incomplete · banned_text | Laukų klaidos: "fields" (pranešimai) ir "codes" (pastovūs raktai) |
429 | rate_limited | Viršytas užklausų limitas |
500 | server_error | Klaida mūsų pusėje; nurodykite atsakymo X-Request-Id kreipdamiesi į pagalbą |
MCP serveris DI asistentams
Prijunkite Tirgus rinkos duomenis prie Claude ar kito MCP kliento: asistentas galės ieškoti skelbimų, vertinti kainas, rasti geriausius pasiūlymus, sekti kainų tendencijas ir atrasti būdų uždirbti. Tik vieši duomenys, tik skaitymui: jokių kontaktų ar asmens duomenų.
search_listings | Paieška pagal tekstą, kategoriją, regioną, kainą ir filtrus |
get_listing | Skelbimo informacija, kainos įvertinimas, kainų istorija, aukcionas ir pardavėjo patikimumas |
check_price | Ar kaina gera? Palyginimas su panašiais automobiliais, butais, namais ir telefonais |
best_offers | Pigiausias rinkos ketvirtis ir didžiausi kainų sumažinimai |
price_trends | Savaitinės medianinės kainos, kainų sumažinimai ir pardavimai |
market_overview | Visa rinka: apimtys, paklausa, automobilių ir butų kainos |
find_opportunities | Vienkartiniai darbai, darbo skelbimai, „perku“ skelbimai, pamokos, aukcionai ir nemokamai atiduodami daiktai |
list_categories | Kategorijos, filtrai ir regionai |
Nuotoliniu būdu (HTTP)
Claude: Nustatymai → Jungtys → Pridėti pasirinktinę jungtį ir įveskite šį adresą. Rakto nereikia; limitas — 120 vienetų per minutę: kiekviena užklausa yra 1, o check_price, best_offers, price_trends, market_overview ir find_opportunities — 5. Limitas skaičiuojamas kiekvienam IPv4 adresui arba IPv6 /48 tinklui; kai paslauga apkrauta, klientai, siunčiantys tik kelias užklausas per minutę, vis tiek aptarnaujami, o laukti visiems tenka tik esant perkrovai (žr. Retry-After).
https://baltic-market.org/mcp
Lokaliai (stdio)
Claude Desktop arba IDE konfigūracijoje (serverio kopijoje su ta pačia duomenų baze):
{
"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" }
}
}
}
Paruošti raginimai: market_report, deal_hunter, earn_money.
CSV
Pirmoje CSV eilutėje pateikiami stulpelių pavadinimai; atributai žymimi priešdėliu a_ (tie patys kaip filtruose). Kelias reikšmes atskirkite simboliu |. Tinka ir kablelis, ir kabliataškis.
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