مستندات سرویسهای استعلامی
راهنمای اتصال و استفاده کسبوکارهای تاییدشده از سرویسهای استعلامی NexPal.
v1
application/json
https://api.nexpal.io/v1/kyc
احراز هویت
کلید API اختصاصی کسبوکار را در هدر Authorization تمام درخواستهای
سرویسهای استعلامی ارسال کنید.
| محل ارسال | نام دقیق | نوع | الزامی | مقدار |
|---|---|---|---|---|
| هدر | Authorization |
string |
الزامی | Bearer YOUR_API_KEY |
| هدر | Content-Type |
string |
الزامی | application/json |
| هدر | Accept |
string |
پیشنهادی | application/json |
curl --request POST 'https://api.nexpal.io/v1/kyc/info/card-info' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"number":"1111222233334444"}'
با ثبت درخواست فعالسازی یا تولید مجدد قابل دریافت است. لطفا در حفظ و نگهداری آن کوشا باشید و در اختیار سایر اشخاص قرار ندهید.
فهرست سرویسها
همه سرویسها با متد POST و بدنه application/json فراخوانی میشوند.
هر زمان نیاز به وارد نمودن نام یا کد بانک بود باید آن را با حروف بزرگ و بر طبق جدول انتهای صفحه در درخواست خود وارد نمایید:
کد بانکهاکدهای پاسخ و خطا
قالب پاسخ موفق
پاسخ عمومی NexPal شامل هزینه سرویس با مالیات بر ارزش افزوده بهصورت رشته در cost و پاسخ استعلام
در data است. درخواستهای POST موفق با HTTP 201 پاسخ داده میشوند.
| نام | نوع | توضیح |
|---|---|---|
cost | string | مجموع هزینه پایه و مالیات به ریال؛ فقط نتیجه موفق سرویس از کیف پول کسر میشود |
baseCost | string | هزینه پایه همان فراخوانی، بدون مالیات، به ریال |
vatRate | string | نرخ درصد مالیات ثبتشده هنگام درخواست |
vatAmount | string | مبلغ مالیات به ریال، با گرد کردن HALF_UP به عدد صحیح |
data | object | پاسخ سرویس یا خطای اعلامشده توسط سرویس استعلام |
سرویسهای احراز اعتباری نیستند: پیش از فراخوانی باید موجودی کیف پول کارمزد برای مجموع هزینه پایه و مالیات کافی باشد. برای مثال، هزینه پایه ۵٬۰۰۰ ریال با نرخ مالیات ۱۰٪ به موجودی حداقل ۵٬۵۰۰ ریال نیاز دارد. هزینههای فهرست سرویسها، هزینه پایه و بدون مالیات هستند. تکرار درخواست با کلید یکسان، پاسخ و مالیات ثبتشده قبلی را برمیگرداند و دوباره هزینهای کسر نمیکند. فیلدهای تفکیک مالیات ممکن است در پاسخهای تاریخی وجود نداشته باشند.
اگر سرویس بالادستی خطای منطقی را با پاسخ HTTP موفق برگرداند، NexPal همان خطا را در
data و داخل پوسته پاسخ عمومی برمیگرداند. پیش از استفاده از نتیجه، ساختار
data را بررسی کنید.
{
"cost": "5500",
"baseCost": "5000",
"vatRate": "10",
"vatAmount": "500",
"data": {
"code": "0",
"MessageFromCore": {
"code": "card.not_valid",
"message": "کارت نامعتبر است"
}
}
}
خطاهای اعلامشده توسط سرویس استعلام
| کد | محل | توضیح |
|---|---|---|
invalid.request_body | data.MessageFromCore.code | بدنه درخواست از دید سرویس استعلام معتبر نیست. |
inquiry.failed | data.MessageFromCore.code | انجام استعلام ناموفق بوده است. |
card.not_valid | data.MessageFromCore.code | شماره کارت معتبر نیست. |
nationalCode.not_valid | data.MessageFromCore.code | کد ملی معتبر نیست. |
code و message | data | برخی خطاها بهصورت کد و پیام در سطح اول داده برمیگردند. |
خطاهای HTTP مشترک
| HTTP | پیام | توضیح |
|---|---|---|
| 400 | Bad Request | نوع، حضور یا قالب یکی از فیلدهای بدنه نامعتبر است؛ فهرست خطاهای فیلد در message میآید. |
| 401 | INVALID_KYC_API_KEY | هدر Bearer وجود ندارد یا کلید معتبر نیست. |
| 402 | INSUFFICIENT_FEE_BALANCE | موجودی کیف پول کارمزد برای هزینه سرویس و مالیات کافی نیست؛ سرویس احراز اعتبار منفی ندارد. |
| 500 | EHRAZ_VAT_CONFIGURATION_INVALID | نرخ مالیات سرویس پیکربندی نشده یا نامعتبر است؛ درخواست سرویس اجرا نمیشود. |
| 403 | KYC_ACCEPTOR_INACTIVE | دسترسی سرویسهای استعلامی کسبوکار فعال نیست. |
| 500 | EHRAZ_SERVICE_NOT_CONFIGURED | سرویس در NexPal پیکربندی نشده است. |
| 500 | EHRAZ_SERVICE_COST_INVALID | هزینه سرویس قابل پردازش نیست. |
| 500 | KYC_BILLING_FAILED | ثبت نهایی فراخوانی با خطای داخلی مواجه شده است. |
| 502 | EHRAZ_PROVIDER_UNAVAILABLE | ارتباط با سرویس استعلام برقرار نشد. |
| 502 | EHRAZ_PROVIDER_ERROR | سرویس استعلام خطای سمت سرور برگرداند. |
| 502 | EHRAZ_PROVIDER_REQUEST_FAILED | سرویس استعلام درخواست را با خطای HTTP رد کرد. |
| 502 | EHRAZ_PROVIDER_INVALID_RESPONSE | پاسخ سرویس استعلام JSON معتبر نیست. |
| 503 | EHRAZ_SERVICE_INACTIVE | سرویس انتخابی در حال حاضر فعال نیست. |
| 503 | EHRAZ_PROVIDER_NOT_CONFIGURED | سرویس استعلام موقتاً آماده ارائه نیست. |
| 504 | EHRAZ_PROVIDER_TIMEOUT | مهلت دریافت پاسخ پایان یافته است. |
کد بانکها
| Bank Code |
|---|
| MARKAZI |
| SANAT_VA_MADAN |
| MELLAT |
| REFAH |
| MASKAN |
| SEPAH |
| KESHAVARZI |
| MELLI |
| TEJARAT |
| SADERAT |
| TOSEAH_SADERAT |
| POST |
| TOSEAH_TAAVON |
| TOSEAH |
| GHAVAMIN |
| KARAFARIN |
| PARSIAN |
| EGHTESAD_NOVIN |
| SAMAN |
| PASARGAD |
| SARMAYEH |
| SINA |
| MEHR_IRANIAN |
| SHAHR |
| AYANDEH |
| ANSAR |
| GARDESHGARI |
| HEKMAT_IRANIAN |
| DAY |
| RESALAT |
| MELAL |
| MEHR_EGHTESAD |
| KHAVARMIANEH |
| NOOR |
| IRAN_VENEZUELA |
| UNKNOWN |