صفحه اصلی API Hub درباره ما راهنمای Documents

مستندات رسمی

مستندات NewGateway

راهنمای کامل برای ادغام، مدیریت و مقیاس‌گذاری API‌های شما با پلتفرم NewGateway — از اولین درخواست تا استقرار در Production.

▶شروع سریع۵ دقیقه ⬡مرجع APIکامل ◈راهنماهاگام‌به‌گام ◻SDKJS · Python

شروع سریع

۵ دقیقه

ثبت‌نام

یک حساب رایگان بسازید و وارد داشبورد شوید.

رفتن به ثبت‌نام ←

ایجاد پروژه

پروژه جدید تعریف کنید و slug آن را انتخاب کنید.

افزودن Endpoint

یک endpoint با مسیر و سرور هدف پیکربندی کنید.

اولین درخواست — آزمایش سریع با cURL:

bash

curl -X GET "https://api.newgateway.ir/{projectName}/{endpointPath}" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

پاسخ موفق (200 OK):

json

{
  "status": "ok",
  "data": { ... },
  "latency_ms": 12,
  "gateway_version": "1.4.0"
}

احراز هویت

Authentication

NewGateway از دو روش احراز هویت پشتیبانی می‌کند: API Key برای درخواست‌های سرویس‌به‌سرویس و JWT Bearer Token برای کاربران لاگین‌شده.

API Keyکلید API

بعد از اشتراک در یک سرویس، یک کلید API دریافت می‌کنید. این کلید یک‌بار نمایش داده می‌شود — آن را ذخیره کنید.

bash

Authorization: Bearer ngw_live_xxxxxxxxxxxxxx

JWTتوکن JWT

با ارسال اطلاعات ورود به endpoint زیر، یک JWT کوتاه‌مدت (۱۵ دقیقه) و Refresh Token (۷ روز) دریافت کنید.

bash

POST /api/v1/auth/login
{
  "phone": "09123456789",
  "password": "••••••••"
}

⚠️ هرگز کلید API را در کد Front-end یا مخازن عمومی ذخیره نکنید. از متغیرهای محیطی سمت سرور استفاده کنید.

مرجع API

REST API v1

تمام endpoint‌ها با پیشوند /api/v1 در دسترس هستند.

پروژه‌هاProjects

GET/projectsفهرست پروژه‌های شما

POST/projectsایجاد پروژه جدید

GET/projects/{id}جزئیات یک پروژه

PATCH/projects/{id}ویرایش پروژه

DELETE/projects/{id}حذف پروژه و تمام تنظیمات آن

تنظیمات پروژه (Configs)Endpoints · Schema · Request

GET/projects/{id}/configsفهرست تمام Config Node‌ها

POST/projects/{id}/configsایجاد Endpoint، Schema یا Request

PATCH/projects/{id}/configs/{nodeId}ویرایش یک Config Node

DELETE/projects/{id}/configs/{nodeId}حذف Config Node

کاتالوگ عمومیCatalog

GET/public/catalog/servicesلیست سرویس‌های عمومی

GET/public/catalog/services/{id}جزئیات سرویس و endpoint‌ها

POST/public/catalog/services/{id}/accessدریافت رایگان API Key

POST/catalog/api-keys/{keyId}/revealنمایش مجدد کلید با تأیید OTP

گزارش ترافیکLogs

GET/projects/{id}/reportsآمار کلی درخواست‌ها

GET/projects/{id}/reports/{tariffId}گزارش یک تعرفه خاص

نمونه: ایجاد پروژه

bash

curl -X POST "https://api.newgateway.ir/api/v1/projects" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "پرداخت‌یار",
    "slug": "payadyar",
    "description": "درگاه پرداخت یکپارچه",
    "visibility": "public"
  }'

پاسخ (201 Created):

json

{
  "id": "proj_01j9x...",
  "name": "پرداخت‌یار",
  "slug": "payadyar",
  "visibility": "public",
  "created_at": "2025-09-01T08:00:00Z"
}

راهنماها

Guides

تعریف Endpointendpoints

1نوع "endpoints" را انتخاب کنید.
2مسیر خارجی (externalPath) و متد HTTP را وارد کنید.
3حالت ارسال را تعیین کنید: direct (یک سرور هدف) یا pool (چند سرور).
4برای حالت direct، آدرس IP/hostname و پورت داخلی را وارد کنید.

json

{
  "type": "endpoints",
  "data": {
    "title": "دریافت لیست محصولات",
    "externalPath": "/products",
    "method": "GET",
    "isActive": true,
    "forwardMode": "direct",
    "internalUrl": "10.0.0.5",
    "internalPort": 3001,
    "timeout": 5000
  }
}

تعریف Schemaschema

1نوع "schema" را انتخاب کنید.
2ساختار JSON را با فیلدهای مورد انتظار تعریف کنید.
3برای هر فیلد: type، required، nullable و description را مشخص کنید.
4Schema را در endpoint از طریق schemaId لینک کنید.

json

{
  "type": "schema",
  "data": {
    "product_id": {
      "type": "string",
      "required": true,
      "nullable": false,
      "description": "شناسه یکتای محصول"
    },
    "quantity": {
      "type": "integer",
      "required": true,
      "nullable": false
    },
    "note": {
      "type": "string",
      "required": false,
      "nullable": true
    }
  }
}

Request Pool — Load Balancingrequest

1چند Config Node از نوع "request" با آدرس‌های مختلف بسازید.
2در Endpoint، حالت forwardMode را روی "pool" بگذارید.
3در requestPool هر request را با وزن (loadBalanceWeight) و اولویت مشخص کنید.
4NewGateway در زمان اجرا بر اساس وزن و آپ‌تایم، درخواست‌ها را توزیع می‌کند.

json

{
  "forwardMode": "pool",
  "requestPool": [
    {
      "requestId": "req_server_a",
      "priority": 1,
      "loadBalanceWeight": 70,
      "timeout": 3000
    },
    {
      "requestId": "req_server_b",
      "priority": 2,
      "loadBalanceWeight": 30,
      "timeout": 3000
    }
  ]
}

Rate Limiting در تعرفهtariff

1در داشبورد پروژه، تعرفه (Tariff) جدید بسازید.
2مقدار requestLimit (تعداد کل) یا rateLimit (در بازه زمانی) را تنظیم کنید.
3مشتری با اشتراک در این تعرفه، API Key دریافت می‌کند.
4هنگام فراتر رفتن از حد مجاز، پاسخ 429 برگشت داده می‌شود.

json

// پاسخ هنگام بیش از حد:
HTTP 429 Too Many Requests
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "تعداد درخواست‌های مجاز تمام شد",
  "retry_after": 60
}

SDK و کتابخانه‌ها

SDK

JavaScript / TypeScript

npm install @newgateway/sdk

typescript

import { NewGateway } from '@newgateway/sdk';

const client = new NewGateway({
  apiKey: process.env.NGW_API_KEY,
});

const res = await client.request({
  project: 'payadyar',
  endpoint: '/products',
  method: 'GET',
});

Python

pip install newgateway

python

from newgateway import NewGateway

client = NewGateway(
    api_key=os.environ["NGW_API_KEY"]
)

res = client.request(
    project="payadyar",
    endpoint="/products",
    method="GET",
)

cURL

نیاز به نصب ندارد

bash

curl -X POST \
  "https://api.newgateway.ir/\
  payadyar/products" \
  -H "Authorization: \
      Bearer $NGW_API_KEY" \
  -H "Content-Type: \
      application/json"

کدهای خطا

Error Codes

تمام خطاها با ساختار یکسان برگردانده می‌شوند:

json

{
  "error": "ERROR_CODE",
  "message": "توضیح خطا به فارسی",
  "status": 400
}

کد HTTP	error	توضیح
400	BAD_REQUEST	ورودی‌های نامعتبر
401	UNAUTHORIZED	توکن منقضی یا نامعتبر
403	FORBIDDEN	دسترسی غیرمجاز به این منبع
404	NOT_FOUND	منبع درخواست‌شده یافت نشد
409	CONFLICT	تداخل با وضعیت فعلی
422	VALIDATION_ERROR	خطای اعتبارسنجی فیلدها
429	RATE_LIMIT_EXCEEDED	فراتر از محدودیت نرخ درخواست
500	INTERNAL_ERROR	خطای داخلی سرور
503	SERVICE_UNAVAILABLE	سرور هدف در دسترس نیست

سوالات متداول

FAQ

آیا پلن رایگان محدودیت دارد؟

بله. در پلن رایگان می‌توانید تا ۳ پروژه، ۱۰ endpoint و ۱۰,۰۰۰ درخواست ماهانه داشته باشید. برای نیازهای بیشتر، پلن‌های حرفه‌ای را بررسی کنید.

چطور می‌توانم پلن خود را ارتقا دهم؟

از داشبورد → تنظیمات → اشتراک، می‌توانید پلن خود را تغییر دهید. تغییر پلن فوری است و هزینه به‌صورت تفاضلی محاسبه می‌شود.

آیا API Key من قابل بازیابی است؟

خیر. به دلایل امنیتی، کلید API فقط یک‌بار در لحظه صدور نمایش داده می‌شود. برای نمایش مجدد نیاز به تأیید OTP دارید. در صورت گم شدن، می‌توانید کلید جدید صادر کنید.

آیا امکان تست سرویس قبل از پرداخت وجود دارد؟

بله. هر سرویس با تعرفه رایگان (Free Tier) قابل آزمایش است. پس از اشتراک رایگان، یک API Key با محدودیت درخواست دریافت می‌کنید.

SLA و آپ‌تایم تضمینی چقدر است؟

زیرساخت NewGateway با آپ‌تایم ۹۹.۹٪ (SLA رسمی) ارائه می‌شود. در صورت بروز اختلال، وضعیت سیستم در status.newgateway.ir قابل پیگیری است.

آیا داده‌های کاربران در ایران نگهداری می‌شود؟

بله. تمام داده‌ها روی سرورهای ایرانی ذخیره می‌شوند و هیچ داده‌ای خارج از کشور منتقل نمی‌شود.

آماده شروع هستید؟

همین حالا یک حساب رایگان بسازید و اولین API Gateway خود را راه‌اندازی کنید.

شروع رایگان تماس با پشتیبانی

درباره ما

پلتفرم NewGateway نه‌تنها زیرساختی فنی برای مدیریت و کنترل ارتباطات در محیط‌های میکروسرویسی است، بلکه با ارائه امکانات تجاری‌سازی، نظارت، امنیت و بهینه‌سازی عملکرد، به یکی از مؤلفه‌های کلیدی در توسعه اکوسیستم خدمات دیجیتال تبدیل می‌شود.

صفحه اصلی خدمات قوانین و مقررات نوشته‌ها و بلاگ

شبکه‌های اجتماعی

کلیه حقوق مادی و معنوی این سایت متعلق به شرکت NewGateWay می‌باشد.