خانه راهنمای استفاده مستندات API

# فراخوانی اولیه

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

# گام ۱ — دریافت توکن 

curl 'https://zarin-hub.com/api/v5/Authentication/GetToken' \
  -H 'Content-Type: application/json' \
  --data-binary '{"username":"YOUR_API_USERNAME","password":"YOUR_API_PASSWORD"}'

{
  "meta": { "isSuccess": true, "code": 0, "trackId": "..." },
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresTn": 28800,
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

accessToken را نگه دارید؛ تا ۸ ساعت معتبر است.

# گام ۲ — آزمودن اتصال

سرویس فهرست بانک‌های ایران داده‌ی ایستا برمی‌گرداند و ساده‌ترین راه برای اطمینان از درستی توکن و اتصال است:

curl 'https://zarin-hub.com/api/v5/KYC/BankInfo' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '{}'

اگر پاسخ با "isSuccess": true برگشت، اتصال شما درست است.

# گام ۳ — یک استعلام واقعی 

curl 'https://zarin-hub.com/api/v5/KYC/CheckShahkar' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '{
    "nationalCode": "0012345678",
    "mobileNumber": "09123456789",
    "trackId": "9b126e9a-184c-4cb0-a47e-62b9a3b7176f"
  }'

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

# سیاهه‌ی وارسی

  • [ ] توکن را یک‌بار گرفته‌ام و تا پایان اعتبارش نگه می‌دارم.
  • [ ] برای هر فراخوانی یک trackId تازه می‌سازم و ذخیره می‌کنم.
  • [ ] پیش از خواندن data، مقدار meta.isSuccess را بررسی می‌کنم.
  • [ ] منطق برنامه‌ام روی meta.code نوشته شده، نه روی متن پیام خطا.
  • [ ] مهلت پاسخ کلاینت را دست‌کم روی ۳۰ ثانیه گذاشته‌ام.

# گام بعد

در این صفحه