مستندات API قیمت‌گذاری

نسخه 1.0
آدرس API

GET https://psend.ir/api/getprice.aspx
پارامترهای ورودی
پارامتر ضروری نوع توضیح
key بله string کلید API اختصاصی هر فروشگاه
city بله number CityCode پستی
weight بله number وزن مرسوله به گرم
size بله number شناسه سایز (1 تا 11)
service بله number شناسه سرویس پستی
نمونه درخواست

GET https://psend.ir/api/getprice.aspx?key=123abc456xyz&city=19338&weight=500&size=3&service=2
پاسخ موفق

{
  "status": "success",
  "price": 528500,
  "groupID": 4,
  "weightID": 2,
  "sizeID": 3,
  "serviceID": 2
}
پاسخ خطا

{
  "status": "error",
  "code": "INVALID_KEY",
  "message": "کلید API نامعتبر است"
}
نمونه خطاهای امنیتی و محدودیت درخواست
خطای محدودیت دامنه (Domain Restriction)

{
  "status": "error",
  "code": "UNAUTHORIZED_DOMAIN",
  "message": "درخواست از دامین مجاز ارسال نشده است"
}
خطای بیش از حد مجاز در هر ثانیه

{
  "status": "error",
  "code": "RATE_LIMIT_SECOND",
  "message": "تعداد درخواست‌های این ثانیه بیش از حد مجاز است"
}
خطای حد مجاز روزانه

{
  "status": "error",
  "code": "RATE_LIMIT_DAILY",
  "message": "تعداد درخواست‌های امروز به حد مجاز رسیده است"
}
قوانین امنیتی API

برای جلوگیری از سوءاستفاده و محافظت از کلید API، این سرویس شامل دو مکانیزم امنیتی اصلی است:

1) محدودیت دامنه (Domain Restriction)

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

درخواست‌هایی که از دامنه‌های دیگر ارسال شوند توسط سیستم رد می‌شوند.

2) محدودیت نرخ درخواست‌ها (Rate Limit)

در صورت عبور از سقف مجاز، API با خطای محدودیت نرخ پاسخ خواهد داد.

کدهای خطا و تشریح آن‌ها
کد خطا شدت توضیح
INVALID_INPUT Medium یکی از پارامترهای ورودی کامل، صحیح یا قابل پردازش نیست.
موارد بررسی:
– کلید API وارد شده باشد
– وزن و سایز مقدار معتبر داشته باشند
– CityCode صحیح وارد شده باشد
INVALID_KEY High کلید API معتبر نیست یا دسترسی فعال ندارد.
موارد بررسی:
– مقدار key درست ارسال شده باشد
– اکانت فروشگاه فعال باشد
– کلید به‌درستی Copy شده باشد و کاراکتر اضافه نداشته باشد
CITY_NOT_FOUND Medium شناسه شهر قابل شناسایی نیست یا در سامانه ثبت نشده است.
موارد بررسی:
– CityCode معتبر باشد
– مقدار فقط عدد باشد (بدون فاصله یا متن اضافه)
WEIGHT_RANGE_NOT_FOUND Medium هیچ بازه قابل پردازشی برای وزن ارسال شده پیدا نشد.
موارد بررسی:
– وزن صفر یا منفی نباشد
– وزن از محدوده مجاز بیشتر نباشد
PRICE_NOT_FOUND High قیمت نهایی برای این ترکیب قابل محاسبه نیست.
موارد بررسی:
– سایز صحیح ارسال شده باشد
– شناسه سرویس درست باشد
– وزن در بازه‌های قابل محاسبه قرار گیرد
SERVER_ERROR Critical درخواست به دلیل خطای پردازش پاسخ داده نشده است.
موارد بررسی:
– درخواست را با مقادیر ساده‌تر تست کنید
– پارامترها را استاندارد ارسال کنید
– در صورت تکرار خطا از طریق پشتیبانی پیگیری کنید
UNAUTHORIZED_DOMAIN High درخواست از دامنه‌ای ارسال شده که در تنظیمات فروشگاه ثبت نشده است.
موارد بررسی:
– آدرس سایت در تنظیمات درست ثبت شده باشد
– درخواست از همان دامنه (HTTPS) ارسال شود
– قالب فروشگاه از Cross Domain یا Proxy استفاده نکند
RATE_LIMIT_SECOND High تعداد درخواست‌ها در یک ثانیه بیش از حد مجاز است.
موارد بررسی:
– ارسال درخواست‌ها با فاصله مناسب
– عدم استفاده از حلقه‌های سریع یا ربات
RATE_LIMIT_DAILY High تعداد کل درخواست‌های امروز به سقف مجاز رسیده است.
موارد بررسی:
– کاهش تعداد فراخوانی API
– مدیریت درخواست‌های فروشگاه
تست زنده API