پارسی

مستندات API پلتفرم پیام آراد

به مستندات API پلتفرم پیام آراد (شرکت آراد) خوش آمدید. این راهنما به شما کمک می‌کند تا با پلتفرم قدرتمند پیامکی ما که روزانه بیش از 300 میلیون پیام ارسال می‌کند و 60% از ترافیک پیامکی ایران را پوشش می‌دهد، ادغام شوید. این پلتفرم توسط سازمان‌های بزرگی مانند آسیاتک، آرین تل، جیرینگ و بانک‌های پیشرو نظیر بانک ملت، بانک سپه، بانک ملی، بانک صادرات و ... مورد استفاده قرار گرفته است.

معرفی

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

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

برای مستندات دقیق‌تر و آزمایش زنده API به مستندات Swagger مراجعه کنید.

احراز هویت

API پلتفرم پیام آراد از سه روش احراز هویت پشتیبانی می‌کند:

احراز هویت پایه (Basic Authentication):
- این روش نام کاربری و رمز عبور را به Base64 رمزگذاری کرده و در هدر Authorization قرار می‌دهد.
- نکته: به دلیل آسیب‌پذیری‌های امنیتی، این روش توصیه نمی‌شود.
مثال:
```
نام کاربری: AradUser
رمز عبور: AradPassword

Base64("AradUser:AradPassword") => QXJhZFVzZXI6QXJhZFBhc3N3b3Jk

Authorization: Basic QXJhZFVzZXI6QXJhZFBhc3N3b3Jk
```

توکن Bearer:

با فراخوانی آدرس /connect/token با اطلاعات کاربری خود، یک توکن دریافت کنید. این توکن به مدت 5 دقیقه معتبر است.

درخواست:

POST https://api.aradvas.ir/connect/token
Content-Type: application/x-www-form-urlencoded

بدنه:
grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD&scope=ApiAccess

پاسخ:

{
    "access_token": "توکن شما",
    "expires_at": "2022-08-01T05:02:37Z",
    "scope": "ApiAccess"
}

کلید API:
- یک کلید API از داشبورد خود تولید کرده و آن را در هدر X-API-Key قرار دهید.
مثال:
```
X-API-Key: YOUR_API_KEY
```

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

آدرس های API

دسترسی و Scope های API

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

Scope: ApiAccess

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

Endpoints:

/api/message/send
/api/message/GetDLR
/api/message/GetDLRByPartId
/api/message/GetMO
/api/message/GetMOByDate

Scope: ApiPatternAccess

این سطح دسترسی برای ارسال پیام‌های مبتنی بر الگو (Pattern-Based Messaging) استفاده می‌شود.

Endpoints:

/api/patternMessage/send
/api/patternMessage/sendMultiple

Scope: BulkApiAccess

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

Endpoints:

/api/message/bulk
/api/message/P2PBulk
/api/message/GetDLR
/api/message/GetDLRByPartId
/api/message/GetMO
/api/message/GetMOByDate

Scope: WhiteListAccess

این سطح دسترسی برای ارسال پیام به شماره‌های ثبت‌شده در لیست سفید (WhiteList) استفاده می‌شود.

Endpoints:

/api/message/SendToWhiteList

ارسال پیامک

برای ارسال یک یا چند پیامک از آدرس زیر استفاده کنید:

آدرس:

POST https://api.aradvas.ir/api/{apiversion}/message/send

هدرها:

Authorization: Bearer {your access token} | Basic | ApiKey
Content-Type: application/json

پارامترهای بدنه:

پارامتر	نوع	توضیحات
`SourceAddress`	string	شماره فرستنده
`DestinationAddress`	string	شماره گیرنده
`MessageText`	string	محتوای پیامک
`ValidityPeriod`	string	مدت اعتبار پیام (1 دقیقه تا 6 ساعت)
`TargetUDH`	array	اختیاری. تنظیمات پورت و شماره مرجع
`DataCoding`	int	کدگذاری داده (8 برای فارسی، 1 برای انگلیسی)
`MessageClass`	string	نوع پیام (متنی، باینری، ایمیل، صوتی)
`ServiceID`	string	شناسه سرویس ارزش افزوده
`Priority`	int	اولویت پیام (0 تا 7)
`UDH`	string	هدر تعریف شده توسط کاربر برای تگ گذاری پیام

نمونه درخواست:

[
  {
    "SourceAddress": "989000xxxx",
    "DestinationAddress": "9891xxxxxxxx",
    "MessageText": "پیام تستی",
    "TargetUDH": ["port:5000", "referenceNumberType:16bit"]
  }
]

نمونه پاسخ:

{
  "message": "با موفقیت انجام شد.",
  "succeeded": true,
  "data": ["624ed1bbcd0efb1ef148e0a0"],
  "resultCode": 100
}

ارسال گروهی و P2P

برای ارسال پیامک‌های گروهی و P2P (شخص به شخص) از این آدرس ها استفاده کنید.

آدرس برای ارسال گروهی:

POST https://api.aradvas.ir/api/{apiversion}/message/bulk

نمونه درخواست برای ارسال گروهی:

{
  "SourceAddress": "989000xxxx",
  "MessageText": "پیشنهاد ویژه از آراد!",
  "DestinationAddress": ["9891xxxxxxxx", "9891yyyyyyyy", "9891zzzzzzzz"]
}

آدرس برای ارسال بالک P2P:

POST https://api.aradvas.ir/api/{apiversion}/message/P2PBulk

نمونه درخواست برای ارسال P2P:

{
  "SourceAddress": "989000xxxx",
  "Messages": [
    {
      "DestinationAddress": "9891xxxxxxxx",
      "MessageText": "سلام علی! وقت ملاقات شما ساعت 3 بعد از ظهر است."
    },
    {
      "DestinationAddress": "9891yyyyyyyy",
      "MessageText": "سلام سارا! سفارش شما #1234 ارسال شده است."
    }
  ]
}

ارسال پیام از طریق GET

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

آدرس:

GET https://api.aradvas.ir/api/{apiversion}/message/send

پارامترهای مورد نیاز:

پارامتر	نوع	توضیحات
`SourceAddress`	string	شماره فرستنده
`DestinationAddress`	string	شماره گیرنده (در صورت چند گیرنده با کاما جدا شود)
`MessageText`	string	محتوای پیامک
`port`	int	پورت (اختیاری)
`referenceNumberType`	string	نوع شماره مرجع (8bit یا 16bit)

نمونه درخواست:

https://api.aradvas.ir/api/message/send?SourceAddress=989000xxxx&DestinationAddress=98912xxxxxxx&MessageText=test&port=5000&referenceNumberType=16bit

نمونه پاسخ:

{
    "message": "Successfully done.",
    "succeeded": true,
    "data": [
        "62e760d2393e38af65bb9e4e"
    ],
    "resultCode": 100
}

دریافت پیام‌ها

برای دریافت پیام‌های ورودی (MO) از آدرس زیر استفاده کنید:

آدرس:

GET https://api.aradvas.ir/api/{apiversion}/message/getmo

نمونه پاسخ:

{
  "message": "با موفقیت انجام شد.",
  "succeeded": true,
  "data": [
    {
      "sourceAddress": "9891xxxxxxxx",
      "destinationAddress": "989000xxxx",
      "messageText": "سلام!",
      "receiveDateTime": "2022-04-04T11:23:11.211Z"
    }
  ],
  "resultCode": 100
}

گزارش تحویل

برای دریافت وضعیت تحویل پیام‌ها از آدرس زیر استفاده کنید:

آدرس:

GET https://api.aradvas.ir/api/{apiversion}/message/dlr?messageId=624ed1bbcd0efb1ef148e0a0

نمونه پاسخ:

{
  "message": "با موفقیت انجام شد.",
  "succeeded": true,
  "data": [
    {
      "messageId": "624ed1bbcd0efb1ef148e0a0",
      "status": "delivered",
      "deliveryDateTime": "2022-04-04T12:00:00.000Z"
    }
  ],
  "resultCode": 100
}

دریافت اطلاعات کاربر

برای دریافت اطلاعات کاربری شامل اعتبار، شماره‌های اختصاصی، و محدودیت‌های ارسال، از متد زیر استفاده کنید:

آدرس:

GET https://api.aradvas.ir/api/user/userinfo

نمونه پاسخ:

{
    "message": "Successfully done.",
    "succeeded": true,
    "data": {
        "userName": "username",
        "firstName": "name",
        "lastName": "family",
        "credit": 5000.0,
        "mps": 1000,
        "senderIds": [
            "989000xxxx",
            "9890001xxx"
        ]
    },
    "resultCode": 100
}

ارسال پیام از طریق الگو

برای استفاده از ارسال پیام بر اساس الگو ابتدا باید یک Pattern در داشبورد تعریف و تأیید شود. سپس می‌توانید از متد زیر استفاده کنید:

آدرس:

POST https://api.aradvas.ir/api/PatternMessage/send

پارامترهای مورد نیاز:

پارامتر	نوع	توضیحات
`Destinations`	Array	لیست شماره‌های گیرنده
`Parameters`	Array	پارامترهای جایگزین در الگو
`PatternId`	string	شناسه الگو از داشبورد

نمونه درخواست:

{
    "Destinations": ["9891xxxxxxx"],
    "Parameters": ["آقای", "سعید سعیدی", "ملت"],
    "PatternId": "12345-pattern-id"
}

نمونه پاسخ:

{
    "message": "Successfully done.",
    "succeeded": true,
    "data": ["624ed1bbcd0efb1ef148e0a0"],
    "resultCode": 100
}

متدهای کمکی (پینگ و بررسی آی‌پی)

بررسی آی‌پی

برای بررسی آی‌پی کاربر از متد زیر استفاده کنید:

GET https://api.aradvas.ir/api/Tools/CheckIp

پاسخ: آی‌پی کاربر برگردانده می‌شود.

متد Ping

برای بررسی سلامت سرور از متد زیر استفاده کنید:

GET https://api.aradvas.ir/api/Tools/Ping

پاسخ: مقدار `PONG` برگردانده می‌شود.

کدهای خطا

در اینجا کدهای خطای اختصاصی API پلتفرم پیام آراد آورده شده است:

خطاهای ارسال

Code	Error	توضیحات
0	Send Error	خطا در فرآیند ارسال پیام رخ داده است.
-1	Not Enough Credit	موجودی برای ارسال پیام کافی نیست.
-2	Server Error	خطای غیرمنتظره‌ای در سرور رخ داده است.
-3	DE ACTIVE Account	حساب کاربری غیرفعال است.
-4	Expired Account	حساب کاربری منقضی شده است.
-5	Invalid Username or Password	نام کاربری یا رمز عبور اشتباه وارد شده است.
-6	Authentication Failure	فرآیند احراز هویت ناموفق بود.
-7	Server Busy	سرور در حال حاضر مشغول است.
-8	Number At Blacklist	شماره گیرنده در لیست سیاه قرار دارد.
-9	Limited In Send Day	محدودیت روزانه ارسال پیام تجاوز شده است.
-10	Limited In Volume	محدودیت حجم ارسال پیام تجاوز شده است.
-11	Invalid Sender Number	شماره فرستنده نامعتبر است.
-12	Invalid Receiver Number	شماره گیرنده نامعتبر است.
-13	Invalid Destination Network	شبکه مقصد نامعتبر است.
-14	Unreachable Network	شبکه مقصد در دسترس نیست.
-15	DE ACTIVE Sender Number	شماره فرستنده غیرفعال است.
-16	Invalid Format of Sender Number	فرمت شماره فرستنده نادرست است.
-17	Tariff Not Found	تعرفه‌ای برای این پیام پیدا نشد.
-18	Invalid IP Address	آدرس IP فرستنده نامعتبر است.
-19	Invalid Pattern	الگوی پیام نامعتبر است.
-20	Expired Sender Number	شماره فرستنده منقضی شده است.
-21	Message Contains Link	پیام حاوی لینک است.
-22	Invalid Port	پورت نامعتبر است.
-23	Message Too Long	متن پیام بیش از حد طولانی است.
-24	Filter Word	پیام شامل کلمات فیلتر شده است.
-25	Invalid Reference Number Type	نوع شماره مرجع نامعتبر است.
-26	Invalid Target UDH	داده UDH هدف نامعتبر است.
-27	Limited In Send Month	محدودیت ارسال ماهانه تجاوز شده است.
-28	Data Coding Not Allowed	کدگذاری داده مجاز نیست.
-29	Not Found Route	مسیری برای ارسال پیام پیدا نشد.
-30	Message Contains Scripts	پیام حاوی اسکریپت است.
-31	Setting Not Found	تنظیمات لازم برای ارسال پیام پیدا نشد.
-32	Content Filter	محتوای پیام فیلتر شده است.
-33	Invalid Character	پیام شامل کاراکترهای نامعتبر است.
-34	SMS Wallet Not Enough Credit	موجودی کیف پول پیامک کافی نیست.
-35	Campaign Exists	کمپین از قبل وجود دارد.
-36	Approver Not Found	تأییدکننده پیدا نشد.
-37	Due Date Less Than Current Date	تاریخ موعد کمتر از تاریخ فعلی است.
-38	Invalid Message Request ID	شناسه درخواست پیام نامعتبر است.
-39	Message Request Not Waiting For Approve	درخواست پیام در انتظار تأیید نیست.
-40	Expire Date Less Than Due Date	تاریخ انقضا کمتر از تاریخ موعد است.
-41	Limited In Schedule	محدودیت در زمان‌بندی ارسال پیام تجاوز شده است.
-42	Too Many Requests	تعداد درخواست‌های ارسال بیش از حد مجاز است.
-43	Cache Server Error	خطایی در سرور کش رخ داده است.

کدهای وضعیت تحویل

این کدها وضعیت تحویل پیام‌های شما را نشان می‌دهد.

Code	Status	توضیحات
1	Delivered	پیام با موفقیت به گوشی گیرنده تحویل داده شد.
2	UnDelivered	پیام به گیرنده تحویل داده نشد.
3	Accepted	پیام توسط سرویس‌دهنده دریافت شده و در انتظار ارسال است.
5	Rejected	پیام توسط سرویس‌دهنده رد شده است.
7	ErrorInSending	در فرآیند ارسال پیام خطایی رخ داده است.
8	WaitingForSend	پیام در انتظار ارسال است.
9	Sent	پیام ارسال شده است.
10	NotSent	پیام ارسال نشده است.
11	Expired	پیام پیش از تحویل منقضی شده است.
14	BlackList	شماره گیرنده در لیست سیاه قرار دارد.
15	SmsIsFilter	محتوای پیام فیلتر شده است.
16	Deleted	پیام حذف شده است.
29	Stored	پیام ذخیره شده است.
32	Unknown	وضعیت تحویل پیام نامشخص است.
33	Enroute	پیام در مسیر ارسال است؛ وضعیت نهایی مشخص نشده است.
34	Undeliverable	پیام غیرقابل تحویل است.
36	UnreachableNetwork	شبکه گیرنده در دسترس نیست.

کدهای بازگشتی API

این کدها پاسخ‌های API به درخواست‌های شما را نشان می‌دهد.

Code	Status	توضیحات
100	Succeeded	درخواست با موفقیت پردازش شد.
101	Database Error	خطایی در پایگاه داده رخ داده است.
102	Repository Error	خطایی در لایه مخزن داده رخ داده است.
103	Model Error	خطایی در مدل داده وجود دارد.
104	API Connection Attempt Failure	اتصال به API ناموفق بود.
105	Service Un-Available	سرویس در حال حاضر در دسترس نیست.
106	Confirm Email Failed	تأیید ایمیل ناموفق بود.
107	User Not Found	کاربر پیدا نشد.
108	Duplicate Error	مورد موردنظر قبلاً وجود دارد.
109	Not Found	مورد درخواست شده پیدا نشد.
110	Unable To Create Result Api Error	ایجاد پاسخ API ممکن نشد.
111	Auto Mapper Error	در فرآیند نگاشت شیء خطایی رخ داده است.
112	General Failure	یک خطای عمومی رخ داده است.
113	Web Service Error	در سرویس وب شخص ثالث خطایی رخ داده است.
114	Error Getting Token from Idp	دریافت توکن از ارائه‌دهنده هویت (IdP) ناموفق بود.
115	Error Retrieving Data from AppSettings	بازیابی داده‌ها از تنظیمات برنامه ناموفق بود.
116	Header Error	هدرهای درخواست به درستی پیکربندی نشده‌اند.
117	Bad Request Error	مشکلی در بدنه درخواست وجود دارد.
118	Rate Limit Exceed Response	کاربر از حد مجاز نرخ ارسال فراتر رفته است.
119	User Tariff Null	هیچ تعرفه‌ای به کاربر اختصاص داده نشده است.
120	Limit On Daily Submissions	کاربر به حد مجاز ارسال روزانه رسیده است.
121	Limit On Monthly Submissions	کاربر به حد مجاز ارسال ماهانه رسیده است.
122	Send To Whitelist Only	ارسال فقط به لیست سفید مجاز است.
123	Enter Whitelist Template	وارد کردن نام الگوی لیست سفید الزامی است.
124	Enter Whitelist Message Text	وارد کردن متن پیام لیست سفید الزامی است.
125	Whitelist Template Not Found	الگوی لیست سفید مشخص‌شده پیدا نشد.

نمونه درخواست‌ها

ارسال پیامک تکی

POST https://api.aradvas.ir/api/{apiversion}/message/send
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

بدنه:
[
  {
    "SourceAddress": "989000xxxx",
    "DestinationAddress": "9891xxxxxxxx",
    "MessageText": "سلام از پلتفرم پیام آراد!"
  }
]

ارسال پیامک گروهی

POST https://api.aradvas.ir/api/{apiversion}/message/bulk
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

بدنه:
{
  "SourceAddress": "989000xxxx",
  "MessageText": "پیشنهاد ویژه از آراد!",
  "DestinationAddress": ["9891xxxxxxxx", "9891yyyyyyyy", "9891zzzzzzzz"]
}

دریافت پیام‌های دریافتی (MO)

GET https://api.aradvas.ir/api/{apiversion}/message/getmo
Authorization: Bearer YOUR_ACCESS_TOKEN

دریافت گزارش تحویل

GET https://api.aradvas.ir/api/{apiversion}/message/dlr?messageId=624ed1bbcd0efb1ef148e0a0
Authorization: Bearer YOUR_ACCESS_TOKEN

تماس و پشتیبانی

برای دریافت کمک یا پرسش‌های بیشتر، با تیم پشتیبانی ما تماس بگیرید:

تلفن:

+98 31 91083200
+98 31 91083100

ایمیل:

info@arad-itc.org

وب سایت:

www.arad-itc.com

تیم پشتیبانی ما در ساعات کاری آماده پاسخگویی به سؤالات فنی و مشکلات مرتبط با API است.

از اینکه از ** پلتفرم پیام آراد** استفاده می‌کنید سپاسگزاریم. امیدواریم تجربه‌ای مطمئن و کارآمد از پیام‌رسانی داشته باشید!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

پارسی

مستندات API پلتفرم پیام آراد

فهرست مطالب

معرفی

احراز هویت

آدرس های API

دسترسی و Scope های API

Scope: ApiAccess

Scope: ApiPatternAccess

Scope: BulkApiAccess

Scope: WhiteListAccess

ارسال پیامک

ارسال گروهی و P2P

ارسال پیام از طریق GET

دریافت پیام‌ها

گزارش تحویل

دریافت اطلاعات کاربر

ارسال پیام از طریق الگو

متدهای کمکی (پینگ و بررسی آی‌پی)

بررسی آی‌پی

متد Ping

پاسخ: مقدار `PONG` برگردانده می‌شود.

کدهای خطا

خطاهای ارسال

کدهای وضعیت تحویل

کدهای بازگشتی API

نمونه درخواست‌ها

ارسال پیامک تکی

ارسال پیامک گروهی

دریافت پیام‌های دریافتی (MO)

دریافت گزارش تحویل

تماس و پشتیبانی

Clone this wiki locally

پارسی

مستندات API پلتفرم پیام آراد

فهرست مطالب

معرفی

احراز هویت

آدرس های API

دسترسی و Scope های API

Scope: ApiAccess

Scope: ApiPatternAccess

Scope: BulkApiAccess

Scope: WhiteListAccess

ارسال پیامک

ارسال گروهی و P2P

ارسال پیام از طریق GET

دریافت پیام‌ها

گزارش تحویل

دریافت اطلاعات کاربر

ارسال پیام از طریق الگو

متدهای کمکی (پینگ و بررسی آی‌پی)

بررسی آی‌پی

متد Ping

پاسخ: مقدار PONG برگردانده می‌شود.

کدهای خطا

خطاهای ارسال

کدهای وضعیت تحویل

کدهای بازگشتی API

نمونه درخواست‌ها

ارسال پیامک تکی

ارسال پیامک گروهی

دریافت پیام‌های دریافتی (MO)

دریافت گزارش تحویل

تماس و پشتیبانی

Clone this wiki locally

پاسخ: مقدار `PONG` برگردانده می‌شود.