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

تمام مثال‌های این مستند با فراخوانی واقعی endpointها روی محیط production تست شده‌اند و خروجی‌ها دقیقاً همان چیزی است که سرور برمی‌گرداند.

آدرس پایه​

https://open.nestapi.ir/{version}/{api_name}

متد و فرمت درخواست​

همهٔ endpointها بجز چند استثنا با متود GET در دسترس هستند و ورودی ها به صورت Query String ارسال میشود.

GET https://open.nestapi.ir/apis-1/bmi?age=30&weight=70&height=175

احراز هویت​

در حال حاضر برای استفاده از API نیازی به توکن یا کلید دسترسی نیست؛ endpointها عمومی و بدون احراز هویت در دسترس‌اند.

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

https://open.nestapi.ir/apis-1/bmi?age=30&weight=70&height=175

پاسخ:

{
  "success": true,
  "data": {
    "bmi": 22.86,
    "status": "وزن نرمال (Normal)",
    "risk": "🟢 وضعیت بدنی سالم و نرمال",
    "input": { "age": 30, "weight": 70, "height": 175 }
  },
  "source": {
    "name": "NestAPI",
    "version": "1.0.1",
    "developers": "t.me/Nest_API t.me/devh3n"
  }
}

نمونه کد​

composer require nestapi/nestapi

<?php

use NestApi\NestApi;

$api = new NestApi();
$result = $api->bmi(age: 30, weight: 70, height: 175);

echo $result->get('status');

pip install nestapi-py

from nestapi import NestApi

with NestApi() as api:
    result = api.bmi(age=30, weight=70, height=175)

    print(result.get("status"))

npm install @devh3n/nestapi

import { NestApi } from "@devh3n/nestapi";

const api = new NestApi();
const result = await api.bmi({ age: 30, weight: 70, height: 175 });

console.log(result.get("status"));

curl "https://open.nestapi.ir/apis-1/bmi?age=30&weight=70&height=175"

فرمت پاسخ​

همهٔ پاسخ‌ها — چه موفق، چه خطا — یک ساختار ثابت دارند. این ساختار در همهٔ سرویس‌ها یکسان است.

پاسخ موفق​

{
  "success": true,
  "data": { "bmi": 22.86 },
  "source": {
    "name": "NestAPI",
    "version": "1.0.1",
    "developers": "t.me/Nest_API t.me/devh3n"
  }
}

فیلد data​

بسته به سرویس، data می‌تواند هر یک از این‌ها باشد:

• آبجکت: { "ip": "...", "location": { ... } }
• آرایه: { "data": [ { ... }, { ... } ] }
• رشته: { "data": { "ascii": " _ \n | | \n" } }
• null: وقتی سرویس چیزی برای برگرداندن ندارد

فیلد meta (اختیاری)​

{
  "success": true,
  "data": [ { "name": "Samsung Galaxy S26 Ultra", "url": "..." } ],
  "meta": {
    "query": { "term": "galaxy" },
    "pagination": { "count": 20 }
  },
  "source": { "name": "NestAPI", "version": "1.0.1", "developers": "..." }
}

meta فقط وقتی در پاسخ است که سرویس آن را فرستاده باشد؛ نبودنش خطا نیست.

فیلد source​

این فیلد روی همهٔ پاسخ‌ها — موفق و خطا — یکسان و بدون استثنا ظاهر می‌شود.

پاسخ خطا​

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Route not found: GET /apis-1/nope"
  },
  "source": { "name": "NestAPI", "version": "1.0.1", "developers": "..." }
}

پارامتر نامعتبر یا ناقص​

دو حالت متفاوت وجود دارد و کد وضعیت متفاوتی دارند:

۱) پارامتر نیامده — وضعیت 400 و کد PARAM_NOT_FOUND، با آرایه‌ای از جزئیات برای هر پارامتر گمشده:

{
  "success": false,
  "error": {
    "code": "PARAM_NOT_FOUND",
    "message": "Required parameters not found: 'age', 'weight', 'height'",
    "details": [
      { "parameter": "age", "message": "'age' parameter not found", "description": "Age in years, e.g. ?age=30." },
      { "parameter": "weight", "message": "'weight' parameter not found", "description": "Weight in kilograms, e.g. ?weight=70." },
      { "parameter": "height", "message": "'height' parameter not found", "description": "Height in centimeters, e.g. ?height=175." }
    ]
  }
}

details همیشه آرایه است — حتی وقتی فقط یک پارامتر کم است. پس کلاینت با یک forEach همهٔ حالت‌ها را پوشش می‌دهد.

۲) پارامتر آمده ولی قالب یا بازهٔ آن غلط است — وضعیت 422 و کد VALIDATION_ERROR، با آبجکتی که کلیدش بخش و نام پارامتر است:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": { "query.age": "Must be less than or equal to 120" }
  }
}

کلید هر خطا با بخش مربوطه شروع می‌شود — query. یا body. — پس از همان معلوم است مشکل از کجاست. (همهٔ endpointهای عمومی فعلاً ورودی فقط از Query String می‌گیرند.)

کدهای خطا​

هدرها و CORS​

سرویس از مرورگر و جاوااسکریپت سمت کلاینت پشتیبانی می‌کند:

OPTIONS بهصورت Preflight با وضعیت 204 و بدون بدنه پاسخ داده می‌شود.

نکات امنیتی و فنی​

• از پروتکل HTTPS استفاده کنید؛ نسخهٔ HTTP به HTTPS ریدایرکت می‌شود.
• چون احراز هویت فعلاً لازم نیست، هیچ توکنی در سمت کلاینت قرار نمی‌گیرد؛ اگر سرویسی توکن اختصاصی خودش را می‌خواهد، آن را فقط سمت سرور نگه دارید.
• پاسخ‌ها و خطاها را به درستی مدیریت کنید: قبل از خواندن data، success را چک کنید.
• طول هر پارامتر رشته‌ای به ۸ کیلوبایت محدود می‌شود و آرایه‌ها حداکثر ۱۰۰ عضو می‌پذیرند.

define('API_BASE_URL', 'https://open.nestapi.ir/');

API_BASE_URL = "https://open.nestapi.ir/"

const API_BASE_URL = "https://open.nestapi.ir/";

منابع تکمیلی​

• مقدمهٔ مستندات
• سوالات متداول
• کانال اطلاع‌رسانی: @Nest_API
• ارتباط با توسعه‌دهنده: @devh3n - @aLirzix