ورودی
- شماره موبایل
mobileشماره ایران، با یا بدون پیششماره ۹۸. ارقام فارسی و عربی پذیرفته و نرمال میشوند. - کد ملی
nationalIdده رقم با رقم کنترلی معتبر. این بررسی ساختاری است و بهتنهایی استعلام ثبت احوال نیست.
خروجی
- تطابق
matchedدرست یا نادرست بودن تعلق. - آزمایشی
mockدر محیط سندباکس همیشه درست است.
نمونهٔ درخواست و شکل پاسخ
نمونهٔ ساختار است و نتیجهٔ یک فراخوانی واقعی نیست.
POST /v1/services/mobile-national-match/execute
Authorization: Bearer zh_test_…
Idempotency-Key: <unique-per-operation>
{
"input": {
"mobile": "09123334455",
"nationalId": "0499370899"
}
}{
"requestId": "sreq_…",
"status": "SUCCEEDED | NEGATIVE | FAILED | UNKNOWN",
"data": { … },
"error": null,
"billing": { "status": "CHARGED | RELEASED | PENDING_RECONCILIATION", "amountRial": "…", "currency": "IRR" },
"mock": true
}خطاها و هزینه
VALIDATION_ERRORورودی از نظر ساختاری نامعتبر است و هزینهای ندارد.بدون هزینهFORBIDDENحساب یا کلید به این سرویس دسترسی ندارد و هزینهای ندارد.بدون هزینهRATE_LIMITEDمحدودیت نرخ اعمال شده و هزینهای ندارد.بدون هزینهINSUFFICIENT_FUNDSموجودی قابل استفاده کافی نیست و رزروی انجام نمیشود.بدون هزینهPROVIDER_ERRORخطای فنی قطعی است و رزرو آزاد میشود.بدون هزینهPROVIDER_TIMEOUTنتیجه نامعلوم است. وجه تا تعیین تکلیف رزرو میماند.بدون هزینهرفتار محیط آزمایشی: چهار رقم آخر موبایل: 0000 عدم تطابق، 0001 خطای فنی، 0002 مهلت نامعلوم، سایر موارد موفق آزمایشی.