راهنمای توسعه‌دهندگان · نسخه ۱

یک اتصال، استعلام‌های قابل ردیابی

از پنل کاربران کلید پروژه بسازید، IP سرور را در فهرست مجاز ثبت و کیف پول را شارژ کنید؛ درخواست را فقط از سرور خودتان بفرستید.

ارسال استعلام

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

curl https://verifygate.ir/v1/inquiries/mobile \
  -H "Authorization: Bearer $VERIFYGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sample-request-0001" \
  -d '{"input":{"nationalCode":"0000000000","mobileNumber":"09000000000"},"options":{"consent":true,"maxAgeSeconds":300}}'

شماره‌های نمونه ساختگی‌اند؛ برای استعلام واقعی معتبر نیستند.

{
    "data": {
        "matched": true
    },
    "meta": {
        "requestId": "example",
        "service": "mobile",
        "source": "cache",
        "queriedAt": "2026-10-29T10:00:00+00:00",
        "expiresAt": "2026-10-29T10:05:00+00:00",
        "ttlSeconds": 300,
        "cacheable": true,
        "contract": "jibit-identicator-1.5.2"
    }
}

کیف پول و IP مجاز

برای پروژه‌های کاربران، Idempotency-Key الزامی است. فهرست IP خالی اتصال API را مسدود می‌کند. IP با اتصال واقعی و پراکسی مورد اعتماد بررسی می‌شود؛ هدر ارسالی خودتان آن را تغییر نمی‌دهد. خطای 402 یعنی موجودی کافی نیست، ip_not_allowed یعنی IP مجاز نیست، و tariff_not_configured یعنی تعرفه هنوز تنظیم نشده است. هزینه موفق مطابق تعرفه زنده یا کش از کیف پول کم می‌شود؛ پاسخ ناموفق هزینه فروش ندارد. مبلغ در حال اجرا رزرو می‌شود و در پنل قابل مشاهده است.

قواعد تازگی و جلوگیری از هزینه تکراری

maxAgeSeconds حداکثر سن قابل قبول شماست. مقدار صفر فقط پاسخ تازه می‌خواهد.
refresh=true نیازمند مجوز پروژه است و حداکثر ۵ بار در دقیقه برای هر سرویس مجاز است.
Idempotency-Key را برای تکرار همان درخواست ثابت نگه دارید. درخواست متفاوت با همان کلید، خطای 409 می‌دهد. پاسخ منقضی دوباره معتبر نمایش داده نمی‌شود.
خطای شبکه نتیجه نامعلوم دارد؛ آن را با کلید تازه خودکار تکرار نکنید. ممکن است هزینه نزد تأمین‌کننده ثبت شده باشد.
کش مشترک بین پروژه‌ها وجود ندارد. تغییر ورودی یا سیاست، کلید کش را تغییر می‌دهد.
خطاها کش نمی‌شوند؛ پاسخ نامعلوم و پاسخ دارای وضعیت حیات نگهداری نمی‌شود. هنگام قطع جیبیت از کش منقضی استفاده نمی‌شود.
خواندن از کش نیز در سقف درخواست پروژه محاسبه می‌شود. شمارش فراخوانی زنده جداگانه است.
تطبیق نام و موبایل تأیید فوت نیست. تصمیم فوت باید مسیر بررسی و تأیید مستقل داشته باشد.

سرویس‌های مستند

شناسه / مسیر	خدمت	TTL پیش‌فرض	ورودی
/v1/inquiries/card	اطلاعات کارت	300 ثانیه	number
/v1/inquiries/iban	اطلاعات شبا	300 ثانیه	value
/v1/inquiries/card-deposit	کارت به حساب	3600 ثانیه	number
/v1/inquiries/card-iban	کارت به شبا	3600 ثانیه	number
/v1/inquiries/availability	دسترسی بانک‌ها	30 ثانیه
/v1/inquiries/deposit-iban	حساب به شبا	3600 ثانیه	bank, number
/v1/inquiries/card-national	تطبیق کارت و کد ملی	300 ثانیه	cardNumber, nationalCode, birthDate
/v1/inquiries/deposit-national	تطبیق حساب و کد ملی	300 ثانیه	bank, depositNumber, nationalCode, birthDate
/v1/inquiries/iban-national	تطبیق شبا و کد ملی	300 ثانیه	iban, nationalCode, birthDate
/v1/inquiries/card-name	تطبیق کارت و نام	300 ثانیه	cardNumber, name
/v1/inquiries/deposit-name	تطبیق حساب و نام	300 ثانیه	bank, depositNumber, name
/v1/inquiries/iban-name	تطبیق شبا و نام	300 ثانیه	iban, name
/v1/inquiries/mobile	شاهکار؛ مالکیت موبایل	300 ثانیه	nationalCode, mobileNumber
/v1/inquiries/postal	نشانی کد پستی	86400 ثانیه	code
/v1/inquiries/postal-wgs	مختصات کد پستی	86400 ثانیه	code
/v1/inquiries/identity	ثبت احوال مقایسه‌ای	86400 ثانیه	nationalCode, birthDate, firstName, lastName, fullName, fatherName
/v1/inquiries/foreigner	هویت اتباع خارجی	3600 ثانیه	fida
/v1/inquiries/corporation	اطلاعات اصناف	3600 ثانیه	code
/v1/inquiries/military	نظام وظیفه	300 ثانیه	nationalCode
/v1/inquiries/sana	ثبت‌نام ثنا	300 ثانیه	nationalCode, mobileNumber
admin-only: balances	موجودی حساب تأمین‌کننده	0 ثانیه
admin-only: daily-report	گزارش روزانه تأمین‌کننده	60 ثانیه	yearMonthDay

برای identity حداقل یکی از firstName، lastName، fullName، fatherName لازم است. تاریخ تولد شمسی YYYYMMDD؛ گزارش روزانه yyMMdd؛ حساب با همان قالب بانک؛ شبا IR و ۲۴ رقم.

وضعیت پوشش

۲۰ عملیات استعلام در API پروژه‌ها و ۲ عملیات گزارش/موجودی فقط برای مدیر پیاده شده‌اند. تولید و تمدید توکن در داخل سرور مدیریت می‌شود. اجرای واقعی هر سرویس به مجوز جیبیت وابسته است.

وضعیت حیات: قرارداد API در مستند موجود نیست

اطلاعات کامل هویتی: نیازمند مستند جدید

چک صیادی: نیازمند مستند جدید

خدمات حقوقی شرکت‌ها: نیازمند مستند جدید

پرداخت، تسویه و امضای دیجیتال: خارج از قرارداد استعلام موجود

فهرست رسمی جیبیت · دریافت قرارداد OpenAPI

خطاها و امنیت

پاسخ خطا: {"error":{"code":"scope_forbidden"},"requestId":"..."}. کدهای 401 دسترسی، 403 مجوز، 409 تکرار/درحال‌اجرا/نامعلوم، 422 ورودی، 429 محدودیت، 502 تأمین‌کننده، 503 تنظیمات هستند. هیچ کلید یا اطلاعات شخصی در خطاها برگردانده نمی‌شود.

کلیدها یک بار نمایش داده می‌شوند؛ در کد مرورگر یا اپ موبایل قرار ندهید. برای چرخش، کلید جایگزین بسازید، مصرف‌کننده را تغییر دهید، سپس قبلی را باطل کنید. لاگ مصرف فاقد متن ورودی/پاسخ است؛ کش رمزگذاری‌شده پس از انقضا پاک می‌شود. لاگ مصرف ۹۰ روز و رویداد مدیریتی ۳۶۵ روز نگهداری می‌شوند.