Ticaro Admin — Documentation

منابع داده (کراولرها)

سیستم قیمت‌گذاری از چند کراولر موازی استفاده می‌کند. هر کراولر روی یک بازه زمانی مستقل اجرا می‌شود و نتایج را از طریق NATS منتشر می‌کند. سرویس Aggregator قیمت‌ها را از منابع مختلف دریافت کرده و بر اساس اولویت هر منبع، قیمت نهایی را محاسبه می‌کند.

نام	بازار	بازه پول	وضعیت پیش‌فرض	توضیح
nobitex	صرافی ایرانی	۱۰ ثانیه	فعال	کریپتو به تومان
binance	صرافی جهانی	۵ ثانیه	فعال	کریپتو به USDT
tgju	بازار ایران	۳۰ ثانیه	فعال	ارز، طلا، سکه، شاخص
wallex	صرافی ایرانی	۱۰ ثانیه	غیرفعال	کریپتو
tetherland	صرافی ایرانی	۱۵ ثانیه	غیرفعال	USDT به تومان
ramzinex	صرافی ایرانی	۱۵ ثانیه	غیرفعال	کریپتو
exnovin	صرافی ایرانی	۱۵ ثانیه	غیرفعال	کریپتو
tsetmc	بورس ایران	۳۰ ثانیه	غیرفعال	سهام و صندوق‌ها
fipiran	صندوق‌های سرمایه‌گذاری	۵ دقیقه	غیرفعال	NAV صندوق‌ها
bama	خودرو (صفر)	۱۵ دقیقه	غیرفعال	قیمت خودروی صفر — bama.ir
divar	خودرو (دست دوم)	۳۰ دقیقه	غیرفعال	میانه قیمت آگهی‌ها — divar.ir

فعال‌سازی کراولر

برای فعال‌سازی هر کراولر، متغیر محیطی مربوطه را در فایل .env یا کانفیگ YAML تنظیم کنید:

CRAWLER_BAMA_ENABLED=true
CRAWLER_BAMA_POLL_INTERVAL=15m

CRAWLER_DIVAR_ENABLED=true
CRAWLER_DIVAR_POLL_INTERVAL=30m

بعد از فعال‌سازی، کراولر crawler service را ریستارت کنید. قیمت‌ها پس از اولین polling در جدول prices ظاهر می‌شوند.

Data Sources (Crawlers)

The pricing system uses multiple parallel crawlers. Each crawler runs on an independent schedule and publishes results via NATS. The Aggregator service receives prices from all sources and computes the final price based on each source's priority.

Name	Market	Poll interval	Default	Description
nobitex	IR exchange	10s	enabled	Crypto / TMN
binance	Global exchange	5s	enabled	Crypto / USDT
tgju	IR market data	30s	enabled	Forex, gold, indices
wallex	IR exchange	10s	disabled	Crypto
tetherland	IR exchange	15s	disabled	USDT/TMN
ramzinex	IR exchange	15s	disabled	Crypto
exnovin	IR exchange	15s	disabled	Crypto
tsetmc	TSE / IFB	30s	disabled	Stocks, ETFs
fipiran	Mutual funds	5m	disabled	NAV per unit
bama	Cars (new)	15m	disabled	New car prices — bama.ir
divar	Cars (used)	30m	disabled	Used car median price — divar.ir

Enabling a Crawler

Set the relevant environment variable in .env or YAML config:

CRAWLER_BAMA_ENABLED=true
CRAWLER_BAMA_POLL_INTERVAL=15m

CRAWLER_DIVAR_ENABLED=true
CRAWLER_DIVAR_POLL_INTERVAL=30m

After enabling, restart the crawler service. Prices will appear in the prices table after the first poll.

نحوه کار کراولر خودرو

Bama — قیمت صفر

آگهی‌های خودروی صفر را از bama.ir جمع‌آوری می‌کند. برای هر مدل، میانه قیمت آگهی‌های صفحه اول را به عنوان قیمت نهایی برمی‌گرداند. بازه پیشنهادی polling: ۱۵ دقیقه.

GET bama.ir/bama-auto/api/v1/search
bodyStatus=new & vehicleType=light

Divar — دست دوم

آگهی‌های خودروی دست دوم را از divar.ir (تهران) جمع‌آوری می‌کند. قیمت متنی آگهی‌ها پارس می‌شود و میانه به عنوان قیمت بازار برمی‌گردد. بازه پیشنهادی: ۳۰ دقیقه.

GET api.divar.ir/v8/web-search/tehran/cars
sort=sort_date

نکته مهم: قیمت‌های bama و divar قیمت پیشنهادی (asking price) آگهی‌ها هستند، نه قیمت معامله‌شده. این قیمت‌ها به عنوان شاخص بازار استفاده می‌شوند. کراولر divar برای پارس کردن قیمت‌های فارسی (مثل «۵۸۰ میلیون تومان») از تبدیل ارقام فارسی به لاتین استفاده می‌کند.

مدل‌های خودروی پشتیبانی‌شده

این مدل‌ها در جدول assets ثبت شده‌اند. هر مدل با سیمبل انگلیسی و quote_currency=TMN ذخیره می‌شود.

IKCO / ایران خودرو

PEUGEOT206پژو ۲۰۶

PEUGEOT207پژو ۲۰۷

PEUGEOT405پژو ۴۰۵

SAMANDLXسمند LX

SAMANDELXسمند ELX

SAMANDSORENسمند سورن

DENAدنا

DENAPLUSدنا پلاس

RUNNAرانا

RUNNAPLUSرانا پلاس

ARIAآریا

SAIPA / سایپا

PRIDE111پراید ۱۱۱

PRIDE131پراید ۱۳۱

PRIDE132پراید ۱۳۲

PRIDE141پراید ۱۴۱

TIBAتیبا

TIBA2تیبا ۲

QUICKکوییک

QUICKRکوییک R

QUICKAUTOکوییک اتوماتیک

SHAHINشاهین

SHADINGشاهین G

سایر / Other

HAIMAS7هایما S7

ATLASاطلس

MVM315MVM 315

MVM550MVM 550

BRILLIANCEH330برلیانس H330

CHERYAROZO5چری آریزو ۵

How Car Price Crawlers Work

Bama — New cars

Collects new-car listings from bama.ir. For each model, computes the median price from the first page of results. Recommended poll interval: 15 minutes.

GET bama.ir/bama-auto/api/v1/search
bodyStatus=new & vehicleType=light

Divar — Used cars

Collects used-car listings from divar.ir (Tehran). Parses Persian price text from ad descriptions and returns the median as market price. Recommended poll interval: 30 minutes.

GET api.divar.ir/v8/web-search/tehran/cars
sort=sort_date

Note: Bama and Divar prices are asking prices from listings, not transaction prices. They serve as market indicators. The Divar crawler converts Persian/Arabic-Indic numerals and handles suffixes like «میلیون» (million) to produce numeric TMN values.

Supported Car Models

All models are registered in the assets table with asset_type='car' and quote_currency='TMN'.

IKCO

PEUGEOT206Peugeot 206

PEUGEOT207Peugeot 207

PEUGEOT405Peugeot 405

SAMANDLXSamand LX

SAMANDELXSamand ELX

SAMANDSORENSamand Soren

DENADena

DENAPLUSDena Plus

RUNNARunna

RUNNAPLUSRunna Plus

ARIAAria

SAIPA

PRIDE111Pride 111

PRIDE131Pride 131

PRIDE132Pride 132

PRIDE141Pride 141

TIBATiba

TIBA2Tiba 2

QUICKQuick

QUICKRQuick R

QUICKAUTOQuick Auto

SHAHINShahin

SHADINGShahin G

Others

HAIMAS7Haima S7

ATLASAtlas

MVM315MVM 315

MVM550MVM 550

BRILLIANCEH330Brilliance H330

CHERYAROZO5Chery Arrizo 5

دسترسی به قیمت خودرو از طریق API

تمام endpoint‌های API نیاز به احراز هویت دارند (JWT یا X-API-Key).

GET /api/v1/prices/category/car

تمام قیمت‌های خودرو (همه مدل‌ها، هر دو منبع bama و divar)

curl -H "X-API-Key: your_key" \
  https://api.yourhost.com/api/v1/prices/category/car

GET /api/v1/prices/{symbol}/{quote}

قیمت یک مدل خاص — مثال: پژو ۲۰۶

curl -H "X-API-Key: your_key" \
  https://api.yourhost.com/api/v1/prices/PEUGEOT206/TMN

{
  "symbol": "PEUGEOT206",
  "quote_currency": "TMN",
  "price": 580000000,
  "high_24h": 650000000,
  "low_24h": 520000000,
  "sources": [
    { "source": "bama",  "price": 580000000, "fetched_at": "2026-06-03T10:00:00Z" },
    { "source": "divar", "price": 610000000, "fetched_at": "2026-06-03T09:45:00Z" }
  ]
}

GET /api/v1/prices

همه قیمت‌ها — شامل خودرو، ارز، طلا و کریپتو

curl -H "X-API-Key: your_key" \
  https://api.yourhost.com/api/v1/prices

Accessing Car Prices via API

All API endpoints require authentication (Bearer JWT or X-API-Key header).

GET /api/v1/prices/category/car

All car prices — all models, both bama and divar sources

curl -H "X-API-Key: your_key" \
  https://api.yourhost.com/api/v1/prices/category/car

GET /api/v1/prices/{symbol}/{quote}

Price for a specific model — example: Peugeot 206

curl -H "X-API-Key: your_key" \
  https://api.yourhost.com/api/v1/prices/PEUGEOT206/TMN

{
  "symbol": "PEUGEOT206",
  "quote_currency": "TMN",
  "price": 580000000,
  "high_24h": 650000000,
  "low_24h": 520000000,
  "sources": [
    { "source": "bama",  "price": 580000000, "fetched_at": "2026-06-03T10:00:00Z" },
    { "source": "divar", "price": 610000000, "fetched_at": "2026-06-03T09:45:00Z" }
  ]
}

GET /api/v1/prices

All prices — includes cars, forex, gold, and crypto

curl -H "X-API-Key: your_key" \
  https://api.yourhost.com/api/v1/prices

قرارداد نام‌گذاری سیمبل‌ها

هر asset با ترکیب symbol/quote_currency شناسایی می‌شود.

نوع دارایی	مثال symbol	quote_currency	منبع
کریپتو (جهانی)	BTC	USDT	binance
کریپتو (ایران)	BTC	TMN	nobitex, wallex
ارز خارجی	USD	TMN	tgju
طلا	GOLD18	TMN	tgju
طلای جهانی	XAU	USD	tgju
شاخص بورس	TSEI	POINT	tsetmc
فارکس	EURUSD	FX	tgju
خودرو	PEUGEOT206	TMN	bama, divar

Symbol Naming Convention

Each asset is identified by symbol/quote_currency.

Asset type	Symbol example	quote_currency	Source(s)
Crypto (global)	BTC	USDT	binance
Crypto (Iran)	BTC	TMN	nobitex, wallex
Forex	USD	TMN	tgju
Gold (Iran)	GOLD18	TMN	tgju
Gold (global)	XAU	USD	tgju
Stock index	TSEI	POINT	tsetmc
FX cross rate	EURUSD	FX	tgju
Car (new/used)	PEUGEOT206	TMN	bama, divar