پورتال توسعه‌دهندگان

شروع سریع

دو مسیر عمومی بدون ورود قابل خواندن‌اند؛ بقیهٔ مسیرها به یک نشست کاربر نیاز دارند. اولین درخواستتان را همین حالا می‌توانید بزنید:

curl https://api.noghtex.ir/api/stats

# → { "online": 12, "sales_last_hour": 340 }

مشخصهٔ کامل API (همهٔ مسیرها، اسکیمای ورودی/خروجی، کدهای خطا) اینجاست:

curl -s https://api.noghtex.ir/openapi.json | jq '.info.title'
# → "Noghtex Public API"

منابع کلیدی

مدل احراز هویت

نقطکس از کلید API استفاده نمی‌کند؛ احراز هویت «نشست کوکی‌محور» است و عمداً همین‌طور طراحی شده، چون همهٔ مسیرهای غیرعمومی به نام یک کاربر واقعی پول جابه‌جا می‌کنند. جریان کار برنامه‌نویسی چنین است:

1. POST /auth/otp/request با شمارهٔ موبایل کاربر؛ کد پیامک می‌شود.
2. POST /auth/login با همان شماره و کد؛ سرور دو کوکی __Host- تنظیم می‌کند و توکن CSRF را در بدنه برمی‌گرداند.
3. هر درخواست تغییردهنده باید هم کوکی‌ها را ببرد و هم توکن CSRF را در سرآیند X-CSRF-Token برگرداند.

یعنی یک عامل هوشمند می‌تواند فقط با رضایت صریح کاربرِ خودش (و خواندن کد پیامکی که برای او آمده) از API استفاده کند؛ دسترسی بدون کاربر وجود ندارد و این محدودیت، امنیتی است نه فنی.

خطاها

همهٔ پاسخ‌های خطا — حتی ۴۰۴ و ۴۰۵ — JSON هستند و سه بخش دارند: code (شناسهٔ پایدار)، message و hint (راهنمای رفع).

curl -i https://api.noghtex.ir/api/no-such-endpoint
# HTTP/1.1 404 Not Found
# {"code":"NOT_FOUND","message":"not found",
#  "hint":"See /openapi.json for the list of valid endpoints."}

نسخه‌بندی و منسوخ‌سازی API

Versioning & deprecation policy — the REST surface is major version 1. Every response carries an API-Version: 1 header, so a client can pin what it talks to from any single response, errors included.

• مسیرهای بدون نسخهٔ فعلی همان قرارداد نسخهٔ ۱ هستند و تغییر ناسازگار نخواهند داشت؛ نسخهٔ شکستهٔ بعدی زیر پیشوند /v2/... عرضه می‌شود و دست‌کم ۱۲ ماه در کنار v1 می‌ماند.
• عملیاتی که قرار است حذف شود، در مشخصهٔ OpenAPI با deprecated: true علامت می‌خورد و پاسخ‌هایش تا زمان حذف، سرآیندهای Deprecation: true و Sunset را می‌برند.
• افزودنی‌های ناسازگارنشکن (فیلد اختیاری تازه، عملیات تازه، کد خطای تازه) هر زمان ممکن است اضافه شوند؛ کلاینت باید فیلدها و کدهای ناشناخته را نادیده بگیرد.

curl -si https://api.noghtex.ir/api/stats | grep -i api-version
# API-Version: 1

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

پاسخ‌های دارای بودجهٔ نرخ، سرآیندهای استاندارد RFC را برمی‌گردانند تا یک عامل هوشمند بلافاصله و به‌صورت خودتنظیم آهنگ درخواست‌هایش را تنظیم کند:

پاسخ ردشده 429 RATE_LIMITED است با همین سرآیندها در حالت «صفر باقی‌مانده» به‌علاوهٔ Retry-After (ثانیه). بودجه‌های نمونه: تصرف ۳۰۰ در دقیقه برای هر کاربر، برداشت ۵ در ساعت برای هر کاربر، خواندن عمومی حدود ۱۲۰ در دقیقه برای هر IP، و سقف لبهٔ شبکه حدود ۶۰۰ درخواست در دقیقه برای هر IP.

curl -si https://api.noghtex.ir/api/stats | grep -i ratelimit

کلید API نداریم — عمداً

نقطکس هیچ API Key صادر نمی‌کند؛ چون همهٔ مسیرهای غیرعمومی به نام یک کاربر واقعیِ احراز هویت‌شده پول جابه‌جا می‌کنند و نشست کوکی + CSRF + بررسی مبدأ جانشین کلید است. یک ماشین با رضایت صریح کاربر از نشست واردشدهٔ او استفاده می‌کند (مدل بالا و جریان موجود در مستندات). خواندن‌های عمومی (GET /api/stats، GET /openapi.json و probe های سلامت) اصلاً اعتبارنامه نمی‌خواهند.

وضعیت سندباکس

• محیط سندباکس هنوز نداریم؛ تست را روی حساب واقعی خودتان و با مبالغ کم انجام دهید. همهٔ مسیرهای تغییردهنده با کلید Idempotency-Key خودتان idempotent هستند.
• سطح آزمایشیِ فقط‌خواندنیِ بدون پول در نقشهٔ راه است؛ خبرش اول در llms.txt و همین صفحه منتشر می‌شود.
• صفحهٔ زندهٔ بوم (WebTransport/WSS) بخشی از این REST API نیست؛ برای مشاهدهٔ زنده از خود اپ استفاده کنید.

مرتبط

مرجع مسیرها و مثال‌های curl · کنترل‌های امنیتی و سقف‌های نرخ · llms.txt · تماس با ما