AI ایجنٹس کے لیے Treeple

Treeple قزاقستان میں رہنمائی شدہ دوریں منعقد کرتا ہے۔ یہ صفحہ بیان کرتا ہے کہ AI ایجنٹ کیٹلاگ کو کیسے پڑھ سکتا ہے اور ایک سفری کی طرف سے ایک انسان کو بکنگ کی درخواست کس طرح تسلیم کر سکتا ہے۔ کوئی رجسٹریشن نہیں، کوئی API کلید نہیں، کوئی OAuth نہیں۔

MCP سرور

Streamable HTTP پر ریموٹ ماڈل کنٹیکسٹ پروٹوکول سرور۔ کسی بھی MCP-قابل کلائنٹ کو یہاں اشارہ کریں:

https://mcp.treeple.kz/mcp

Claude Desktop، Claude Code اور اسی طرح کے کلائنٹس کے لیے:

{
  "mcpServers": {
    "treeple": {
      "type": "http",
      "url": "https://mcp.treeple.kz/mcp"
    }
  }
}
  • search_tours — ٹیکسٹ، قسم یا مدت کے لحاظ سے کیٹلاگ تلاش کریں۔
  • get_tour — سفر نامہ، شامل ہونے والے، ملاقات کے مقام، منسوخی کی پالیسی اور مکمل قیمت ٹیبل۔
  • get_availability — روانگی کی تاریخیں، یا ایمانداری سے « on_request » جب کسی دوری کے پاس کوئی مقررہ کیلنڈر نہ ہو۔
  • get_quote — ایک نامزد گروپ اور تاریخ کے لیے درست قیمت، جو اس ٹائم اسٹیمپ تک معتبر ہے جو یہ واپس کرتا ہے۔
  • create_booking_session — ایک کوٹ کو treeple.kz پر چیک آؤٹ لنک میں بدلتا ہے، جہاں مسافر اپنی رابطہ تفصیلات خود درج کرتا ہے۔
  • get_booking_status — ایک بکنگ کی حالت، اس کے ٹوکن سے تلاش کی جاتی ہے۔ ای میل یا فون سے تلاش دستیاب نہیں۔
  • submit_booking_request — ایک درخواست انسانی منیجر کو تسلیم کرتا ہے۔ بکنگ نہیں ہے اور کوئی ادائیگی نہیں کرتا۔
  • search_content — دیکھنے کی جگہیں، ریسٹورنٹس، سفری مضامین اور ٹور کیٹیگریاں — وہی سرچ انجن جو سائٹ استعمال کرتی ہے۔
  • get_content — ایک جگہ، ریسٹورنٹ، مضمون یا کیٹیگری مکمل تفصیل کے ساتھ۔ ایک جگہ ان ٹورز کی فہرست بھی دیتی ہے جو واقعی وہاں جاتے ہیں۔

REST API

MCP سرور اس API کے اوپر ایک پتلا wrapper ہے — آپ اسے براہ راست کال کر سکتے ہیں۔ OpenAPI 3.1 مواصفات:

https://backend.treeple.kz/api/v1/agent/openapi.json

کیٹلاگ تلاش کریں:

curl "https://backend.treeple.kz/api/v1/agent/tours?lang=en&q=canyon&limit=5"

بکنگ کی درخواست جمع کریں:

curl -X POST "https://backend.treeple.kz/api/v1/agent/booking-requests" \
  -H "Content-Type: application/json" \
  -d '{
    "tour_slug": "charyn-canyon-tour-1-day",
    "date": "2026-09-15",
    "pax": { "adults": 2, "children": 0 },
    "lang": "en",
    "contact": { "email": "traveller@example.com" },
    "idempotency_key": "3f6d6d2e-4a1f-4c2b-9c3a-1a2b3c4d5e6f"
  }'

پوری کیٹلاگ کا ایک فلیٹ پروڈکٹ فیڈ دستیاب ہے:

https://backend.treeple.kz/api/v1/agent/feed.json

ٹورز سے آگے

ہر سوال بکنگ سے متعلق نہیں ہوتا۔ یہ شماریاں وہ ہیں جو کیٹلاگ میں واقعی موجود ہیں — ان سے زیادہ کا دعویٰ کرنے والا ایجنٹ یہ گھڑ رہا ہے۔

  • locations — 116 دیکھنے کی جگہیں، سب کوآرڈینیٹس کے ساتھ۔ ہر ایک میں وہ ٹورز درج ہیں جو وہاں جاتے ہیں؛ یہ ایک منتخب فہرست ہے، اس لیے خالی فہرست کا مطلب ہے کہ Treeple وہاں کوئی ٹور نہیں بیچتا۔
  • tour_types — 16 ٹور کیٹیگریاں، ہر ایک کے ساتھ اس کے پیچھے شائع شدہ ٹورز کی تعداد۔
  • restaurants — 5 ریستوران — چار الماتی میں، ایک آستانہ میں۔ کھانا، قیمت کی حد، پتہ، کھلنے کے اوقات۔ کوئی کوآرڈینیٹس نہیں: کیٹلاگ میں یہ موجود نہیں، اس لیے کوئی فیلڈ واپس نہیں کی جاتی۔
  • articles — Treeple کے لکھے ہوئے 6 سفری مضامین۔
curl "https://backend.treeple.kz/api/v1/agent/content/locations?lang=en&q=Kolsai"
curl "https://backend.treeple.kz/api/v1/agent/content/locations/natspark-kolsay?lang=en"

یہ کتنی تازہ ہے

سائٹ خودکار طور پر دوبارہ بنائی جاتی ہے جب کیٹلاگ بدلتا ہے۔ ان صفحات کے پیچھے موجود اسنیپ شاٹ کب لیا گیا تھا، یہ عوامی ہے:

https://treeple.kz/catalogue-status.json

ٹور کے لیے واپس آنے والے فیلڈز

یہ get_tour اور GET /tours/{slug} کے جواب میں موجود فیلڈ نام ہیں — خلاصہ نہیں۔ مستند ورژن اوپر دی گئی OpenAPI تفصیلات ہیں۔

{
  "slug":              "localised, differs per language",
  "canonical_slug":    "stable identifier, same in every language",
  "title", "summary", "description", "url",
  "duration_days" | "duration_nights" | "duration_hours", "duration_label",
  "types":             ["trekking", "culture", ...],
  "price":             { "basis": "per_person", "currency", "from",
                         "by_group_size": [{ "pax", "price_per_person" }] },
  "itinerary":         [{ "day", "title", "description" }],
  "included":          ["what the price covers"],
  "excluded":          ["what it does not"],
  "meeting_place":     "text",
  "suitable_for", "not_suitable_for", "difficulty", "min_age", "max_age",
  "cancellation_policy": { "source": "tour" | "site_default",
                           "deadline_hours", "service_fee_percent",
                           "tiers": [{ "hours_before_start", "refund_percent" }] },

  "guide_languages":   { "live": [...], "audio": [...] },   // what the GUIDE speaks
  "content_languages": [...],                               // locales the PAGE is published in
  "confirmation_type": "instant" | "manual",
  "availability_type": "scheduled" | "on_request",
  "group":             { "type", "minimum_pax", "maximum_pax" },
  "operator":          "text"
}

جو فیلڈ جواب میں موجود نہیں ہے اس کا مطلب ہے کہ Treeple کے پاس اس کے لیے کوئی ڈیٹا نہیں۔ اس کا مطلب صفر، نہیں، یا ڈیفالٹ نہیں ہوتا — اس لیے ایسا فرض کرنے کے بجائے یہی کہیں۔ اسی لیے minimum_pax صرف اُن ٹورز میں آتا ہے جن میں واقعی کم از کم روانگی کی شرط ہو، اور payment_policy نامی کوئی فیلڈ بالکل موجود نہیں۔

دو زبانوں کے فیلڈ موجود ہیں اور ان کے معنی مختلف ہیں۔ guide_languages سے مراد ہے گائیڈ واقعی کون سی زبانیں بولتا ہے؛ content_languages صرف یہ بتاتا ہے کہ یہ ویب صفحہ کن لوکلز میں شائع ہے۔ کبھی بھی content_languages سے “کیا X بولنے والا گائیڈ ہے” کا جواب نہ دیں۔

چیزیں جو ورنہ آپ کو الجھا دیں گی

  • قیمتیں فی شخص ہیں اور گروپ کے سائز کے ساتھ تبدیل ہوتی ہیں۔ ہر قیمت ایک by_group_size ٹیبل لے جاتی ہے — اصل گروپ سے ملنے والی قطار کا حوالہ دیں، « from » کی شکل نہیں۔ « from » کا عدد صرف min_group_size_for_from والے گروپ سائز پر لاگو ہوتا ہے: چارین کے ایک روزہ دورے میں یہ پندرہ مسافروں پر $30 ہے، جبکہ دو افراد فی کس $155 ادا کرتے ہیں۔
  • ٹور سلگز زبان کے لحاظ سے مختلف ہوتے ہیں۔ canonical_slug مستحکم شناخت کنندہ ہے؛ lang کو واضح طور پر پاس کریں۔
  • « on_request » کا مطلب ہے کہ تاریخ انفرادی طور پر طے کی جاتی ہے، نہ کہ دوری فروخت ہو گئی ہو۔
  • بکنگ کی درخواستوں کو واپس نہیں پڑھا جا سکتا۔ ایک منیجر سفری سے براہ راست رابطہ کرتا ہے؛ کوئی حالت سے نہیں ہے۔ یہ ارادی ہے — یہ وہی ہے جو کسی کو دوسروں کی درخواستوں کی فہرست بنانے سے روکتا ہے۔
  • فی درخواست بالکل ایک رابطہ چینل: ای میل، فون یا Telegram۔ کوئی نام، دستاویزات یا ادائیگی کی تفصیلات جمع نہیں کی جاتی ہیں۔
  • ہر بکنگ کی درخواست کو UUID idempotency کلید کی ضرورت ہے۔ اسے 24 گھنٹے میں دہرایا جائے تو اصل درخواست واپس آتی ہے بجائے دوسری lead بنانے کے، تاکہ ٹائم آؤٹ کے بعد دوبارہ کوشش ہمیشہ محفوظ ہو۔

شرح کی حدیں

  • فی IP فی منٹ 60 پڑھنے کی درخواستیں۔
  • فی IP فی منٹ 5 بکنگ کی درخواستیں اور فی دن 20۔
  • حد سے اوپر آپ کو Retry-After ہیڈر کے ساتھ 429 ملتا ہے۔ اسے عزت دیں۔
  • کوئی API کلید ضروری نہیں۔ ساتھی زیادہ حدود کے لیے X-Agent-Key کی درخواست کر سکتے ہیں۔

رازداری

ایک بکنگ کی درخواست بالکل ایک رابطہ چینل لے جاتی ہے اور کچھ نہیں۔ رابطہ کی قیمتوں اور IP پتوں کو کبھی بھی صاف الفاظ میں لاگز یا تجزیہ میں نہیں لکھا جاتا ہے — صرف نمک شدہ ہیش، ڈپلیکیٹ درخواستوں کو ضم کرنے کے لیے استعمال کیا جاتا ہے۔ کوئی endpoint نہیں ہے جو ایک بکنگ کی درخواست واپس کرتا ہے، تاکہ کوئی بھی دوسروں کی انکوائریز کو درج نہیں کر سکتا۔

دریافت

سوالات، یا کیا آپ کو کسی ساتھی انضمام کے لیے زیادہ شرح کی حدوں کی ضرورت ہے؟ لکھو support@treeple.kz.