مستند وب سرویس

مفاهیم
url اصلی برای ارسال
تعیین کلید
پارامترها
دریافت وضعیت
وب هوک(دریافت)
دریافت تراز حساب

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

Json فرمتی ساده و قابل فهم برای ذخیره و انتقال پیام میباشد. در این فرمت معمولا از ساختار key: value استفاده میشود. مثال { کلید: مقدار}
کلید: در واقع کلید ها عناوین مقادیری هستند که باید به سمت درگاه وب سرویس ارسال شود.
HTTP request : درخواستی که در قالب پروتکل http ارسال میشود. این درخواست در ساده ترین حالت شامل دو بخش هدر و بدنه میشود.
HTTP Response : پاسخی که در پاسخ به درخواست http به کاربر داده میشود. این مورد یک پیام و یک کد وضعیت دارد. کد وضعیت بطور کلی مشکل اصلی را میبایست بشما نشان دهد. چنانچه کد وضعیت 200 باشد به این معناست که همه چیز درست است و شما پاسخ نرمال دریافت کرده اید. کد 404 نشان از اشتباه بودن آدرس URL دارد و شناسه 401 نشان میدهد که شما دسترسی کافی ندارید.
Apikey : یک کلید امنیتی که باید در حفظ آن کوشا باشید. این کلید شرط دسترسی به وب سرویس و ارسال پیام از طریق آن میباشد.
Header : همان HTTP Header است که برروی بسته های http قرار میگیرد و مواردی از جمله نوع داده، کلید دسترسی و… را در آن تعیین میکنند.
Content-type : یک مقدار واجب در هدر http میباشدکه تعیین کننده نوع محتواست. مثلا در وب فرم ها این مقدار برابر multipart/form-data است. در زمانیکه نیاز به ارسال داده ها در قالب json است این مقدار را application/json تعیین میکنیم.

https://api.behpardazjahan.com/api/v3.0.1/send

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

نیاز است برای بهره مندی از وب سرویس کلید داشته باشید. این کلید میبایست در هدر درخواست قرار گیرد. x-api-key عنوان پارامتری است که باید در هدر قرار گرفته باشد. در صورتی که این مورد در درخواست http شما شناسایی نشود یا به غلط باشد با خطای 401 مواجه خواهید شد.
کلید در پنل کاربری هر کاربر قابل تولید و نمایش است.

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

عنوان پارامتر	شرح	نوع داده
srcNum	شماره مبدا که قرار است با آن ارسال انجام شود.	string
recipient	شماره گیرنده / مخاطب	string
body	بدنه پیام / پیام اصلی	string
customerId	شناسه پیام (Checkingid)	int

در ابتدای شماره ها کد کشور که همان 98 برای ایران می باشد، باید قرار گیرد.

نکات شایان توجه:

مقادیر از نوع رشته یا string الزاما داخل “ قرار میگیرند. مثال “پیام من”
در وارد کردن عناوین یا بعبارتی همان key میبایست حروف بزرگ و کوچک رعایت شود.
فراموش نکنید که بدون وارد کردن کلید در هدر پیام. با وضعیت 401 مواجه خواهید شد.
حتما Content-Type را در هدر خود بصورت application/json قرار دهید.
پاسخ سرور به درخواست (Http Response)
پاسخ به درخواست نیز در قالب json ارائه میشود. این پاسخ چنانچه شما کد 200 را دریافت کنید یعنی هیچ مشکلی وجود نداشته و درخواست شما انجام شده است. اما چنانچه api key ناشناس باشد در ذیل میتوانید نمونه از هردو پاسخ را مشاهده نمایید.

				
					{
  "statuseCode": 401,
  "timestamp": "2023-10-62T14:07:45.398+00:00",
  "message": "API key is not valid",
  "description": "uri=/api/v3.0.1/send",
  "payload": null
}

				
					{
  "messageId": 7467173766,
  "scrNum": "989999991000",
  "recipient": "************",
  "customerId": 12,
  "statusCode": 200
}

آنچنانکه در تصاویر مشاهده میشود همواره در ابتدای شماره ها کد کشور که همان 98 برای ایران می باشد، قرار دارد.

عنوان پارامتر	شرح	نوع داده
messageId	شناسه ارسال که هنگام پردازش پیام تولید میشود	int
srcNum	شماره ارسال کننده	string
recipient	شماره گیرنده	string
customerId	شناسه پیام برای پیگیری های کاربر	int
status	وضعیت پیام	string
status Code	کد وضعیت http Request	int

چنانچه شما پاسخ با کد وضعیت 200 دریافت کردید این مورد الزاما بمعنای ارسال پیام نیست و باید به وضعیت در پاسخ دریافتی یا همان status توجه کنید. چنانچه ارسال پیام تائید نشود با REJECTED در این فیلد مواجه خواهید شد.

وضعیت پیام ( status Code ) ممکن است هرکدام از موارد زیر باشد، که در این صورت اشکالی در پردازش یا ارسال پیام وجود داشته است:

1-: محتوا تائید نمیشود. محتوای حساس

2-: بکاررفتن ایموجی در پیام وب سرویس

3-: شماره گیرنده دچار اشکال است

4-: شماره ارسال دچار اشکال است

خطای 400 نیز در شرایطی محتمل است که درخواست در فرمت نادرستی ارسال شود یا چنانچه شما دارای اعتبار مناسب نباشید. در پاسخ message برابر insufficient credit خواهد بود.

عموما دو نوع دریافت وضعیت مطرح است. در حالت اول بررسی وضعیت پیامی را داریم که طی دو روز اخیر فرستاده شده و در واقع آرشیو نشده است. در این صورت میتوانید به روش زیر اقدام کنید:
https://api.behpardazjahan.com/api/v3.0.1/get-status-customer-id
این آدرس برای دریافت وضعیت پیام ها با استفاده از آی دی customerId است که میتواند براحتی آنرا پس از ارسال پیام در پاسخی که از سوی سرور دریافت میکنید ببینید. به همین دلیل به این شناسه به CheckingID نیز شناخته میشود.

درحالت دوم، از ارسال پیام چند روز گذشته است و از آنجا که حداکثر پیام ها 48 ساعت در دیتابیس اصلی وجود دارند، پس از آن دیگر قادر نخواهید بود وضعیت دریافت کنید. میبایست تاریخ ارسال را در URL بشکل زیر وارد کنید:
https:// api.behpardazjahan.com /api/v3.0.1/get-status-archive-customer-id/[2023-10-23]

در مثال فوق تاریخ بیست و سوم 10 سال 2023 در نظر گرفته شده است و میتوانید تاریخ دلخواه را درآن جایگزین کنید. توجه داشته باشید که [] فقط جهت نمایش متغیر بودن در آدرس مذکور است و نباید آنرا در آدرس قرار دهید.

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

				
					[
....7467154372,
....123123123 
]

موارد فوق بواسطه شناسه customerId انجام میشد اما میتوان با استفاده از همین ساختار اما بکارگیری شناسه پیام یا همان messageId نیز این مورد را به انجام رساند.

بمنظور دریافت وضعیت از آدرس : https:// api.behpardazjahan.com/api/v3.0.1/get-status استفاده کنید.

ارسال درخواست به آدرس فوق الزام به در نظر گرفتن کلید x-api-key در هدر درخواست دارد.

status هایی که محتمل است دریافت کنید بشرح زیر است:

-1: NOT FOUND
0: ENQUEUED
1: DELIVERED
2: PENDING
3: FAILED
4: BLACKLISTED
7: REJECTED

چنانچه در فراخوانی این آدرس با خطای 401 مواجه شدید این مورد یقینا ناشی از قرار نگرفتن کلید در هدر می باشد.

برای دریافت از آرشیو هم امکان استفاده به همین سبک، از طریق آدرس زیر مهیاست:

https://api.behpardazjahan.com/api/v3.0.1/get-status-archive/2023-10-23

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

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

اگر قصد دریافت پیام بر پایه وب سرویس دارید، شما میتوانید با ارائه آدرس URL دلخواه درخواست کنید که پیام های دریافتی را در آن دریافت کنید. روش دریافت تنها بصورت query String است یعنی مقادیر در نوار آدرس بنمایش در خواهند آمد.

پارامترهایی که میتوان دریافت کرد:

Text محتوا
timestamp زمان ارسال
from فرستنده
to گیرنده
messaged شناسه پیام

آدرس به این صورت خواهد بود:

Your Domain/?text=11&timestamp=2023-11-20 14:13:17&from=989991994424&to=989999100000

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

آدرس: https://api.behpardazjahan.com/api/v3.0.1/balance

برای دریافت اعتبار فعلی نیاز به ارسال هیچ داده ای نیست و تنها کافی است در هدر خود x-api-key را قرار دهید. به این ترتیب در پاسخ تنها یک عدد دریافت میکنید که نشان از اعتبار فعلی حساب شما دارد.