sdk ارسال پیامک python

متد ارسال پیامک وب‌سرویس - send_webservice

    def send_webservice(self, message: str, sender: str, recipients: List[str]) -> Dict[str, Any]:
        """
        Send message via webservice.

        Args:
            message: Text message to send
            sender: Sender number
            recipients: List of recipient phone numbers

        Returns:
            API response
        """
        payload = {
            "from_number": sender,
            "message": message,
            "sending_type": "webservice",
            "params": {
                "recipients": recipients
            }
        }
        return self._post("/send", payload)
    

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

- message (str): متن پیامکی که قرار است ارسال شود.
- sender (str): شماره خط پیامکی فرستنده (که باید در پنل کاربری شما ثبت شده باشد).
- recipients (List[str]): لیستی از شماره‌های موبایل گیرندگان پیامک.

Dict[str, Any]: پاسخ دریافتی از API که معمولاً شامل اطلاعاتی درباره وضعیت ارسال است.

نحوه آماده‌سازی داده‌ها: پارامترهای ورودی در قالب یک دیکشنری به نام payload ساخته می‌شوند که شامل شماره فرستنده، متن پیام، نوع ارسال (`webservice`) و لیست گیرندگان است. سپس این payload به متد داخلی _post ارسال می‌شود.

متد ارسال پیامک الگو - send_pattern

    def send_pattern(self, pattern_code: str, sender: str, recipient: str,
                     params: Dict[str, Any]) -> Dict[str, Any]:
        """
        Send a message using a pre-defined pattern.

        Args:
            pattern_code: The pattern code
            sender: Sender number
            recipient: Recipient phone number
            params: Pattern parameters

        Returns:
            API response
        """
        payload = {
            "from_number": sender,
            "recipients": [recipient],
            "code": pattern_code,
            "params": params,
            "sending_type": "pattern"
        }
        return self._post("/send", payload)
    

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

- pattern_code (str): کد منحصر به فرد الگوی پیامکی که در پنل کاربری ایجاد شده است.
- sender (str): شماره خط پیامکی فرستنده.
- recipient (str): شماره موبایل گیرنده پیامک (در این حالت، معمولاً یک گیرنده واحد است).
- params (Dict[str, Any]): دیکشنری شامل مقادیری که باید در الگو جایگزین شوند (مانند نام کاربر، کد OTP، تاریخ و غیره).

Dict[str, Any]: پاسخ دریافتی از API.

نحوه آماده‌سازی داده‌ها: مشابه متد قبل، داده‌ها در قالب payload جمع‌آوری می‌شوند، اما با تفاوت‌هایی چون استفاده از pattern_code و params خاص الگو، و تعیین sending_type به صورت "pattern".

متد ارسال کد تایید صوتی - send_votp

    def send_votp(self, code: Union[int, str], recipient: str) -> Dict[str, Any]:
        """
        Send a voice OTP message.

        Args:
            code: OTP code
            recipient: Recipient phone number

        Returns:
            API response
        """
        payload = {
            "message": str(code),
            "sending_type": "votp",
            "params": {
                "recipients": [recipient]
            }
        }
        return self._post("/send", payload)
    

این متد برای ارسال کدهای تایید هویت (OTP) از طریق تماس صوتی استفاده می‌شود. این روش امنیت بالایی برای احراز هویت کاربران فراهم می‌کند.

- code (Union[int, str]): کد تایید که می‌تواند به صورت عدد یا رشته باشد. در نهایت به رشته تبدیل شده و ارسال می‌شود.
- recipient (str): شماره موبایل گیرنده کد تایید صوتی.

Dict[str, Any]: پاسخ دریافتی از API.

نحوه آماده‌سازی داده‌ها: کد OTP به عنوان message و sending_type روی "votp" تنظیم می‌شود. لیست گیرندگان نیز در بخش params قرار می‌گیرد.

متد داخلی ارسال درخواست POST - _post

    def _post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
        """
        Send a POST request to the API.

        Args:
            path: API endpoint path
            payload: Request payload

        Returns:
            API response data

        Raises:
            requests.HTTPError: If the request fails
        """
        url = f"{self.base_url}{path}"

        response = self.session.post(url, json=payload)
        response.raise_for_status()  # Raise exception for 4XX/5XX responses

        return response.json()
    

این یک متد "خصوصی" (با پیشوند underscore) است که به عنوان یک تابع کمکی برای ارسال درخواست‌های POST به API عمل می‌کند. تمامی متدهای ارسال پیامک در نهایت از این متد استفاده می‌کنند.

- path (str): مسیر (Endpoint) خاص API که درخواست به آن ارسال می‌شود (مثلاً `"/send"`).
- payload (Dict[str, Any]): داده‌های JSON که باید در بدنه درخواست ارسال شوند.

Dict[str, Any]: داده‌های JSON پاسخ دریافتی از سرور API.

requests.HTTPError: در صورتی که سرور API با خطای کلاینت (4xx) یا سرور (5xx) پاسخ دهد، این خطا پرتاب می‌شود و توسعه‌دهنده را از بروز مشکل مطلع می‌سازد.

نحوه عملکرد: آدرس کامل URL ساخته شده، درخواست POST با استفاده از نشست ایجاد شده ارسال می‌شود، و سپس متد raise_for_status() اطمینان حاصل می‌کند که در صورت وجود خطا در پاسخ HTTP، استثنا (Exception) ایجاد شود. در نهایت، پاسخ JSON از بدنه درخواست استخراج و برگردانده می‌شود.

این کلاس Client با ارائه متدهای واضح و تفکیک شده برای هر نوع ارسال پیام، فرآیند ادغام سرویس پیامک آرتا پیامک را برای توسعه‌دهندگان پایتون بسیار ساده و کاربرپسند می‌کند.