مرجع API عمومی
API سمت سرور با کلید محرمانه: اطلاعات پروژه، گزارش مصرف، وضعیت حساب و موجودی و مدیریت کامل وب‌هوک‌ها.
در این صفحه
نشانی و احراز هویت
- نشانی پایه
https://api.namayek.com/v1- احراز هویت
- فقط کلید محرمانه در سرآیند
X-Namayek-KeyیاAuthorization: Bearer - پروژه
- همیشه پروژه همان کلید؛ از ورودی خوانده نمی‌شود
- CORS
- ندارد؛ این API فقط برای سرور است
- هزینه
- رایگان (فقط محدودیت نرخ)
| روش | مسیر | دسترسی | کار |
|---|---|---|---|
| GET | /v1/project | هر دسترسی | شناسه، نام، slug، سقف‌ها و وضعیت پروژه کلید. |
| GET | /v1/usage | هر دسترسی | سری مصرف ساعتی یا روزانه پروژه. |
| GET | /v1/billing/summary | هر دسترسی | موجودی، بدهی، وضعیت توقف، پایان مهلت و هزینه ماه حساب صاحب کلید. |
| GET | /v1/webhooks | webhooks:manage | فهرست وب‌هوک‌ها و سقف تعداد. |
| POST | /v1/webhooks | webhooks:manage | ساخت وب‌هوک؛ راز فقط همین یک بار برمی‌گردد. |
| GET | /v1/webhooks/{endpointId} | webhooks:manage | جزئیات و نمونه کد تایید. |
| PATCH | /v1/webhooks/{endpointId} | webhooks:manage | تغییر نشانی، توضیح، رویدادها یا وضعیت. |
| DELETE | /v1/webhooks/{endpointId} | webhooks:manage | حذف وب‌هوک. |
| POST | /v1/webhooks/{endpointId}/rotate-secret | webhooks:manage | راز تازه با دوره هم‌پوشانی ۰ تا ۷۲ ساعت. |
| POST | /v1/webhooks/{endpointId}/test | webhooks:manage | فرستادن رویداد webhook.test. |
| GET | /v1/webhooks/{endpointId}/deliveries | webhooks:manage | فهرست تحویل‌ها با صفحه‌بندی cursor. |
| POST | /v1/webhooks/{endpointId}/deliveries/{deliveryId}/resend | webhooks:manage | ارسال دوباره یک تحویل. |
محدودیت نرخ
هر کلید در هر گروه مسیر سقف درخواست در دقیقه دارد (پیش‌فرض ۶۰)؛ مقدار را مدیر سامانه تنظیم می‌کند و در سرآیند X-RateLimit-Limit برمی‌گردد. پس از آن پاسخ ۴۲۹ با Retry-After می‌گیرید. سقف مسیرهای پشتیبان‌گیری جداست؛ API پشتیبان‌گیری. کارهای تغییردهنده در گزارش امنیتی حساب ثبت می‌شوند.
اطلاعات پروژه
اطلاعات پروژه‌ای که کلید به آن تعلق دارد، شامل سقف‌های هزینه و وضعیت:
GET /v1/project
curl -sS "https://api.namayek.com/v1/project" \ -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"{ "statusCode": 200, "data": { "id": "6f1c2a4e-1b2c-4d5e-8f90-123456789abc", "name": "فروشگاه من", "slug": "default", "caps": { "dailyToman": null, "monthlyToman": "2000000", "action": "block", "cappedDaily": false, "cappedMonthly": false }, "state": "active" }, "timestamp": "2026-10-23T10:00:00.000Z"}گزارش مصرف
| پارامتر | نوع | لزوم | پیش‌فرض | توضیح |
|---|---|---|---|---|
from | YYYY-MM-DD | لازم | — | روز شروع به تقویم میلادی و ساعت تهران. |
to | YYYY-MM-DD | لازم | — | روز پایان (شامل)؛ ساعتی تا ۷ روز و روزانه تا ۴۰۰ روز. |
granularity | hour | day | لازم | — | دانه‌بندی سری. |
services | csv | اختیاری | — | تا ۱۶ سرویس، مثلا maps.tiles,maps.search. |
keyId | uuid | اختیاری | — | فقط مصرف یک کلید از همین پروژه. |
GET /v1/usage
curl -sS "https://api.namayek.com/v1/usage?from=2026-10-01&to=2026-10-23&granularity=day&services=maps.tiles,maps.search" \ -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"{ "statusCode": 200, "data": { "granularity": "day", "from": "2026-10-01", "to": "2026-10-23", "points": [ { "t": "2026-10-21T20:30:00.000Z", "service": "maps.tiles", "units": "184220" }, { "t": "2026-10-21T20:30:00.000Z", "service": "maps.search", "units": "1290" } ], "totals": [ { "service": "maps.tiles", "units": "3911840" }, { "service": "maps.search", "units": "25110" } ], "freshness": { "foldedUntil": "2026-10-23T09:58:00.000Z" } }, "timestamp": "2026-10-23T10:00:00.000Z"}| فیلد | نوع / مقدار | توضیح |
|---|---|---|
points[] | { t, service, units } | t زمان شروع بازه به ISO؛ units رشته عددی (ممکن است از 2^53 بزرگ‌تر شود). |
totals[] | { service, units } | جمع هر سرویس در بازه. |
freshness.foldedUntil | ISO 8601 | تا این دقیقه کامل شمرده شده است. |
وضعیت حساب و موجودی
وضعیت حساب صاحب پروژه کلید: موجودی، بدهی، توقف و هزینه ماه. سرور شما پیش از کار سنگین یا در زمان‌بندی خودش می‌تواند ببیند حساب در مهلت تسویه است یا متوقف شده؛ حساب متوقف هم همین پاسخ را می‌گیرد. داده تا ۱۵ ثانیه کش می‌شود و با هر کسر هزینه، شارژ یا تسویه تازه می‌شود. برای خبر لحظه‌ای رویدادهای wallet.charged، billing.outstanding_created، billing.suspended و billing.statement_ready را در وب‌هوک‌ها بگیرید.
GET /v1/billing/summary
curl -sS "https://api.namayek.com/v1/billing/summary" \ -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"{ "statusCode": 200, "data": { "currency": "TOMAN", "state": "grace", "suspensionReason": null, "balanceToman": "150000", "availableToman": "120000", "outstandingToman": "12500", "outstandingSince": "2026-10-23T09:00:00.000Z", "graceEndsAt": "2026-10-24T09:00:00.000Z", "suspendedAt": null, "lowBalance": { "thresholdToman": "20000", "isLow": false, "daysLeft": 9.25 }, "month": { "period": "140508", "billedToman": "84000", "unbilledEstimateToman": "1200", "projectedToman": "310000" } }, "timestamp": "2026-10-23T10:00:00.000Z"}| فیلد | نوع / مقدار | توضیح |
|---|---|---|
currency | "TOMAN" | واحد همه مبلغ‌ها؛ مبلغ‌ها رشته عددی‌اند. |
state | active | grace | suspended | فعال، در مهلت تسویه بدهی، یا متوقف (درخواست‌های مصرفی کلیدها رد می‌شود ولی همین API پاسخ می‌دهد). |
suspensionReason | balance | admin | null | دلیل توقف: بدهی تسویه‌نشده یا تصمیم پشتیبانی. |
balanceToman | string | موجودی کل کیف پول. |
availableToman | string | موجودی قابل استفاده برای هزینه مصرف. |
outstandingToman | string | بدهی تسویه‌نشده؛ شارژ کیف پول اول آن را تسویه می‌کند. |
graceEndsAt | ISO 8601 | null | اگر بدهی تا این زمان تسویه نشود سرویس‌ها متوقف می‌شوند. |
outstandingSince / suspendedAt | ISO 8601 | null | زمان ثبت بدهی و زمان توقف. |
lowBalance | { thresholdToman, isLow, daysLeft } | آستانه هشدار، کم بودن موجودی و روزهای باقی با مصرف هفت روز اخیر (null یعنی مصرفی نبوده). |
month | { period, billedToman, unbilledEstimateToman, projectedToman } | ماه شمسی جاری (مثلا 140508): صورت‌حساب‌شده، برآورد هنوز صورت‌حساب‌نشده و پیش‌بینی کل ماه. |
مدیریت وب‌هوک‌ها
با دسترسی webhooks:manage همه کارهای پنل را با API انجام دهید. راز ساخته‌شده فقط در پاسخ ساخت یا چرخش برمی‌گردد و API هیچ راهی برای دیدن دوباره آن ندارد. قالب رویدادها و تایید امضا در وب‌هوک‌ها.
| پارامتر | نوع | لزوم | پیش‌فرض | توضیح |
|---|---|---|---|---|
url | string | لازم | — | نشانی https عمومی تا ۲۰۴۸ نویسه؛ نشانی شبکه داخلی رد می‌شود. |
description | string | اختیاری | — | توضیح تا ۲۰۰ نویسه. |
events | string[] | لازم | — | ۱ تا ۶۴ رویداد بی تکرار از جدول رویدادها. |
curl -sS -X POST "https://api.namayek.com/v1/webhooks" \ -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/hooks/namayek","events":["billing.low_balance","api_key.revoked"]}'قالب پاسخ
پاسخ موفق در پاکت { statusCode, data, timestamp } است و خطا این شکل را دارد:
{ "success": false, "statusCode": 403, "code": "ORIGIN_NOT_ALLOWED", "message": "این دامنه برای کلید مجاز نیست"}- برنامه شما باید روی
codeتصمیم بگیرد، نه روی متن پیام؛ پیام فارسی برای نمایش است. - فهرست کدها در خطاها و محدودیت‌ها.
آخرین به‌روزرسانی: