API dokumentatsioon
Hangi API-võtiJSON REST API kuulutuste, kandidaatide ja statistika haldamiseks. Hinnad on eurodes, ajad ISO 8601 vormingus.
Koostöö, reklaam ja API: partners@baltic-market.org
Autentimine
Saatke igas päringus päis Authorization jaotisest „Integratsioonid“ pärit võtmega. Hoidke võtmeid oma serveris.
curl https://baltic-market.org/api/v1/me \ -H "Authorization: Bearer tg_live_…"
Limiit: 120 päringut minutis konto kohta, kõik võtmed kokku (päised X-RateLimit-*).
Turvalised kordused
Saatke POST-päringutega päis Idempotency-Key (kuni 100 märki). Kui ühendus katkeb ja kordate päringut sama võtme ja sisuga, saate tagasi esimese vastuse (päis Idempotent-Replayed): teist kuulutust ei looda ja teist makset ei võeta. Võtmeid säilitatakse 24 tundi.
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 '{ … }'
Päringu sisu on õigete tüüpidega JSON-objekt; tundmatud väljad ja atribuudid lükatakse selgitusega tagasi. Igal vastusel on päis X-Request-Id — märkige see toega ühendust võttes.
Võtmete õigused
Igal võtmel on selle loomisel märgitud õigused; konto (/me) ja kuulutuste lugemiseks õigusi vaja pole. Uued võtmed saavad vaikimisi listings:write ja stats:read. Andke igale süsteemile või tarnijale oma võti ainult vajalikuga. GET /api/v1/me näitab päringu teinud võtme õigusi ja kulutusi.
listings:write | kuulutuste ja nende fotode loomine, muutmine ja kustutamine; avaldamine paketi kvoodi piires ja pikendamine, kui see on tasuta |
credits:spend | koos listings:write õigusega maksmine krediidisaldost: tasuline avaldamine, pikendamine, TOP-positsioon, esiletõstmine, „kiire“ ja tippu tõstmine |
applications | lugeda tööavaldusi, sh kandidaatide telefoni ja e-posti, ning muuta nende etappi |
stats:read | vaatamised, kontaktide avamised ja salvestamised päevade kaupa |
Võtmel võib olla kuu kulutuslimiit krediitides (kalendrikuu, Läti aeg). Limiiti ületav makse lükatakse tagasi vastusega 403 spend_cap_reached ja ilma credits:spend õiguseta võtme makse vastusega 403 insufficient_scope; midagi ei võeta. Neid keeldumisi Idempotency-Key jaoks ei salvestata, nii et sama hiljem uuesti saadetud päring (suurema limiidiga võtmega või järgmisel kuul) töödeldakse uuesti. Uus kuulutus, mis maksaks krediite, jääb siis mustandiks ja põhjus on väljal "pending". Enne õiguste kasutuselevõttu loodud võtmetel on kõik õigused ja limiiti pole: asendage need uutega.
Kuulutused
GET | /api/v1/listings?status=active&page=1 | Teie kuulutused, 50 lehel |
POST | /api/v1/listings | Loo ja avalda |
GET | /api/v1/listings/:id | Üks kuulutus |
PATCH | /api/v1/listings/:id | Muuda hinda, pealkirja, kirjeldust või olekut (active/inactive) |
DELETE | /api/v1/listings/:id | Kustuta |
POST | /api/v1/listings/:id/images | Lisa fotosid (multipart-väli "photos", kuni 10) |
DELETE | /api/v1/listings/:id/images/:image | Eemalda foto |
POST | /api/v1/listings/:id/promote | TOP, esiletõst, kiire, ülestõstmine või pikendamine krediitide eest |
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 }
}'
Avaldamisel kasutatakse paketi kvooti, seejärel krediite. Kui krediite ei jätku, sisaldab vastus "pending": "credits" ja kuulutus jääb mustandiks.
Märkige, kes müüb (ELi digiteenuste määrus): "seller_kind": "private" või "trader"; ettevõte saadab ka "trader" nime, registrikoodi ja aadressiga ning väljaga "certified": true – kohustusega pakkuda ainult ELi õigusele vastavaid tooteid ja teenuseid. Ilma selleta jääb kuulutus mustandiks (pending "seller_kind"), kuni olete selle saidil korra märkinud.
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 või 30 päeva; renew: 7, 14, 30 või 60; bump: true. Kehtib teie paketi allahindlus; summa on väljal "charged".
Avaldused
GET | /api/v1/applications?listing=:id&page=1 | Kandideerimised teie töökuulutustele |
PATCH | /api/v1/applications/:id | Teisalda etappi {"stage": "interview"} |
Statistika
GET | /api/v1/me | Konto, pakett, krediidid |
GET | /api/v1/stats?days=30 | Vaatamised, kontaktid ja salvestamised päevade kaupa |
Vead
400 | invalid_json · bad_request | Päringu sisu ei ole kehtiv JSON |
401 | unauthorized | Võti puudub või on vigane |
402 | insufficient_credits | Avaldamiseks või esiletõstmiseks pole piisavalt krediiti |
403 | plan_required · account_disabled | Teie pakett ei sisalda API-t või konto on keelatud |
403 | insufficient_scope · spend_cap_reached | Võtmel puudub väljal "scope" nimetatud õigus või makse ületaks selle kuu kulutuslimiiti |
404 | not_found | Ei leitud või ei kuulu teile |
405 | method_not_allowed | Meetodit siin ei toetata (vt päist Allow) |
409 | expired · not_published · auction_price_locked · withdrawn · closed · request_in_progress · invalid_status_change · not_deliverable · drafts_limit | Praeguses olekus pole võimalik |
413 | payload_too_large | Päring liiga suur (JSON kuni 100 kB, fotod kuni 8 MB) |
415 | unsupported_media_type | Saatke Content-Type: application/json |
422 | validation_failed · idempotency_key_reused · incomplete · banned_text | Väljade vead: "fields" (teated) ja "codes" (püsivad võtmed) |
429 | rate_limited | Päringute limiit on ületatud |
500 | server_error | Viga meie poolel; tugiteenusega ühendust võttes märkige vastuse X-Request-Id |
MCP-server tehisintellekti assistentidele
Ühendage Tirgus turuandmed Claude'i või mõne muu MCP-kliendiga: assistent saab otsida kuulutusi, hinnata hindu, leida parimaid pakkumisi, jälgida hinnatrende ja avastada teenimisvõimalusi. Ainult avalikud andmed, ainult lugemiseks: ilma kontaktide ja isikuandmeteta.
search_listings | Otsing teksti, kategooria, piirkonna, hinna ja filtrite järgi |
get_listing | Kuulutuse andmed, hinnahinnang, hinnaajalugu, oksjon ja müüja usaldusväärsus |
check_price | Kas hind on hea? Võrdlus sarnaste autode, korterite, majade ja telefonidega |
best_offers | Turu odavaim veerand ja suurimad hinnalangused |
price_trends | Nädala mediaanhinnad, hinnalangused ja müügid |
market_overview | Kogu turg: mahud, nõudlus, autode ja korterite hinnad |
find_opportunities | Otsatööd, töökuulutused, „ostan“-kuulutused, tunnid, oksjonid ja tasuta äraandmised |
list_categories | Kategooriad, filtrid ja piirkonnad |
Kaugühendus (HTTP)
Claude'is: Seaded → Konnektorid → Lisa kohandatud konnektor ja sisestage see URL. Võtit pole vaja; limiit on 120 ühikut minutis: iga päring on 1, kuid check_price, best_offers, price_trends, market_overview ja find_opportunities on 5. Limiiti arvestatakse iga IPv4-aadressi või IPv6 /48-võrgu kohta; kui teenus on koormatud, teenindatakse endiselt kliente, kes teevad vaid mõne päringu minutis, ja ainult ülekoormuse korral peavad kõik ootama (vt Retry-After).
https://baltic-market.org/mcp
Lokaalselt (stdio)
Claude Desktopi või IDE konfiguratsioonis (serveri koopial sama andmebaasiga):
{
"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" }
}
}
}
Valmisviibad: market_report, deal_hunter, earn_money.
CSV
CSV esimene rida sisaldab veergude nimesid; atribuudid kasutavad eesliidet a_ (samad mis filtrites). Eraldage mitu väärtust märgiga |. Sobivad nii koma kui ka semikoolon.
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