sdk ارسال پیامک go
کتابخانه Go برای اتصال به API پیامک

SDK پیامک Go برای اتصال سریع و قابل‌اعتماد به آرتا پیامک

ارسال پیامک در Golang با net/http، ساختار سبک و مدیریت خطای استاندارد Go

SDK پیامک Go امکان ارسال پیامک Webservice، پیامک Pattern و کد تأیید VOTP را در پروژه‌های Golang فراهم می‌کند. این پکیج از کتابخانه استاندارد net/http استفاده می‌کند و امکان تنظیم Base URL و HTTP Client را در اختیار توسعه‌دهنده قرار می‌دهد.

نصب و شروع سریع مشاهده نمونه کدهای Go
  • ✓ Webservice
  • ✓ Pattern
  • ✓ VOTP
  • ✓ Base URL سفارشی
نصب سریع با go get Timeout قابل تنظیم
main.go 
package main

import (
    "log"
    "github.com/ippanelcom/golang-sdk/ippanel"
)

func main() {
    client := ippanel.NewClient(
        "YOUR_API_KEY",
    )

    response, err := client.SendWebservice(
        "پیام آزمایشی آرتا پیامک",
        "+983000505",
        []string{"+989123456789"},
    )

    if err != nil {
        log.Fatal(err)
    }

    log.Println(response.Meta.Status)
}
توسعه سریع‌تر در Golang

چرا از SDK پیامک Go آرتا پیامک استفاده کنیم؟

این کتابخانه برای توسعه‌دهندگانی مناسب است که می‌خواهند فرایند اتصال Go به API پیامک را با ساختاری شفاف، سبک و هماهنگ با الگوهای رایج Golang پیاده‌سازی کنند.

پیاده‌سازی با net/http استاندارد

لایه ارتباط HTTP پکیج با کتابخانه استاندارد Go ساخته شده و در سورس بررسی‌شده به وابستگی خارجی نیاز ندارد.

کنترل مستقیم روی Client

HTTP Client در دسترس است؛ بنابراین می‌توانید timeout و تنظیمات موردنیاز ارتباط را متناسب با پروژه تغییر دهید.

مدیریت خطا به سبک Go

متدهای عمومی پکیج، پاسخ و error را برمی‌گردانند تا مدیریت خطا در همان جریان استاندارد پروژه انجام شود.

قابلیت‌های تأییدشده در سورس

ویژگی‌های فنی SDK پیامک Go

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

سه روش ارسال پیام

پشتیبانی از ارسال Webservice، پیامک Pattern و کد تأیید VOTP از طریق سه متد عمومی مجزا.

Authorization Header

API Key تعریف‌شده در Client مستقیماً در هدر Authorization درخواست‌های API قرار می‌گیرد.

Timeout پیش‌فرض ۱۰ ثانیه

Client پیش‌فرض با timeout ده‌ثانیه‌ای ساخته می‌شود و امکان جایگزینی آن با http.Client دلخواه وجود دارد.

Base URL قابل تنظیم

هنگام ساخت Client می‌توان به‌جای آدرس پیش‌فرض، یک Base URL سفارشی را به‌عنوان پارامتر دوم تعریف کرد.

شروع سریع

نصب SDK پیامک Go با go get

برای راه‌اندازی کتابخانه ارسال پیامک Golang، ابتدا نسخه معرفی‌شده در README پکیج را نصب کرده و سپس Client را با API Key حساب خود ایجاد کنید.

مراحل اتصال Go به پنل پیامک

نصب و استفاده اولیه از SDK تنها به دریافت پکیج، import کردن namespace و ساخت Client نیاز دارد.

  • ۱ نصب نسخه v1.0.0 با دستور go get
  • ۲ Import کردن پکیج ippanel در پروژه
  • ۳ ساخت Client با API Key معتبر
  • ۴ فراخوانی متد ارسال متناسب با سناریو

حداقل نسخه موردنیاز Go در README آرشیو بررسی‌شده مشخص نشده است؛ بنابراین بهتر است سازگاری را در محیط پروژه خود بررسی کنید.

Terminal + main.go Go SDK 
# Install version v1.0.0
go get github.com/ippanelcom/golang-sdk@v1.0.0

// Import package
import (
    "github.com/ippanelcom/golang-sdk/ippanel"
)

// Create client
client := ippanel.NewClient(
    "YOUR_API_KEY",
)
عملیات اصلی پکیج

روش‌های ارسال پیامک در Golang

هر سه عملیات به endpoint ارسال متصل می‌شوند و مقدار sending_type نوع ارسال پیام را مشخص می‌کند.

SendWebservice

ارسال پیامک Webservice در Go

این متد برای ارسال متن عادی به یک یا چند گیرنده کاربرد دارد و شماره‌های مقصد را به‌صورت آرایه دریافت می‌کند.

  • دریافت متن پیام و شماره فرستنده
  • پشتیبانی از آرایه شماره‌های گیرنده
  • مناسب اعلان‌ها و پیام‌های عمومی
SendPattern

ارسال پیامک Pattern با Golang

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

  • دریافت Pattern Code
  • پشتیبانی از پارامترهای پویا با map
  • دریافت یک گیرنده در امضای فعلی متد
SendVOTP

ارسال کد تأیید VOTP در Go

متد VOTP یک کد عددی از نوع int32 و شماره گیرنده را دریافت می‌کند و کد را برای ارسال به رشته تبدیل می‌کند.

  • مناسب سناریوهای احراز هویت
  • دریافت کد عددی int32
  • دریافت شماره یک گیرنده
ارسال متن عادی

نمونه ارسال پیامک Webservice با Golang

متد SendWebservice متن پیام، شماره فرستنده و آرایه‌ای از گیرندگان را دریافت می‌کند. خروجی متد شامل یک اشاره‌گر به SendResponse و مقدار error است.

  • ✓ ارسال درخواست POST به مسیر /send
  • ✓ مقدار sending_type برابر webservice
  • ✓ ارسال گیرندگان در params.recipients
webservice.go SendWebservice 
response, err := client.SendWebservice(
    "پیام آزمایشی آرتا پیامک",
    "+983000505",
    []string{
        "+989123456789",
        "+989356789012",
    },
)

if err != nil {
    log.Fatalf(
        "send failed: %v",
        err,
    )
}

log.Println(response.Meta.Status)
پیام‌های قالبی و تأیید

نمونه ارسال Pattern و VOTP با Go

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

pattern.go SendPattern 
response, err := client.SendPattern(
    "PATTERN_CODE",
    "+983000505",
    "+989123456789",
    map[string]interface{}{
        "name": "فرید",
        "code": "4821",
    },
)

if err != nil {
    log.Fatal(err)
}

log.Println(response.Meta.Message)
votp.go SendVOTP 
response, err := client.SendVOTP(
    123456,
    "+989123456789",
)

if err != nil {
    log.Fatalf(
        "VOTP failed: %v",
        err,
    )
}

log.Println(
    response.Meta.Status,
    response.Meta.Message,
)

در امضای فعلی SendPattern فقط یک گیرنده از نوع string دریافت می‌شود. برای جلوگیری از خطا، Pattern Code و نام پارامترها را دقیقاً مطابق الگوی ثبت‌شده در پنل وارد کنید.

کنترل تنظیمات اتصال

تنظیم Base URL و Timeout در Go SDK

این پکیج برای سناریوهایی که به URL یا HTTP Client سفارشی نیاز دارند، امکان تغییر تنظیمات پیش‌فرض را فراهم می‌کند.

custom-base-url.go Base URL 
client := ippanel.NewClient(
    "YOUR_API_KEY",
    "https://custom.example/api",
)
custom-timeout.go HTTP Client 
client := ippanel.NewClient(
    "YOUR_API_KEY",
)

client.HTTPClient = &http.Client{
    Timeout: 30 * time.Second,
}

Base URL پیش‌فرض پکیج https://edge.ippanel.com/v1/api است. از آنجا که مسیر درخواست با الحاق رشته‌ای ساخته می‌شود، Base URL سفارشی را بدون اسلش انتهایی وارد کنید.

مسیر اجرای درخواست

فرایند ارسال پیامک با API در پروژه Go

پس از ساخت Client، داده‌ها به JSON تبدیل شده و درخواست HTTP همراه با API Key به endpoint ارسال می‌شود.

ساخت Client

API Key و در صورت نیاز Base URL سفارشی در اختیار NewClient قرار می‌گیرد.

انتخاب روش ارسال

براساس سناریو، یکی از متدهای Webservice، Pattern یا VOTP فراخوانی می‌شود.

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

Payload به JSON تبدیل شده و درخواست به مسیر /send ارسال می‌شود.

بررسی Response و Error

نتیجه موفق در SendResponse و مشکل درخواست در مقدار error در دسترس قرار می‌گیرد.

پاسخ و خطا

مدیریت خطا در SDK پیامک Go چگونه انجام می‌شود؟

متدهای عمومی خروجی را به‌شکل (*SendResponse, error) برمی‌گردانند و خطاهای مختلف درخواست در مراحل مشخص تولید می‌شوند.

مرحله رفتار پکیج خروجی احتمالی
تبدیل Payload تبدیل ساختار درخواست به JSON پیش از ایجاد درخواست HTTP failed to marshal request
ساخت Request ایجاد درخواست POST و افزودن Headerهای لازم failed to create request
اجرای درخواست ارسال درخواست توسط HTTP Client تنظیم‌شده request failed
HTTP Status ناموفق برای status code برابر یا بزرگ‌تر از ۴۰۰، متن خام پاسخ به‌شکل error برمی‌گردد. Raw response body
پاسخ موفق JSON پاسخ در ساختار SendResponse و Meta decode می‌شود. *SendResponse

نسخه بررسی‌شده دارای retry یا backoff داخلی نیست. اگر پروژه شما به تلاش مجدد نیاز دارد، این منطق را با توجه به نوع خطا و سیاست سرویس در لایه برنامه پیاده‌سازی کنید. برای جزئیات بیشتر به راهنمای خطاهای API پیامک مراجعه کنید.

ادامه مسیر توسعه

مستندات و منابع تکمیلی SDK پیامک Go

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

پرسش‌های توسعه‌دهندگان

سوالات متداول SDK پیامک Go

پاسخ پرسش‌های رایج درباره نصب، Base URL، متدهای ارسال، timeout و مدیریت خطا در کتابخانه پیامک Golang.

SDK پیامک Go چه روش‌های ارسالی را پشتیبانی می‌کند؟

این پکیج سه متد عمومی SendWebservice برای پیام متنی عادی، SendPattern برای پیام‌های الگویی و SendVOTP برای ارسال کد تأیید دارد.

چگونه SDK پیامک Go را نصب کنیم؟

مطابق README پکیج، نسخه v1.0.0 با دستور go get github.com/ippanelcom/golang-sdk@v1.0.0 نصب می‌شود. سپس پکیج ippanel را در پروژه import کرده و Client را با API Key می‌سازید.

آیا امکان تغییر Base URL در Go SDK وجود دارد؟

بله. تابع NewClient یک پارامتر اختیاری برای Base URL سفارشی دریافت می‌کند. به‌دلیل الحاق مستقیم مسیر درخواست، بهتر است URL سفارشی بدون اسلش انتهایی وارد شود.

API Key در درخواست‌های Go چگونه ارسال می‌شود؟

API Key ذخیره‌شده در Client مستقیماً در هدر Authorization قرار می‌گیرد. SDK در نسخه بررسی‌شده پیشوندی مانند Bearer به مقدار کلید اضافه نمی‌کند.

آیا می‌توان timeout درخواست‌های پیامک را تغییر داد؟

بله. timeout پیش‌فرض Client برابر ۱۰ ثانیه است، اما می‌توانید فیلد HTTPClient را با یک http.Client سفارشی و timeout دلخواه جایگزین کنید.

مدیریت خطا در SDK پیامک Golang چگونه است؟

متدهای عمومی پاسخ و error را به سبک استاندارد Go برمی‌گردانند. در status codeهای ۴۰۰ و بالاتر، متن خام بدنه پاسخ به‌عنوان error بازگردانده می‌شود.

آیا ارسال Pattern برای چند گیرنده پشتیبانی می‌شود؟

در امضای فعلی متد SendPattern فقط یک recipient از نوع string دریافت می‌شود؛ هرچند مقدار گیرنده در Payload داخلی داخل آرایه قرار می‌گیرد.

آیا SDK پیامک Go وابستگی خارجی دارد؟

در سورس بررسی‌شده فقط پکیج‌های استاندارد Go مانند net/http، encoding/json، bytes، errors، fmt، io و time استفاده شده‌اند و وابستگی خارجی دیگری در فایل SDK مشاهده نشد.

آیا این SDK دارای retry خودکار است؟

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

اتصال پروژه Go به سرویس پیامک را شروع کنید

SDK پیامک Go را نصب کنید، Client را با API Key بسازید و متناسب با نیاز پروژه از ارسال Webservice، Pattern یا VOTP استفاده کنید.

مشاهده دستور نصب مطالعه مستندات API