احراز هویت و امنیت
راهنمای استفاده از کلید دسترسی اختصاصی و اعتبارسنجی درخواستها در پلتفرم پشتیار
تمامی درخواستهای ارسالی به وبسرویسهای پشتیار (https://api.poshtyar.com) از طریق کلید دسترسی اختصاصی (X-API-KEY) اعتبارسنجی میشوند.
دریافت کلید اختصاصی (API Key)
برای دریافت کلید دسترسی اختصاصی حساب کاربری خود:
- وارد پنل کاربری پشتیار (app.poshtyar.com) شوید.
- از منوی اصلی وارد بخش تماس خروجی > وبسرویس و API یا بخش پروفایل کاربری شوید.
- در کارت کلید اختصاصی وبسرویس (Developer API Key)، کلید اختصاصی شما با پیشوند
poshtyar_live_نمایش داده میشود. - در صورت نیاز به ابطال کلید قبلی و ساخت کلید جدید، میتوانید از دکمه تغییر کلید استفاده فرمایید.
نکته امنیتی
کلید API دارای اختیارات کامل جهت برقراری تماس و کسر اعتبار حساب است. هرگز کلید را در کدهای عمومی سمت کاربر (کلاینت) قرار ندهید و همواره آن را در متغیرهای محیطی امن سرور (.env) ذخیره کنید.
ساختار هدرهای احراز هویت در HTTP
درخواستهای ارسالی به وبسرویس باید شامل هدر X-API-KEY باشند:
POST /api/v1/external/calls/originate HTTP/1.1
Host: api.poshtyar.com
X-API-KEY: poshtyar_live_YOUR_API_KEY_HERE
Content-Type: application/jsonپیشنیازهای دسترسی به API تماس خروجی
برای موفقیتآمیز بودن فراخوانی وبسرویس، شرایط زیر مورد نیاز است:
- فعال بودن دسترسی وبسرویس: دسترسی
has_outbound_api_accessبرای حساب کاربری شما فعال شده باشد. - اعتبار کیف پول: موجودی نقدی یا اعتبار هدیه حساب کاربری برای برقراری مکالمه مثبت باشد.
کدهای وضعیت و خطاهای رایج (HTTP Status Codes)
| کد وضعیت | پیام خطا / وضعیت | علت و راهکار |
|---|---|---|
200 OK | {"status": "success", ...} | درخواست معتبر بوده و تماس در صف برقراری قرار گرفت. |
400 Bad Request | {"error": "شماره تماس و اپراتور الزامی است"} | فیلدهای الزامی نظیر شماره تماس یا شناسه اپراتور ارسال نشدهاند. |
401 Unauthorized | {"error": "کلید API نامعتبر است"} | هدر X-API-KEY ارسال نشده یا مقدار کلید منقضی/اشتباه است. |
403 Forbidden | {"error": "دسترسی به وبسرویس تماس خروجی..."} | دسترسی تماس خروجی برای حساب کاربری شما فعال نیست. |
500 Internal Error | {"error": "اعتبار حساب کافی نیست"} | موجودی کیف پول کاربر برای برقراری تماس ناکافی است. |