شناسه پیگیری و حالت درخواست

دو فیلد اختیاری در بدنه‌ی همه‌ی سرویس‌های زرین‌هاب پذیرفته می‌شوند:

{
  "trackId": "9b126e9a-184c-4cb0-a47e-62b9a3b7176f",
  "requestHandlingType": "standard"
}

trackId

trackId شناسه‌ی یکتای هر درخواست است و در گزارش‌ها، صورت‌حساب و پیگیری پشتیبانی به همین شناسه ارجاع داده می‌شود.

• اگر trackId را ارسال نکنید، زرین‌هاب یک UUID نسخه ۴ برای شما تولید می‌کند.
• اگر ارسال کنید، باید یک UUID معتبر و غیرصفر باشد؛ در غیر این صورت پاسخ ۴۰۰ با خطای اعتبارسنجی روی فیلد trackId دریافت می‌کنید.
• trackId در بدنه‌ی پاسخ (meta.trackId) و در هدر X-Track-Id برگردانده می‌شود.

مهم

هر trackId فقط یک بار قابل استفاده است. اگر همان شناسه را دوباره ارسال کنید، درخواست با خطای تکراری‌بودن trackId رد می‌شود. برای هر فراخوانی جدید یک شناسه‌ی تازه بسازید.

این رفتار عمدی است و از پردازش دوباره‌ی یک درخواست در زمان تلاش مجدد (retry) جلوگیری می‌کند. اگر می‌خواهید مطمئن شوید یک استعلام دوبار هزینه نمی‌شود، trackId را در سمت خود بسازید و ذخیره کنید.

requestHandlingType

این فیلد تعیین می‌کند در صورت خطای تأمین‌کننده، درخواست چگونه ادامه پیدا کند. تنها دو مقدار پذیرفته می‌شود:

مقدار	رفتار
standard	مقدار پیش‌فرض. فقط تأمین‌کننده‌ی نخست (بالاترین اولویت) فراخوانی می‌شود.
advanced	در صورت خطای تأمین‌کننده، درخواست روی تأمین‌کننده‌های بعدی زنجیره ادامه پیدا می‌کند.

مقدار نامعتبر باعث پاسخ ۴۰۰ با خطای اعتبارسنجی روی فیلد requestHandlingType می‌شود.

چه زمانی advanced را انتخاب کنیم؟

• وقتی موفقیت استعلام از سرعت پاسخ مهم‌تر است (مثلاً در جریان ثبت‌نام کاربر).
• وقتی سامانه‌ی مرجع بی‌ثبات است و می‌خواهید خطای موقت یک تأمین‌کننده جریان کار شما را متوقف نکند.

نکاتی که باید در نظر بگیرید:

• زمان پاسخ در حالت advanced می‌تواند چند برابر شود، چون چند تأمین‌کننده پشت سر هم امتحان می‌شوند.
• پیش از شروع زنجیره، کافی‌بودن اعتبار برای کل زنجیره بررسی می‌شود؛ اگر اعتبار کافی نباشد درخواست از ابتدا رد می‌شود.
• هزینه فقط برای تلاش موفق نهایی می‌شود؛ تلاش‌های ناموفق مبلغ رزروشده را آزاد می‌کنند.
• هر تلاش در زنجیره لاگ جداگانه‌ی خود را دارد که به trackId درخواست اصلی زنجیر می‌شود.

نمونه

curl 'https://zarin-hub.com/api/v5/KYC/IbanInquiry' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '{
    "iban": "IR120570028780010851556101",
    "trackId": "6f2a1c53-6f61-4bd4-9f56-6f1e1f5a7b21",
    "requestHandlingType": "advanced"
  }'

پیگیری یک درخواست

برای دیدن وضعیت یا جزئیات یک درخواست ثبت‌شده، از سرویس‌های گروه پیگیری درخواست استفاده کنید و همان trackId را ارسال کنید.