معرفی

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

ویژگی‌های اصلی

• دسترسی به بیش از ۵۰ API کاربردی
• پشتیبانی از فرمت‌های JSON و XML
• احراز هویت امن با استفاده از کلیدهای API
• محدودیت نرخ درخواست منعطف
• SDK‌های رسمی برای زبان‌های محبوب برنامه‌نویسی
• مستندات جامع و به‌روز
• پشتیبانی فنی ۲۴/۷

شروع سریع

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

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

در اینجا یک نمونه درخواست ساده به API آب و هوا را مشاهده می‌کنید:

curl -X GET "https://api.potyapi.com/v1/weather?city=tehran" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

// با استفاده از fetch
const fetchWeather = async () => {
try {
  const response = await fetch('https://api.potyapi.com/v1/weather?city=tehran', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log(data);
  return data;
} catch (error) {
  console.error('Error fetching weather data:', error);
}
}

 "https://api.potyapi.com/v1/weather?city=tehran",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
  "Authorization: Bearer YOUR_API_KEY",
  "Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error: " . $err;
} else {
echo $response;
}
?>

import requests

url = "https://api.potyapi.com/v1/weather"
params = {"city": "tehran"}
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)

if response.status_code == 200:
  data = response.json()
  print(data)
else:
  print(f"Error: {response.status_code}")
  print(response.text)

پاسخ نمونه

{
"status": "success",
"data": {
  "city": "تهران",
  "country": "ایران",
  "temperature": 28,
  "feels_like": 30,
  "humidity": 45,
  "wind_speed": 12,
  "condition": "آ  "ایران",
  "temperature": 28,
  "feels_like": 30,
  "humidity": 45,
  "wind_speed": 12,
  "condition": "آفتابی",
  "icon": "sunny",
  "forecast": [
    {
      "date": "1402-07-16",
      "min_temp": 22,
      "max_temp": 29,
      "condition": "آفتابی"
    },
    {
      "date": "1402-07-17",
      "min_temp": 20,
      "max_temp": 27,
      "condition": "ابری"
    }
  ]
}
}

احراز هویت

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

کلید API

برای احراز هویت، شما باید کلید API خود را در هدر Authorization هر درخواست قرار دهید:

Authorization: Bearer YOUR_API_KEY

مدیریت کلیدهای API

شما می‌توانید کلیدهای API خود را در داشبورد کاربری مدیریت کنید:

• ایجاد کلیدهای جدید
• غیرفعال کردن کلیدهای موجود
• تنظیم محدودیت‌های دسترسی برای هر کلید
• مشاهده تاریخچه استفاده از هر کلید

محدودیت‌های نرخ

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

هدرهای محدودیت نرخ

در پاسخ به هر درخواست، هدرهای زیر برای اطلاع‌رسانی درباره وضعیت محدودیت نرخ شما ارائه می‌شوند:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1634567890

• X-RateLimit-Limit: تعداد کل درخواست‌های مجاز در بازه زمانی فعلی
• X-RateLimit-Remaining: تعداد درخواست‌های باقی‌مانده در بازه زمانی فعلی
• X-RateLimit-Reset: زمان بازنشانی محدودیت (timestamp یونیکس)

تجاوز از محدودیت

اگر از محدودیت نرخ تجاوز کنید، یک پاسخ با کد وضعیت 429 Too Many Requests دریافت خواهید کرد.

مدیریت خطاها

API‌های پوتی از کدهای وضعیت HTTP استاندارد برای نشان دادن موفقیت یا شکست یک درخواست استفاده می‌کنند. در صورت بروز خطا، یک پاسخ JSON با جزئیات خطا دریافت خواهید کرد.

کدهای وضعیت

• 200 OK: درخواست موفقیت‌آمیز بود
• 400 Bad Request: درخواست نامعتبر است
• 401 Unauthorized: احراز هویت ناموفق بود
• 403 Forbidden: شما مجوز دسترسی به منبع درخواستی را ندارید
• 404 Not Found: منبع درخواستی یافت نشد
• 429 Too Many Requests: از محدودیت نرخ تجاوز کرده‌اید
• 500 Internal Server Error: خطای داخلی سرور رخ داده است

ساختار پاسخ خطا

{
"status": "error",
"code": "invalid_parameter",
"message": "پارامتر city الزامی است",
"details": {
  "field": "city",
  "error": "missing_required_field"
}
}

پشتیبانی

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

مستندات Postman

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

همچنین می‌توانید مجموعه Postman را دانلود کرده و به راحتی API‌های ما را تست کنید: