برای انجام تنظیمات دسترسیهای API بعد از ورود به پنل دفترشما، به بخش «توسعهدهندگان» بروید و گزینه «API» را انتخاب کنید. تا صفحهی «دسترسیهای API» به نمایش درآید. اگر تا به حال برای دسترسی API تنظیماتی انجام دادهاید و توکنی تعریف کردهاید در این صفحه لیست آنها را خواهید دید. در غیر اینصورت تنها گزینه «ایجاد توکن جدید» را میبینید.
توجه: راهنمای کدهای ارسالی و دریافتی با API در لینک «راهنمای swagger» قرار دارد.
ساخت توکن برای دسترسی API
برای دسترسی امن به APIهای دفترشما لازم است توکن دسترسی (API Token) تعریف کنیم تا مجبور به ثبت نام کاربری و رمز عبور در هر درخواست نباشیم.
این توکن در واقع نقش کد اعتبارسنجی هر درخواستی است که به پنل دفترشما زده میشود است و مشخص میکند که درخواست کننده کیست و اجازه دسترسی به کدام APIها را دارد.
برای ساخت توکن جدید:
- روی دکمه «ایجاد توکن جدید» کلیک کنید و در پنجره بازشده، اطلاعات لازم را ثبت کنید.
- یک نام اختصاصی برای توکن انتخاب کنید تا در لیست توکنها قابل شناسایی باشند.
- مدت اعتبار توکن را مشخص کنید اگر مایل هستید توکن تا تاریخ مشخصی یا بیش از 90 روز، اعتبار داشته باشد، گزینه «سفارشی» را در منوی کشویی انتخاب کنید و در فیلد روبرو، تاریخ موردنظر را تعیین کنید.
- در فیلد آخر مشخص میکنید این توکن، کلید دسترسی به کدام APIها است. میتوانید گزینه «دسترسی کامل» را انتخاب کنید یا با کلیک روی گزینه «درخواست شخصیسازی شده»، این توکن را برای یکی از API های «گزارش تماس» یا «تماس خروجی» فعال کنید.
5. در نهایت روی دکمه «ایجاد توکن» کلیک کنید.
6. حالا یک کد که همان توکن است آماده شده است. آن را کپی کنید و در اختیار دولوپر قرار دهید تا دسترسی API به درستی برقرار شود.
نکات مهم:
- توکن فقط یکبار نمایش داده میشود. فراموش نکنید آن را در جای امن نگهداری کنید.
- هر توکن فقط به API هایی که در زمان ایجاد مشخص شدهاند دسترسی دارد .
- مدت اعتبار توکن قابل تنظیم و قابل ویرایش است.
نحوه استفاده از توکن در درخواستها
تمامی درخواستهای API باید شامل توکن در Header باشند:
Authorization: Bearer YOUR_API_TOKEN
در صورت ارسال توکن نامعتبر یا منقضیشده، درخواست با خطای 4۰1 مواجه خواهد شد.
آدرس پایه API (Base URL)
https://coreapi.daftareshoma.com/api/Customize/API-NAME
تمام Endpoint ها نسبت به این آدرس فراخوانی میشوند.
اطلاعات دریافتی در API گزارش تماس
با فراخوانی این API ، با توجه به مقادیر ورودی ارسال شده، سطرهای گزارش تماس مورد انتظار برگشت داده میشود. یعنی مشترک
لیست جامعی از تمامی تماسها همراه با جزئیات هر تماس را دریافت میکند. در این قسمت نمونه کد ارسال شده را همراه با توضیحات هر کدام از مقادیر و مشخصهها را ببینید.
Endpoint
POST /api/Customize/CustomerCallSearch
نمونه Request ارسال شده همراه با توضیح پارامترها
{
"fromDate": "2025-10-01",
"toDate": "2026-01-12",
"type": "IVR",
"directionType": "Incoming",
"from": "+98918****453",
"to": "+98993****468",
"extention": "+982128****60",
"disposition": "Answered",
"id": "89***27a-a**e-4**f-beb9-072****95c0a",
"limit": 50,
"pagination": 1
}
نکته: در صورتی که نمیخواهید پارامتری را ارسال کنید، کل آن پارامتر باید از ریکوست برداشته شود. مثلا اگر میخواهید فقط فیلتر تاریخ داشته باشید، نمونه ریکوئست صحیح به صورت زیر خواهد بود:
{
"fromDate": "2026-01-01",
"toDate": "2026-01-26"
}
Response
در صورت موفقبودن درخواست، API لیستی از تماسها را مطابق با فیلترهای ارسالشده برمیگرداند . هر سطر از خروجی
نمایانگر یک تماس به همراه جزئیات آن است . نمونه Response موفق برای دو تماس به صورت زیر است:
{
"data": [
{
"id": "b3efbc58-1e09-4bee-89b6-dff0c2da30be",
"fromNumber": "+98919*****11",
"toNumber": "+98912*****48",
"startTime": "2026-01-25T17:51:06",
"endTime": "2026-01-25T17:51:31",
"duration": "00:00:07",
"extension": "+982128423015",
"recordingId": null,
"type": "IVR",
"reportDispositionType": "NoAnswered",
"callSource": "Line",
"direction": "Incoming",
"waitingTime": "00:00:19",
"totalCallTime": "00:00:25",
"involvedServices": [
"IVR"
]
},
{
"id": "81b608ce-d906-416c-932a-9a484c5fc8ba",
"fromNumber": "+98919*****11",
"toNumber": "+9821284*****",
"startTime": "2026-01-25T17:41:03",
"endTime": "2026-01-25T17:41:08",
"duration": "00:00:05",
"extension": "+982128423015",
"recordingId": null,
"type": "IVR",
"reportDispositionType": "Answered",
"callSource": "Line",
"direction": "Incoming",
"waitingTime": "00:00:00",
"totalCallTime": "00:00:05",
"involvedServices": [
"IVR"
]
}
],
"totalCount": 2,
"pageNumber": 1,
"pageSize": 50
}
اطلاعات دریافتی در API تماس خروجی
این API برای برقراری تماس خروجی از طریق سیستم دفترشما استفاده میشود. پس از فراخوانی، تماس از خط مشخصشده
برقرار میشود و نتیجه تماس در سیستم ثبت میگردد.
Endpoint
POST api/Customize/OutgoingCall
نمونه Request ارسال شده برای تماس خروجی همراه با توضیحات پارامترها
{
"from_number": "+98918****453",
"to_number": "+98993****468",
"caller_extension": "+982128****60"
}
نکته: برای برقراری تماس خروجی از طریق API، باید هر 3 پارامتر به درستی ارسال شوند.
در صورت موفقبودن درخواست، API با کد وضعیت 200 پاسخ میدهد.
این پاسخ بدون بدنه (Empty Response Body) است و تنها نشانگر این است که درخواست برقراری تماس خروجی با موفقیت ثبت شده است.
توجه کنید که عدم وجود بدنه در Response به معنی خطا نیست.
جزئیات Response
HTTP Status Code: 200 OK
Response Body: ندارد
Response Headers: شامل اطلاعات استاندارد سرور
نکات مهم
- این API فقط ثبت درخواست تماس خروجی را تأیید میکند.
- برقراری تماس بهصورت Asynchronous انجام میشود .
- نتیجه نهایی تماس(پاسخ دادهشده، بیپاسخ، مسدود و …) در لحظه قابل دریافت نیست.
- برای مشاهده نتیجه تماس، باید از API گزارش تماس استفاده شود.
رفتار در صورت بروز خطا
در صورت بروز خطا، پاسخ شامل بدنه JSON با کد وضعیت مناسب و پیام خطا خواهد بود. جزئیات خطاها در ادامه توضیح داده میشود.
توضیح تکمیلی درباره عملکرد تماس خروجی با API:
در این حالت هم، مشابه برقراری تماس خروجی از طریق پرتال، سیستم از شماره caller_extension با شماره from_number تماس میگیرد، پس از Answered ، اینبار با شماره to_number تماس میگیرد و پس از Answered ، در نهایت سیستم from_number را به
to_number وصل میکند تا مکالمه آغاز شود.
خطاها و کدهای پاسخ
در صورت بروز خطا در هر درخواست، API یکی از کدهای زیر را برمیگرداند:
نکات تکمیلی
- توصیه میشود برای هر سرویس یا نرمافزار، یک توکن مجزا ایجاد کنید.
- در نسخههای آینده، قابلیتهای پیشرفتهتری مانند کنترل سناریوی تماس از طریق API اضافه خواهد.
آموزش تست API با استفاده از Swagger
برای تست API از طریق Swagger، مراحل زیر را انجام دهید:
- در ابتدای صفحه Swagger ، روی آیکون قفل (Authorize) کلیک کنید و توکن API را وارد نمایید.
- پس از ثبت موفق توکن، به Endpoint موردنظر مراجعه کرده و روی دکمه Try it out کلیک کنید.
- مقادیر ورودی موردنیاز را مطابق با مستندات API وارد کنید و Execute کنید.
- درخواست را اجرا کنید و پاسخ دریافتی را بررسی کنید .
نکته مهم: شماره خط (Extension) یا اطلاعاتی که در ورودی ارسال میکنید، باید متعلق به همان پنل کاربری باشد که توکن API از آن ایجاد شده است. در غیر این صورت، درخواست با خطا مواجه خواهد شد.
