مقدمه
وب‌سرویس ارائه‌شده در این مستند، مبتنی بر پروتکل SOAP است. برنامه‌نویسان می‌توانند با اتصال به این سرویس و نوشتن چند خط کد، به‌راحتی از خدمات پیام کوتاه ساپک استفاده کنند.
پیشنهاد ما به برنامه نویسان استفاده از وب سرویس REST به جای SOAP است. وب سرویس SOAP نخستین وب سرویس سامانه پیامکی ساپک بود و برای سازگاری با ارسال های قدیمی همچنان ارائه می شود.
شرایط استفاده
برای استفاده از وب سرویس SOAP باید پنل پیامکی ساپک را تهیه نمایید. توجه داشته باشید که پنلی را انتخاب نمایید که وب سرویس از امکانات آن باشد.
همچنین برای استفاده از وب سرویس SOAP باید کلمه عبور مخصوص آن را تعریف نمایید. برای این منظور وارد پنل شده و در بخش تظنیمات، کلمه عبور وب سرویس SOAP را تعریف نمایید.
از کلمه عبور پنل نمی توانید برای استفاده از وب سرویس استفاده نمایید.
آدرس اندپوینت
برای اتصال به وب سرویس، از آدرس زیر استفاده نمایید:
https://api.sapak.me/soap/smsService.svc
یا در صورت نیاز به صورت زیر استفاده شود:
https://api.sapak.me/soap/smsService.svc?singlewsdl
برای استفاده از وب‌سرویس، ابتدا باید در پنل ارسال پیامک ساپک ثبت‌نام کنید و سپس پنل دارای وب‌سرویس را خریداری کنید. در فراخوانی هر متد، باید نام کاربری و کلمه عبور را وارد کنید که همان نام کاربری و کلمه عبور ورود به پنل است. برای امنیت بیشتر، می‌توانید در بخش تنظیمات پنل، رمز مخصوص وب‌سرویس را تعریف کنید.
مفاهیم اولیه
پیش از بررسی متدهای موجود در این وب‌سرویس، لازم است برخی مفاهیم آن توضیح داده شوند. این مفاهیم به برنامه‌نویس کمک می‌کنند تا ارسال و دریافت پیامک‌ها را بهتر مدیریت کند.
انکدینگ پیامک
هر پیامک بسته به متن آن می‌تواند از نوع اسکی (ASCII) یا یونیکد باشد. برای ذخیره‌سازی هر یک از کاراکترهای استاندارد ASCII (مانند حروف لاتین، اعداد و علائم استاندارد مثل +، = و &) که با صفحه‌کلید انگلیسی قابل تایپ هستند، تنها یک بایت نیاز است. در حالی که برای ذخیره‌سازی هر یک از کاراکترهای یونیکد (مانند حروف فارسی، سایر زبان‌های دنیا یا کاراکترهای خاص مثل Ω) به دو بایت نیاز است.
بنابراین، نوع کاراکترهای استفاده‌شده در پیامک بر طول آن تأثیر می‌گذارد. هر پیامک نمی‌تواند بیش از ۱۱۲۰ بیت (معادل ۱۴۰ بایت) باشد. این یعنی ۱۶۰ کاراکتر ۷ بیتی (برای اسکی) یا ۷۰ کاراکتر ۱۶ بیتی (برای یونیکد). از آنجایی که زبان‌هایی مانند فارسی، چینی یا ژاپنی به استفاده از کاراکترهای ۱۶ بیتی (UTF-16/UCS-2) نیاز دارند، در پیامک‌های فارسی نمی‌توان بیش از ۷۰ کاراکتر داشت.
تعیین انکدینگ پیامک
وجود تنها یک کاراکتر یونیکد در متن پیامک کافی است تا کل پیامک به‌صورت یونیکد در نظر گرفته شود. برای مثال، استفاده از یک حرف فارسی در یک پیامک انگلیسی باعث می‌شود تمام محدودیت‌های پیامک‌های یونیکد برای آن اعمال شود.
بخش بندی پیامک
در صورتی که طول پیامک از حد مجاز بیشتر شود، عملیات بخش‌بندی روی آن انجام می‌شود و پیامک در قالب چند بخش (پارت) ارسال می‌گردد. در پیامک‌های فارسی، برای هر بخش ۳ کاراکتر از تعداد کاراکترهای مجاز کسر می‌شود. برای مثال، در یک پیامک فارسی ۸۰ کاراکتری، ۶۷ کاراکتر اول در بخش اول و باقی کاراکترها در بخش دوم قرار می‌گیرند. در پیامک‌های انگلیسی، برای هر بخش ۷ کاراکتر کسر می‌شود. با این حال، کل متن به‌صورت یکپارچه به گیرنده می‌رسد.
در تعداد محدودی از اپراتورهای پیامکی، تعداد کاراکترها در هر بخش ممکن است کمی متفاوت باشد.
حداکثر تعداد بخشهای پیامک
حداکثر تعداد بخش‌ها در اپراتورهای مختلف متفاوت است، اما معمولاً حداقل از ۱۰ بخش پشتیبانی می‌شود. اگر متن ارسالی شما طولانی است، توصیه می‌شود پیش از ارسال انبوه، با خط پیامکی موردنظر آزمایش انجام دهید تا از ارسال کامل آن مطمئن شوید.
فرمت های شماره فرستنده
شماره فرستنده همان شماره پیامکی شما است. دقیقاً همان چیزی که در لیست شماره‌های پیامکی خود در پنل مشاهده می‌کنید، می‌توانید به‌عنوان شماره فرستنده در وب سرویس استفاده کنید. مانند موارد زیر:
30001234
500012345678
ServiceLine
Tabligh
فرمت های شماره گیرنده
شماره‌های گیرنده، همان شماره‌های موبایلی هستند که پیامک برای آن‌ها ارسال می‌شود. فرمت‌های قابل‌قبول به‌صورت زیر است:
9xxxxxxxxx
09xxxxxxxxx
989xxxxxxxxx
+989xxxxxxxxx
00989xxxxxxxxx
بلک لیست مخابرات
بلک‌لیست مخابرات به مشترکانی اشاره دارد که امکان دریافت پیامک‌های تبلیغاتی را مسدود کرده‌اند. بنابراین، اگر با خطوط پیامک انبوه به این شماره‌ها پیامک ارسال کنید، پیام شما به دست آن‌ها نمی‌رسد. اما وب‌سرویس ساپک به‌صورت هوشمند پیام شما را به گیرنده می‌رساند. برای این منظور، در پنل خود به بخش «تنظیمات» و سپس «بلک‌لیست مخابرات» مراجعه کنید و نحوه ارسال به بلک‌لیست را مشخص کنید. برای ارسال به بلک‌لیست، دو گزینه «خط تبلیغ» و «خط خدماتی» وجود دارد. اگر متن پیام شما تبلیغاتی نیست، توصیه می شود از گزینه خط خدماتی استفاده کنید.
هنگام استفاده از وب‌سرویس، چنانچه خط خدماتی ندارید می‌توانید با خیال راحت با خط تبلیغاتی خود پیامک ارسال کنید. در حین ارسال، سیستم به‌صورت هوشمند وضعیت بلک‌لیست هر شماره را تشخیص می‌دهد و از طریق روشی که در تنظیمات مشخص کرده‌اید، پیام شما را به گیرندگان می‌رساند.