دسترسی هوشمند به مستندات با MCP (MCP API)

۱۱ از ۱۱v1.2.0

این صفحه نقطه شروع مستندات API دیجی‌اکسپرس است. تیم‌های فنی و ابزارهای هوش مصنوعی می‌توانند با اتصال به سرور MCP دیجی‌اکسپرس، در مستندات انگلیسی اینتگریشن جست‌وجو کنند و بخش دقیق و قابل استناد هر پاسخ را دریافت کنند.

نشانی اتصال MCP

کلاینت‌های سازگار با Streamable HTTP باید به نشانی زیر متصل شوند. این مسیر برای خواندن مستندات عمومی است و به حساب کاربری، اطلاعات محرمانه یا APIهای عملیاتی مرسوله دسترسی ندارد.

POSThttps://digiexpress.ir/mcp/api

راه‌اندازی سریع در کلاینت‌های MCP

در کلاینت هوش مصنوعی یا Agent خود بخش MCP، Integrations یا Tools را باز کنید، یک Remote MCP Server بسازید و مقادیر زیر را وارد کنید. نام منو ممکن است بین محصولات متفاوت باشد، اما نوع اتصال و URL یکسان است.

۵ ردیف
تنظیممقدار
NameDigiExpress API Docs
TransportStreamable HTTP / Remote HTTP
URLhttps://digiexpress.ir/mcp/api
AuthenticationNone؛ این Endpoint فقط مستندات عمومی را می‌خواند
Available toolssearch و fetch

تنظیم کلاینت‌های مبتنی بر JSON

اگر کلاینت شما فایل پیکربندی JSON با کلید mcpServers دارد، تنظیم زیر را اضافه کرده و کلاینت را Restart کنید. هیچ Token یا Credential دیجی‌اکسپرس را در این فایل قرار ندهید.

json
{
  "mcpServers": {
    "digiexpress-api": {
      "url": "https://digiexpress.ir/mcp/api"
    }
  }
}

تست اتصال در کمتر از یک دقیقه

  • کلاینت یا Agent را پس از ذخیره تنظیمات Restart کنید و مطمئن شوید سرور DigiExpress API Docs فعال است.
  • در فهرست ابزارها باید دقیقاً دو Tool با نام‌های search و fetch نمایش داده شوند.
  • Prompt زیر را اجرا کنید. دستیار باید ابتدا search و سپس fetch را فراخوانی کند و در پاسخ به منبع انگلیسی MCP استناد کند.
  • اگر دستیار بدون فراخوانی Tool پاسخ داد، صریحاً از آن بخواهید فقط از DigiExpress MCP و الگوی search → fetch استفاده کند.
text
Use the DigiExpress API documentation MCP. Search and fetch the Authentication section. Explain the exact two-call OTP flow: first POST /api/customers/auth/sendOTP with phone_number, then POST /api/customers/auth/login with username and otp_code. Return the documented success fields and citations. Do not add a refresh endpoint unless it is explicitly documented.

مثال ۱: ثبت با Specified Parcels طبق فلو Async سند

text
Use only the DigiExpress API documentation MCP. Search and fetch Login with Password, Register with Specified Parcels, Webhook Integration, and Single Label. For a [LANGUAGE/FRAMEWORK] backend, implement this documented flow: POST /api/customers/auth/login; POST /api/v2/shipments with parcels and without max_shipment_capacity_estimation_for_pre_reservation; treat Register HTTP 200 only as queued for asynchronous routing; wait for the successful Webhook before calling GET /api/v2/parcels/{parcel_id_or_code}/label. Preserve every documented request field and cite each fetched section.

مثال ۲: ثبت Estimated و افزودن Parcel

text
Use only the DigiExpress API documentation MCP. Search and fetch Register with Estimated Capacity, Add Parcel, Delete Parcel, Label Generation, and Webhook Integration. Implement the documented [LANGUAGE/FRAMEWORK] flow: register through POST /api/v2/shipments with max_shipment_capacity_estimation_for_pre_reservation and without parcels; treat Register HTTP 200 as asynchronous; after the successful routing Webhook, add each physical package through POST /api/v2/shipments/{shipment_id}/parcels; after Add Parcel returns HTTP 200, retrieve that parcel's label. Enforce remained weight, remained volume, Parcel Size Tier, and the documented delete rules.

مثال ۳: ثبت دو مرحله‌ای با Time Window

text
Use only the DigiExpress API documentation MCP. Search and fetch the Shipping Time Window section along with Register with Specified Parcels and Register with Estimated Capacity. Implement the documented two-stage [LANGUAGE/FRAMEWORK] flow: query options through POST /api/v2/shipping-time-window-request using cargo_ready_date_time, one origin, one destination, physical estimation, each_parcel_size_tier, and off_day_dates; store the selected option's token and expiry; then register through POST /api/v2/shipments using that token and exactly one of parcels or max_shipment_capacity_estimation_for_pre_reservation. Explain the different Label timing for Specified and Estimated registration. Preserve every documented request field and cite each fetched section.

مثال ۴: Webhook و بازیابی رویداد ازدست‌رفته

text
Search and fetch Webhook Integration Guide and Webhook Feed API. Generate a [LANGUAGE/FRAMEWORK] receiver that accepts DigiExpress POST or PUT events, persists the payload, returns HTTP 200 after successful processing, tolerates unknown fields and Progress Types, and does not require intermediate statuses before a final status such as Delivered. Because DigiExpress currently does not retry a failed Webhook, implement recovery with POST /api/v2/shipments/webhook-feed-request using shipment_ids_or_shipment_consignor_reference_ids. Base every behavior on the fetched documentation and cite it.

مثال ۵: عیب‌یابی با کد خطا و وضعیت Shipment

text
I received DigiExpress error code [ERROR_CODE] from [DOCUMENTED_ENDPOINT] for shipment [SYNTHETIC_REFERENCE]. Search by the exact code, endpoint, and related operation; fetch the matching Error Codes and workflow sections; report the documented cause and fix; then verify whether my request fields, Parcel Size Tier, token state, or Shipment state violate that documented flow. Clearly separate documented facts from diagnostic suggestions and never request real credentials or customer data.

پرسش‌های مناسب برای MCP

  • برای ورود با OTP چه Endpointها و چه ترتیب فراخوانی لازم است؟
  • چه زمانی پس از ثبت Shipment می‌توان Label را دریافت کرد؟
  • برای افزودن Parcel در حالت Estimated چه محدودیت‌هایی وجود دارد؟
  • یک Webhook ناموفق را چگونه از Webhook Feed بازیابی کنم؟
  • کد خطای موردنظر چه معنی دارد و راه‌حل پیشنهادی مستندات چیست؟

رفع مشکلات اتصال و استفاده

۶ ردیف
مشکلراه‌حل
خطای 404URL را دقیقاً https://digiexpress.ir/mcp/api وارد کنید.
ابزارها نمایش داده نمی‌شوندTransport را Streamable HTTP انتخاب کنید، تنظیمات را ذخیره کرده و کلاینت را Restart کنید.
search نتیجه مرتبط نداردQuery را با اصطلاح انگلیسی، Endpoint، نام فیلد JSON یا کد خطای دقیق‌تر تکرار کنید.
fetch خطای شناسه می‌دهدشناسه را دستی نسازید؛ ابتدا search را اجرا کرده و همان id برگشتی را به fetch بدهید.
دستیار Endpoint حدس می‌زنددر Prompt الزام کنید فقط پس از search و fetch پاسخ دهد، Citation ارائه کند و موارد مستندنشده را صریح اعلام کند.
API واقعی خطای 401 یا 403 می‌دهداین خطا مربوط به MCP نیست؛ Base URL محیط، Credential، Token expiry و IP Whitelist اتصال اینترنت را بررسی کنید.