مستندات API | شمال اس ام اس

شروع سریع و راه‌اندازی وب‌سرویس

۴ گام تا اولین فراخوانی

عضویت و احراز هویت

ثبت‌نام سریع با شماره موبایل و در صورت نیاز تکمیل احراز هویت پایه در پنل کاربری.

شارژ اعتباری کیف پول

کیف پول حساب خود را به میزان دلخواه شارژ کنید؛ با اعتبار هدیه بلافاصله پس از ورود.

ثبت دامنه و دریافت API Key

در بخش کلیدهای API دامنه یا IP سرور خود را ثبت و توکن دسترسی با پیشوند ssk_ دریافت کنید.

ارسال درخواست استاندارد

درخواست‌های JSON خود را با هدر Bearer از سمت سرور برنامه ارسال کنید و پاسخ آنی استاندارد بگیرید.

هشدار امنیتی بسیار مهم: کلید اختصاصی API Key خود را هرگز در کدهای سمت کلاینت (فرانت‌اند جاوااسکریپت، سورس برنامه موبایل، مخازن عمومی گیت) قرار ندهید. همیشه فراخوانی‌ها را منحصراً از سمت بک‌اند (PHP، Node.js، Python، Laravel، ASP.NET و...) با هدرهای معتبر ارسال فرمایید.

احراز هویت و هدرهای الزامی (Request Headers)

Bearer Token

آدرس پایه API: https://shomalsms.ir/api/v1

کلیه درخواست‌ها باید به متد ذکرشده در هر بخش (عموماً POST) با فرمت UTF-8 و بدنه JSON به همراه هدرهای معتبر زیر ارسال گردند:

Authorization: Bearer ssk_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json

در صورت ارسال هدر Origin یا Referer، دامنه فرستنده باید با دامنه‌های تایید شده شما در پنل یکسان باشد. در صورتی که برای کلید خود IP مجاز تعریف کرده باشید، درخواست فقط از همان IPها پذیرفته خواهد شد.

مسیرها و وب‌سرویس‌های استعلامی (API Reference)

کلیه ۴۵ وب‌سرویس به صورت دسته‌بندی‌شده و همراه با نمونه فراخوانی cURL و پارامترها

۴۵ متد در دسترس

POST /api/v1/sms_vip سرویس پیامک ویژه (خط خدماتی اختصاصی با قالب ۱ تا ۹)

۳۵۰ تومان / هر ارسال

ارسال پیامک متنی، اطلاع‌رسانی، فاکتور یا کد فعال‌سازی از طریق خطوط خدماتی اختصاصی با قابلیت عبور از بلک‌لیست و انتخاب قالب اختصاصی تعریف‌شده در پنل کاربری (شماره ۱ تا ۹).

نکته مهم در محاسبه صفحات پیامک: در انتهای پیامک‌های این سرویس، کاراکتر خط بعدی به همراه عبارت لغو11 (مجموعاً ۶ کاراکتر) به صورت خودکار توسط اپراتور الصاق می‌شود. جهت ارسال در قالب ۱ صفحه (حداکثر ۷۰ کاراکتر یونیکد)، متن پیامک شما باید حداکثر ۶۴ کاراکتر باشد.

پارامتر	نوع	وضعیت	توضیحات
`mobile`	string	اجباری	شماره تلفن همراه گیرنده (فرمت ۰۹۱۲۱۲۳۴۵۶۷)
`template`	int	اختیاری	شماره قالب تعریف‌شده در پنل (از ۱ تا ۹، پیش‌فرض: ۱)
`code`	string	اختیاری	کد فعال‌سازی جهت جایگذاری در تگ `{code}` قالب
`message`	string	اختیاری	متن مستقیم پیامک (در صورت ارسال متن دلخواه بدون استفاده از قالب)

curl -X POST "https://shomalsms.ir/api/v1/sms_vip" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "09121234567", "template": 1, "code": "58291"}'

POST /api/v1/sms_otp سرویس OTP عادی (پیامک خدماتی اقتصادی)

۲۰۰ تومان / هر ارسال

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

پارامتر	نوع	وضعیت	توضیحات
`mobile`	string	اجباری	شماره تلفن همراه گیرنده
`code`	string	اجباری	کد عددی تایید (مانند 123456)
`template`	int	اختیاری	قالب متن: `0`=کد (پیش‌فرض) \| `1`=کد ورود \| `2`=کد تایید \| `3`=رمز \| `4`=رمز ورود

curl -X POST "https://shomalsms.ir/api/v1/sms_otp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "09354470806", "code": "123456", "template": 0}'

POST /api/v1/voice_otp سرویس OTP صوتی (تماس تلفنی خودکار)

۱۴۵ تومان / هر تماس

برقراری تماس تلفنی خودکار با کاربر و قرائت شمرده کد تایید به زبان فارسی (مناسب مواقع قطعی پیامک یا تلفن‌های ثابت).

پارامتر	نوع	وضعیت	توضیحات
`mobile`	string	اجباری	شماره تلفن همراه یا ثابت با پیش‌شماره
`code`	string	اجباری	کد عددی جهت قرائت (۴ تا ۸ رقم)

curl -X POST "https://shomalsms.ir/api/v1/voice_otp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "09121234567", "code": "7264"}'

POST /api/v1/shahkar استعلام شاهکار (تطابق مالکیت سیم‌کارت و کد ملی)

۸۰۰ تومان / هر استعلام

بررسی و اعتبارسنجی قطعی اینکه آیا شماره سیم‌کارت ارائه شده به نام صاحب کد ملی هست یا خیر (سامانه تنظیم مقررات و ارتباطات رادیویی).

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی متقاضی
`mobile`	string	اجباری	شماره تلفن همراه ۱۱ رقمی

curl -X POST "https://shomalsms.ir/api/v1/shahkar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678", "mobile": "09121234567"}'

POST /api/v1/person_info استعلام مشخصات هویتی و ثبت احوال

۸,۴۵۰ تومان / هر استعلام

استعلام نام، نام خانوادگی، نام پدر، وضعیت حیات و اطلاعات ثبتی شخص حقیقی از پایگاه داده ثبت احوال کشور.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی
`birth_date`	string	اجباری	تاریخ دقیق تولد (فرمت: 1370/01/01)

curl -X POST "https://shomalsms.ir/api/v1/person_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678", "birth_date": "1370/05/15"}'

POST /api/v1/military_status استعلام خدمت سربازی و وضعیت نظام وظیفه

۳,۱۲۰ تومان / هر استعلام

بررسی وضعیت کارت پایان خدمت، معافیت دائم یا موقت و وضعیت نظام وظیفه افراد در فرآیندهای استخدامی و اداری.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی فرد

curl -X POST "https://shomalsms.ir/api/v1/military_status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678"}'

POST /api/v1/sana استعلام سامانه ثنا (وضعیت ثبت‌نام قضایی)

۶۶۳ تومان / هر استعلام

استعلام وضعیت داشتن یا نداشتن حساب کاربری تایید شده در سامانه ابلاغ الکترونیک قضایی (ثنا).

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی

curl -X POST "https://shomalsms.ir/api/v1/sana" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678"}'

POST /api/v1/nationality_status استعلام وضعیت اتباع و کارت آمایش

۳,۷۹۲ تومان / هر استعلام

استعلام اعتبار کارت اتباع خارجی و مهاجرین از مراجع انتظامی و وزارت کشور.

پارامتر	نوع	وضعیت	توضیحات
`code`	string	اجباری	کد فراگیر اتباع یا شناسه آمایش
`code_type`	int	اختیاری	نوع مدرک (۱=کد فراگیر، ۲=آمایش)

curl -X POST "https://shomalsms.ir/api/v1/nationality_status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "98765432101", "code_type": 1}'

POST /api/v1/video_verify احراز ویدئویی بایومتریک و زنده‌سنجی هوشمند (Live+)

۳۰,۴۲۰ تومان / هر احراز

پردازش ویدیوی سلفی کوتاه کاربر، تطبیق چهره با تصویر کارت ملی و الگوریتم‌های هوش مصنوعی زنده سنجی (Liveness Detection).

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی فرد
`birth_date`	string	اجباری	تاریخ تولد

curl -X POST "https://shomalsms.ir/api/v1/video_verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678", "birth_date": "1370/01/01"}'

POST /api/v1/card_info استعلام نام مالک کارت بانکی شتابی

۴۰۰ تومان / هر استعلام

دریافت نام و نام خانوادگی صاحب کارت بانکی جهت جلوگیری از اشتباه در پرداخت و تسویه‌حساب.

پارامتر	نوع	وضعیت	توضیحات
`card_number`	string	اجباری	شماره ۱۶ رقمی کارت بانکی شتابی

curl -X POST "https://shomalsms.ir/api/v1/card_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"card_number": "6037991812345678"}'

POST /api/v1/card_to_iban سرویس تبدیل کارت بانکی به شماره شبا

۷۵۱ تومان / هر تبدیل

استخراج شماره شبا (IBAN) متناظر، شماره حساب و نام بانک صادرکننده از روی شماره ۱۶ رقمی کارت.

پارامتر	نوع	وضعیت	توضیحات
`card_number`	string	اجباری	شماره ۱۶ رقمی کارت بانکی

curl -X POST "https://shomalsms.ir/api/v1/card_to_iban" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"card_number": "6037991812345678"}'

POST /api/v1/bank_card_info استعلام مشخصات جامع کارت (نام + شبا + حساب)

۷۵۱ تومان / هر استعلام

استعلام همزمان نام دارنده کارت، شماره شبا، شماره حساب و نام بانک در یک درخواست واحد.

پارامتر	نوع	وضعیت	توضیحات
`card_number`	string	اجباری	شماره ۱۶ رقمی کارت

curl -X POST "https://shomalsms.ir/api/v1/bank_card_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"card_number": "6037991812345678"}'

POST /api/v1/iban_info استعلام نام صاحب شماره شبا

۳۸۰ تومان / هر استعلام

استعلام نام و نام خانوادگی، وضعیت فعال بودن حساب و نام بانک از روی شماره شبا.

پارامتر	نوع	وضعیت	توضیحات
`iban`	string	اجباری	شماره شبا (با یا بدون شناسه IR)

curl -X POST "https://shomalsms.ir/api/v1/iban_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"iban": "IR120120000000001234567890"}'

POST /api/v1/bank_account_info تبدیل شماره حساب بانکی به شماره شبا

۶۸۳ تومان / هر استعلام

محاسبه و دریافت شماره شبا معتبر بر اساس شماره حساب بانکی.

پارامتر	نوع	وضعیت	توضیحات
`account_number`	string	اجباری	شماره حساب بانکی
`bank`	string	اختیاری	نام یا کد بانک مربوطه

curl -X POST "https://shomalsms.ir/api/v1/bank_account_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_number": "123456789", "bank": "mellat"}'

POST /api/v1/card_match تطبیق کد ملی با شماره کارت بانکی

۲,۷۳۰ تومان / هر استعلام

اعتبارسنجی قطعی اینکه کارت بانکی ارائه شده متعلق به شخص صاحب کد ملی است یا خیر.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی متقاضی
`card_number`	string	اجباری	شماره ۱۶ رقمی کارت بانکی
`birth_date`	string	اختیاری	تاریخ تولد

curl -X POST "https://shomalsms.ir/api/v1/card_match" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678", "card_number": "6037991812345678"}'

POST /api/v1/iban_match تطبیق کد ملی با شماره شبا بانکی

۱,۳۰۰ تومان / هر استعلام

تطبیق مالکیت شماره شبا بانکی با کد ملی شخص قبل از انجام تسویه حساب‌های ریالی پایا و ساتنا.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی
`iban`	string	اجباری	شماره شبا (با یا بدون IR)
`birth_date`	string	اختیاری	تاریخ تولد

curl -X POST "https://shomalsms.ir/api/v1/iban_match" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678", "iban": "IR120120000000001234567890"}'

POST /api/v1/iban_match_pro تطبیق کد ملی با شبا پرو (سیاح - بدون نیاز به تاریخ تولد)

۱,۶۲۵ تومان / هر استعلام

سرویس سریع سیاح بانک مرکزی برای اعتبارسنجی شماره شبا و کدملی بدون نیاز به دریافت تاریخ تولد از کاربر.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی
`iban`	string	اجباری	شماره شبا

curl -X POST "https://shomalsms.ir/api/v1/iban_match_pro" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678", "iban": "IR120120000000001234567890"}'

POST /api/v1/card_mobile_match تطبیق شماره کارت بانکی با شماره موبایل

۲,۷۳۰ تومان / هر استعلام

تطبیق مستقیم مالکیت شماره موبایل با دارنده کارت بانکی بدون نیاز به دریافت کدملی اولیه.

پارامتر	نوع	وضعیت	توضیحات
`mobile`	string	اجباری	شماره موبایل
`card_number`	string	اجباری	شماره کارت ۱۶ رقمی

curl -X POST "https://shomalsms.ir/api/v1/card_mobile_match" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "09121234567", "card_number": "6037991812345678"}'

POST /api/v1/bank_account_match تطبیق شماره حساب بانکی با کد ملی

۱,۴۳۸ تومان / هر استعلام

بررسی همخوانی شماره حساب بانکی با کد ملی صاحب حساب.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی
`account_number`	string	اجباری	شماره حساب بانکی
`birth_date`	string	اختیاری	تاریخ تولد

curl -X POST "https://shomalsms.ir/api/v1/bank_account_match" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678", "account_number": "123456789"}'

POST /api/v1/cheque_info استعلام مشخصات چک صیادی (نام دارنده، شبا، تاریخ، مبلغ)

۱,۴۳۰ تومان / هر استعلام

دریافت نام صادرکننده، شماره شبا، شماره سریال، تاریخ سررسید و نوع چک با وارد کردن شناسه ۱۶ رقمی چک صیادی.

پارامتر	نوع	وضعیت	توضیحات
`sayad_id`	string	اجباری	شناسه ۱۶ رقمی صیادی چک

curl -X POST "https://shomalsms.ir/api/v1/cheque_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sayad_id": "1234567890123456"}'

POST /api/v1/cheque_color استعلام رنگ وضعیت اعتباری صادرکننده چک

۱,۴۳۰ تومان / هر استعلام

ارزیابی ریسک صادرکننده چک با بازگشت وضعیت رنگی (سفید، زرد، نارنجی، قهوه‌ای، قرمز) بر اساس سوابق برگشتی بانک مرکزی.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی صادرکننده چک

curl -X POST "https://shomalsms.ir/api/v1/cheque_color" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678"}'

POST /api/v1/unpaid_cheque_lite استعلام تعداد چک برگشتی (نسخه سبک Lite)

۶,۷۶۰ تومان / هر استعلام

استعلام سریع و کم‌هزینه صرفاً تعداد چک‌های برگشت‌خورده و رفع سوءاثر نشده فرد.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی فرد

curl -X POST "https://shomalsms.ir/api/v1/unpaid_cheque_lite" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678"}'

POST /api/v1/unpaid_cheque استعلام جامع چک‌های برگشتی (تعداد + مجموع مبلغ)

۷,۴۱۰ تومان / هر استعلام

استعلام پیشرفته چک برگشتی شامل تعداد چک‌ها و مبلغ دقیق چک‌های برگشت خورده فرد جهت ارزیابی ریسک اعتباری در معاملات تجاری.

پارامتر	نوع	وضعیت	توضیحات
`national_code`	string	اجباری	کد ملی ۱۰ رقمی

curl -X POST "https://shomalsms.ir/api/v1/unpaid_cheque" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_code": "0012345678"}'

POST /api/v1/power_bill وب سرویس استعلام بدهی قبض برق

۱۳۷ تومان / هر استعلام

استعلام آنی مبلغ بدهی، مهلت پرداخت و شناسه پرداخت قبض برق توانیر.

پارامتر	نوع	وضعیت	توضیحات
`bill_id`	string	اجباری	شناسه قبض ۱۳ رقمی برق

curl -X POST "https://shomalsms.ir/api/v1/power_bill" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_id": "1234567890123"}'

POST /api/v1/power_bill_info وب سرویس قبض برق با جزئیات کامل (مشخصات مشترک + مصرف)

۱۵۶ تومان / هر استعلام

استعلام بدهی + مشخصات کامل مشترک، آدرس کنتور، میزان مصرف کیلووات ساعت و دوره قرائت قبض برق.

پارامتر	نوع	وضعیت	توضیحات
`bill_id`	string	اجباری	شناسه قبض برق

curl -X POST "https://shomalsms.ir/api/v1/power_bill_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_id": "1234567890123"}'

POST /api/v1/water_bill وب سرویس استعلام قبض آب

۱۳۷ تومان / هر استعلام

استعلام وضعیت پرداخت، بدهی و شناسه پرداخت قبوض آب و فاضلاب مشترکین.

پارامتر	نوع	وضعیت	توضیحات
`bill_id`	string	اجباری	شناسه قبض آب

curl -X POST "https://shomalsms.ir/api/v1/water_bill" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_id": "1234567890123"}'

POST /api/v1/water_bill_info وب سرویس قبض آب با جزئیات (مشخصات مشترک + بدهی)

۱۵۶ تومان / هر استعلام

استعلام اطلاعات جامع قبض آب شامل نام مشترک، کاربری، آدرس و ریز بدهی قبوض آبفا.

پارامتر	نوع	وضعیت	توضیحات
`bill_id`	string	اجباری	شناسه قبض آب

curl -X POST "https://shomalsms.ir/api/v1/water_bill_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_id": "1234567890123"}'

POST /api/v1/gas_bill وب سرویس استعلام بدهی قبض گاز

۱۳۷ تومان / هر استعلام

استعلام بدهی قبوض گاز شرکت ملی گاز به صورت بلادرنگ.

پارامتر	نوع	وضعیت	توضیحات
`bill_id`	string	اجباری	شناسه اشتراک یا قبض گاز

curl -X POST "https://shomalsms.ir/api/v1/gas_bill" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_id": "1234567890123"}'

POST /api/v1/gas_bill_info وب سرویس قبض گاز با جزئیات (مشخصات مشترک + مصرف)

۱۵۶ تومان / هر استعلام

وضعیت پرداخت، بدهی، مشخصات اشتراک و حجم مصرف گاز مشترکین شرکت ملی گاز.

پارامتر	نوع	وضعیت	توضیحات
`bill_id`	string	اجباری	شناسه اشتراک یا قبض گاز

curl -X POST "https://shomalsms.ir/api/v1/gas_bill_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_id": "1234567890123"}'

POST /api/v1/company_info استعلام اطلاعات ثبتی شخص حقوقی (ثبت شرکت‌ها)

۴,۸۱۰ تومان / هر استعلام

استعلام نام رسمی شرکت، شماره ثبت، نوع شرکت، وضعیت فعالیت، آدرس قانونی و تاریخ ثبت از اداره کل ثبت شرکت‌ها.

پارامتر	نوع	وضعیت	توضیحات
`national_id`	string	اجباری	شناسه ملی ۱۱ رقمی شرکت

curl -X POST "https://shomalsms.ir/api/v1/company_info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_id": "10100000000"}'

POST /api/v1/company_members استعلام اعضای هیئت مدیره و بازرسین شرکت

۵,۱۵۷ تومان / هر استعلام

فهرست اعضای هیئت مدیره، مدیرعامل، بازرسین قانونی، کدملی و سمت‌های رسمی ثبت شده در آخرین تغییرات شرکت.

پارامتر	نوع	وضعیت	توضیحات
`national_id`	string	اجباری	شناسه ملی ۱۱ رقمی شرکت

curl -X POST "https://shomalsms.ir/api/v1/company_members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_id": "10100000000"}'

POST /api/v1/company_signatories استعلام صاحبین حق امضا و امضاداران رسمی شرکت

۷,۲۸۰ تومان / هر استعلام

بررسی اختیارات قانونی و افرادی که حق امضای قراردادها و اسناد تعهدآور مالی شرکت را طبق آخرین روزنامه رسمی دارند.

پارامتر	نوع	وضعیت	توضیحات
`national_id`	string	اجباری	شناسه ملی ۱۱ رقمی شرکت

curl -X POST "https://shomalsms.ir/api/v1/company_signatories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_id": "10100000000"}'

POST /api/v1/company_newspapers استعلام آگهی‌های تغییرات و تاسیس روزنامه رسمی

۵,۱۵۷ تومان / هر استعلام

فهرست و متن کامل آگهی‌های تاسیس و تغییرات منتشر شده در روزنامه رسمی قوه قضائیه.

پارامتر	نوع	وضعیت	توضیحات
`national_id`	string	اجباری	شناسه ملی شرکت

curl -X POST "https://shomalsms.ir/api/v1/company_newspapers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"national_id": "10100000000"}'

POST /api/v1/license استعلام اعتبار مجوز شغلی و پروانه کسب صنفی

۴,۵۵۰ تومان / هر استعلام

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

پارامتر	نوع	وضعیت	توضیحات
`code`	string	اجباری	شناسه صنفی یا کد رهگیری مجوز کسب

curl -X POST "https://shomalsms.ir/api/v1/license" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "12345678"}'

POST /api/v1/tax_records استعلام پرونده‌های مالیاتی و ثبت‌نام مودیان

۳,۶۴۰ تومان / هر استعلام

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

پارامتر	نوع	وضعیت	توضیحات
`code`	string	اجباری	کد ملی یا شناسه ملی مودی

curl -X POST "https://shomalsms.ir/api/v1/tax_records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "0012345678"}'

POST /api/v1/enamad استعلام اینماد و اطلاعات مالک وب‌سایت

۳,۷۷۰ تومان / هر استعلام

استعلام وضعیت اعتبار نماد اعتماد الکترونیکی (اینماد)، تاریخ اعتبار، ستاره‌ها و هویت صاحب امتیاز سایت.

پارامتر	نوع	وضعیت	توضیحات
`domain`	string	اجباری	دامنه سایت بدون پروتکل (مثلاً example.com)

curl -X POST "https://shomalsms.ir/api/v1/enamad" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

POST /api/v1/postal_code استعلام نشانی دقیق از کد پستی ۱۰ رقمی

۴,۵۵۰ تومان / هر استعلام

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

پارامتر	نوع	وضعیت	توضیحات
`postal_code`	string	اجباری	کد پستی ۱۰ رقمی بدون خط تیره

curl -X POST "https://shomalsms.ir/api/v1/postal_code" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"postal_code": "1234567890"}'

POST /api/v1/postal_tracking رهگیری بسته و مرسولات شرکت ملی پست

۲,۲۱۰ تومان / هر رهگیری

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

پارامتر	نوع	وضعیت	توضیحات
`barcode`	string	اجباری	بارکد ۲۴ رقمی بسته پستی

curl -X POST "https://shomalsms.ir/api/v1/postal_tracking" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"barcode": "111111111111111111111111"}'

POST /api/v1/geo_to_address تبدیل مختصات لوکیشن (Lat/Long) به آدرس متنی

۵۵ تومان / هر استعلام

دریافت استان، شهر، منطقه و آدرس متنی فارسی بر اساس مختصات نقطه Latitude و Longitude نقشه.

پارامتر	نوع	وضعیت	توضیحات
`latitude`	float	اجباری	عرض جغرافیایی نقطه
`longitude`	float	اجباری	طول جغرافیایی نقطه

curl -X POST "https://shomalsms.ir/api/v1/geo_to_address" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 35.6892, "longitude": 51.3890}'

POST /api/v1/text_to_speech تبدیل متن به گفتار صوتی هوش مصنوعی بومی

۸۲ تومان / هر تبدیل

تولید فایل صوتی با کیفیت بالا از متن فارسی بر بستر شبکه ملی اطلاعات بدون وابستگی خارجی.

پارامتر	نوع	وضعیت	توضیحات
`text`	string	اجباری	متن فارسی کوتاه
`male`	bool	اختیاری	صدای آقا (true - پیش‌فرض) یا خانم (false)
`ttsEngine`	int	اختیاری	کد موتور هوش مصنوعی: ۱ (هوشمند)، ۲ (بومی)، ۳ (خارجی)

curl -X POST "https://shomalsms.ir/api/v1/text_to_speech" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "سفارش شما با موفقیت ثبت شد", "male": true}'

POST /api/v1/check_email اعتبارسنجی صحت آدرس و فعال بودن صندوق ایمیل

۳۳ تومان / هر استعلام

بررسی صحت ساختار آدرس ایمیل، وجود رکوردهای MX سرور ایمیل و پاسخگویی میل‌باکس.

پارامتر	نوع	وضعیت	توضیحات
`email`	string	اجباری	آدرس ایمیل متقاضی

curl -X POST "https://shomalsms.ir/api/v1/check_email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

POST /api/v1/my_ip وب سرویس دریافت آدرس IP سرور کلاینت

۲۶ تومان / هر استعلام

شناسه و آدرس IP عمومی فرستنده درخواست را برمی‌گرداند (مناسب تست ارتباطات و فایروال).

curl -X POST "https://shomalsms.ir/api/v1/my_ip" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/ip_location وب سرویس ژئولوکیشن و تشخیص کشور و شهر IP

۱۹۵ تومان / هر استعلام

تشخیص کشور، استان، شهر و ISP اینترنت یک آدرس IP.

پارامتر	نوع	وضعیت	توضیحات
`ip`	string	اختیاری	آدرس IPv4 (پیش‌فرض: IP فرستنده)

curl -X POST "https://shomalsms.ir/api/v1/ip_location" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "5.160.0.1"}'

POST /api/v1/ip_is_iran وب سرویس تشخیص ایرانی بودن آدرس IP

۱۹۵ تومان / هر استعلام

بررسی سریع اینکه آیا IP مربوط به موقعیت جغرافیایی ایران است یا خیر (مناسب فیلتر ترافیک خارجی و فیلترشکن‌ها).

پارامتر	نوع	وضعیت	توضیحات
`ip`	string	اختیاری	آدرس IPv4

curl -X POST "https://shomalsms.ir/api/v1/ip_is_iran" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "5.160.0.1"}'

POST /api/v1/is_holiday استعلام وضعیت تعطیلی روز جاری در تقویم کشور

۱۹۵ تومان / هر استعلام

بررسی تعطیل بودن یا کاری بودن روز جاری طبق تقویم رسمی کشور (مناسب اجرای تسک‌ها و یادآورهای کاری).

curl -X POST "https://shomalsms.ir/api/v1/is_holiday" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/v1/balance استعلام مانده موجودی کیف پول

رایگان

دریافت موجودی ریالی و تومانی حساب کاربری متصل به کلید API.

curl -X GET "https://shomalsms.ir/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/v1/services دریافت لیست کامل وب‌سرویس‌ها و قیمت‌ها

رایگان

دریافت آرایه‌ای از کلیه سرویس‌های فعال همراه با کد اختصاصی، عنوان فارسی، واحد و قیمت مصوب.

curl -X GET "https://shomalsms.ir/api/v1/services" \
  -H "Authorization: Bearer YOUR_API_KEY"

مسیر یا متدی با عبارت جستجو شده پیدا نشد.

ساختار استاندارد پاسخ وب‌سرویس‌ها

کلیه پاسخ‌های موفق با کد HTTP 200 و کلید "ok": true به همراه کد رهگیری یکتا بازگردانده می‌شوند:

نمونه پاسخ موفق (HTTP 200)

{
  "ok": true,
  "request_id": "84a7e30d12f9b4c0",
  "service": "cheque_info",
  "units": 1,
  "cost": 1430,
  "balance": 98570,
  "result": {
    "sayadId": "1234567890123456",
    "ownerName": "نام دارنده چک",
    "iban": "IR120120000000001234567890",
    "dueDate": "1403/08/20",
    "amount": 500000000
  }
}

نمونه پاسخ خطا

{
  "ok": false,
  "error": "insufficient_balance",
  "message": "موجودی کیف پول شما برای این استعلام کافی نیست."
}

کدهای خطا و وضعیت HTTP

کد HTTP	کد خطا (error)	توضیح فارسی
401	`unauthorized`	کلید API ارسال نشده یا نامعتبر است
403	`site_not_approved` · `kyc_required`	دامنه سایت هنوز به تایید نرسیده یا احراز هویت حساب ناقص است
403	`ip_not_allowed` · `origin_not_allowed`	درخواست از IP یا دامنه غیرمجاز ارسال شده است
402	`insufficient_balance`	موجودی کیف پول برای انجام این درخواست کافی نیست
422	`invalid_parameters`	پارامترهای ورودی ناقص یا نامعتبر هستند (هیچ هزینه‌ای کسر نمی‌شود)
429	`rate_limited`	تعداد درخواست‌ها در دقیقه بیش از سقف مجاز است
502	`upstream_failed`	عدم پاسخگویی سامانه بالادستی؛ هزینه بلافاصله به حساب مسترد می‌گردد

تعرفه رسمی کلیه خدمات و استعلام‌ها

نرخ قطعی

کلیه قیمت‌ها بر اساس هر بار استعلام یا فراخوانی موفق به تومان محاسبه می‌گردند:

سرویس	واحد	مسیر فراخوانی	تعرفه (تومان)
سرویس پیامک ویژه	پیامک و OTP	هر صفحه پیامک	۳۵۰ تومان	فعال
سرویس OTP عادی	پیامک و OTP	هر ارسال	۲۰۰ تومان	فعال
سرویس OTP صوتی	پیامک و OTP	هر تماس	۱۴۵ تومان	فعال
استعلام شاهکار	هویتی و افراد	هر استعلام	۸۰۰ تومان	فعال
استعلام نام مالک کارت بانکی	بانکی و کارت	هر استعلام	۴۰۰ تومان	فعال
وب سرویس قبض برق با جزئیات	قبوض خدماتی	هر استعلام	۲۰۰ تومان	فعال
استعلام مشخصات چک صیادی	چک صیادی	هر استعلام	۱,۳۰۰ تومان	فعال
تبدیل لوکیشن به آدرس	پستی و ابزارها	هر استعلام	۵۰ تومان	فعال
وب سرویس قبض آب با جزئیات	قبوض خدماتی	هر استعلام	۲۰۰ تومان	فعال
استعلام خدمت سربازی	هویتی و افراد	هر استعلام	۲,۹۰۰ تومان	فعال
سرویس تبدیل کارت به شبا	بانکی و کارت	هر تبدیل	۷۰۰ تومان	فعال
احراز ویدئویی بایومتریک	هویتی و افراد	هر احراز	۳۰,۰۰۰ تومان	فعال
تطبیق کارت بانکی با موبایل	بانکی و کارت	هر استعلام	۲,۲۰۰ تومان	فعال
استعلام تعداد چک برگشتی Lite	چک صیادی	هر استعلام	۵,۵۰۰ تومان	فعال
استعلام رنگ چک صیادی	چک صیادی	هر استعلام	۱,۳۰۰ تومان	فعال
تطبیق کد ملی با شبا پرو (سیاح)	بانکی و کارت	هر استعلام	۱,۴۰۰ تومان	فعال
استعلام مشخصات هویتی	هویتی و افراد	هر استعلام	۷,۵۰۰ تومان	فعال
سرویس رهیگیری بسته پستی	پستی و ابزارها	هر رهگیری	۱,۹۰۰ تومان	فعال
تبدیل متن به صوت با هوش مصنوعی بومی	پستی و ابزارها	هر تبدیل	۸۵ تومان	فعال
استعلام شخص حقوقی	شرکتی و مالیات	هر استعلام	۴,۰۰۰ تومان	فعال
وب سرویس قبض گاز با جزئیات	قبوض خدماتی	هر استعلام	۲۰۰ تومان	فعال
استعلام اعتبار مجوز شغلی	شرکتی و مالیات	هر استعلام	۴,۰۰۰ تومان	فعال
استعلام سامانه ثنا	هویتی و افراد	هر استعلام	۷۰۰ تومان	فعال
استعلام وضعیت اتباع	هویتی و افراد	هر استعلام	۳,۵۰۰ تومان	فعال
استعلام اگهی های روزنامه رسمی	شرکتی و مالیات	هر استعلام	۴,۵۰۰ تومان	فعال
وب سرویس قبض گاز	قبوض خدماتی	هر استعلام	۱۵۰ تومان	فعال
تطبیق شماره حساب با کدملی	بانکی و کارت	هر استعلام	۱,۴۳۸ تومان	فعال
وب سرویس قبض برق	قبوض خدماتی	هر استعلام	۱۵۰ تومان	فعال
استعلام صاحبین حق امضا شرکتها	شرکتی و مالیات	هر استعلام	۷,۰۰۰ تومان	فعال
استعلام پرونده ها مالیاتی	شرکتی و مالیات	هر استعلام	۳,۵۰۰ تومان	فعال
استعلام اعضای هیئت مدیره	شرکتی و مالیات	هر استعلام	۵,۰۰۰ تومان	فعال
استعلام تعداد چک برگشتی	چک صیادی	هر استعلام	۷,۵۰۰ تومان	فعال
وب سرویس قبض آب	قبوض خدماتی	هر استعلام	۱۵۰ تومان	فعال
وب سرویس دریافت IP برنامه (کلاینت)	پستی و ابزارها	هر استعلام	۲۵ تومان	فعال
وب سرویس تشخیص موقعیت IP	پستی و ابزارها	هر استعلام	۱۶۰ تومان	فعال
استعلام مشخصات کارت بانکی	بانکی و کارت	هر استعلام	۶۵۰ تومان	فعال
سرویس استعلام کدپستی	پستی و ابزارها	هر استعلام	۴,۰۰۰ تومان	فعال
استعلام دارنده اینماد	شرکتی و مالیات	هر استعلام	۳,۳۰۰ تومان	فعال
وب سرویس تشخیص IP ایرانی	پستی و ابزارها	هر استعلام	۱۶۰ تومان	فعال
اعتبار سنجی ایمیل	پستی و ابزارها	هر استعلام	۵۰ تومان	فعال
استعلام شبا با شماره حساب	بانکی و کارت	هر استعلام	۶۰۰ تومان	فعال
استعلام نام دارنده شبا	بانکی و کارت	هر استعلام	۴۰۰ تومان	فعال
استعلام تعطیلی امروز	پستی و ابزارها	هر استعلام	۱۶۰ تومان	فعال
تطبیق کد ملی با کارت بانکی	بانکی و کارت	هر استعلام	۲,۴۰۰ تومان	فعال
تطبیق کد ملی با شبا	بانکی و کارت	هر استعلام	۱,۳۰۰ تومان	فعال

مستندات توسعه‌دهندگان و وب‌سرویس‌ها

شروع سریع و راه‌اندازی وب‌سرویس

عضویت و احراز هویت

شارژ اعتباری کیف پول

ثبت دامنه و دریافت API Key

ارسال درخواست استاندارد

احراز هویت و هدرهای الزامی (Request Headers)

مسیرها و وب‌سرویس‌های استعلامی (API Reference)

ساختار استاندارد پاسخ وب‌سرویس‌ها

نمونه پاسخ موفق (HTTP 200)

نمونه پاسخ خطا

کدهای خطا و وضعیت HTTP

تعرفه رسمی کلیه خدمات و استعلام‌ها