زی‌هاب/سرویس‌ها/تطبیق موبایل و کد ملی

تطبیق موبایل و کد ملی

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

هویتی

ورودی

  • شماره موبایل 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 مهلت نامعلوم، سایر موارد موفق آزمایشی.