قالب پاسخ

پاسخ همه‌ی وب‌سرویس‌های زرین‌هاب — موفق یا ناموفق — دقیقاً یک ساختار دارد:

{
  "meta": {
    "trackId": "9b126e9a-184c-4cb0-a47e-62b9a3b7176f",
    "status": "kyc-v5-0",
    "isSuccess": true,
    "code": 0,
    "message": "عملیات با موفقیت انجام شد",
    "errorMessage": null,
    "errorType": null,
    "errors": []
  },
  "data": { }
}

فیلدهای meta

نام	نوع	توضیحات
trackId	string (UUID)	شناسه یکتای درخواست؛ در هدر X-Track-Id هم برگردانده می‌شود
status	string	ترکیب نام گروه سرویس و کد وضعیت، به شکل {slug}-{code}؛ مثلاً kyc-v5-0
isSuccess	bool	ملاک اصلی موفقیت درخواست
code	int	کد وضعیت عددی؛ فهرست کامل در فهرست خطاها
message	string | null	پیام موفقیت؛ در پاسخ‌های ناموفق null است
errorMessage	string | null	پیام خطای قابل نمایش به کاربر؛ در پاسخ‌های موفق null است
errorType	string | null	نام نوع خطا، مثل BadRequest یا UnAuthorized
errors	array	فهرست خطاهای جزئی؛ در پاسخ موفق آرایه‌ی خالی است

هر عضو آرایه‌ی errors سه فیلد دارد:

نام	نوع	توضیحات
property	string | null	نام فیلدی که خطا به آن مربوط است
message	string	شرح خطا (فارسی)
attemptedValue	any | null	مقداری که ارسال کرده‌اید

فیلد data

data بدنه‌ی اصلی پاسخ سرویس است و ساختار آن برای هر سرویس متفاوت است. در پاسخ‌های ناموفق مقدار آن null است.

نام فیلدهای data همیشه camelCase است: nationalCode، mobileNumber، iban، cardNumber.

نمونه‌ی پاسخ ناموفق

{
  "meta": {
    "trackId": "9b126e9a-184c-4cb0-a47e-62b9a3b7176f",
    "status": "kyc-v5-2",
    "isSuccess": false,
    "code": 2,
    "message": null,
    "errorMessage": "پارامتر های ارسالی معتبر نیستند",
    "errorType": "BadRequest",
    "errors": [
      {
        "property": "nationalCode",
        "message": "کد ملی باید ۱۰ رقم باشد",
        "attemptedValue": "12345"
      }
    ]
  },
  "data": null
}

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

1. کد وضعیت HTTP را بررسی کنید (200 یعنی درخواست پردازش شده است).
2. meta.isSuccess را بخوانید؛ فقط در صورت true سراغ data بروید.
3. در غیر این صورت meta.code را برای تصمیم‌گیری برنامه‌نویسی و meta.errorMessage را برای نمایش به کاربر استفاده کنید.
4. meta.trackId را همراه هر لاگ یا تیکت پشتیبانی ذخیره کنید.

مهم

هرگز روی متن errorMessage شرط‌گذاری نکنید؛ متن پیام‌ها ممکن است تغییر کند. منطق برنامه‌ی خود را روی meta.code بنویسید.