احراز هویت و سقف‌های API نماینده
توکن‌های Bearer، دامنه‌ها، فهرست مجاز IP، سقف نرخ، کدهای خطا، کلیدهای idempotency و صفحه‌بندی API نماینده فروش OneProvider، همراه با نمونه‌کد.
توکن‌های Bearer، دسترسی‌ها، فهرست مجاز IP، محدودیت نرخ، کدهای خطا، Idempotency و صفحه‌بندی در API نماینده فروش.
همهٔ مدل‌ها، قابلیت‌ها و قیمت‌ها فهرست مستندات برای عامل‌های هوش مصنوعی:https://oneprovider.dev/docs/llms.txt توکن‌ها
توکن به شکل rsk_ و بعد از آن 40 نویسه است. آن را در حساب کاربری بسازید (تب نماینده فروش، «API و تنظیمات»)؛ مقدار فقط یک بار نمایش داده می‌شود و ما فقط هش و 4 نویسهٔ آخر را نگه می‌داریم. تا 10 توکن فعال می‌توانید داشته باشید و هر کدام را هر زمان ابطال کنید. هنگام ساخت می‌توان برای توکن مدت عمر تعیین کرد (1 تا 365 روز): پس از آن توکن 401 token_expired می‌دهد و expires_at در GET /me زمان آن را می‌گوید (null: بدون انقضا).
httpAuthorization: Bearer rsk_...دسترسی‌ها
هر توکن مجموعه‌ای از دسترسی‌ها دارد. دسترسی‌ها مستقل‌اند: keys به معنی read نیست. GET /me با هر توکن معتبری کار می‌کند. بدون دسترسی لازم پاسخ 403 forbidden_scope است.
| Scope | چه چیزی را باز می‌کند |
|---|---|
read | خواندن: موجودی و تراکنش‌ها، قیمت‌ها، مدل‌ها، مشتریان، کلیدها و مصرف آن‌ها، سفارش‌ها، بسته‌ها، آمار، تنظیمات فروشگاه GET /settings، گزارش اقدامات GET /audit (هر GET به‌جز کدها، وب‌هوک‌ها، ربات‌ها، روش‌های پرداخت و وضعیت پرداخت شارژ). |
keys | نوشتن: مشتریان (از جمله مسدودسازی)، صدور، ویرایش، توقف، شارژ، صدور مجدد (rotate) و حذف کلیدها، POST /orders، تنظیمات فروشگاه PATCH /settings (ظاهر کلیدهای صادرشده را تعیین می‌کنند). |
codes | دسته‌های کد و خود کدها (خواندن، ساخت، ابطال، فعال‌سازی). کدها محرمانه‌اند، برای همین دسترسی جداگانه دارند. |
plans | ساخت، ویرایش و حذف بسته‌ها (خواندن بسته‌ها به read نیاز دارد). |
billing | شارژ موجودی نماینده فروش: POST /balance/topups و وضعیت پرداخت. |
webhooks | مدیریت وب‌هوک‌ها، ارسال آزمایشی، خواندن گزارش ارسال‌ها. |
support | برای متدهای پشتیبانیِ آینده رزرو شده است. |
bot | خواندن وضعیت ربات‌ها و روش‌های پرداخت: GET /bot و GET /payment-providers (در پاسخ‌ها توکن نیست). ربات‌ها فقط در حساب کاربری وصل می‌شوند. |
دسترسی هر متد در مرجع آمده است.
فهرست مجاز IP
می‌توان توکن را به فهرستی از آدرس‌های IPv4/IPv6 یا بازه‌های CIDR (تا 20) محدود کرد. درخواست از آدرس دیگر 403 ip_not_allowed می‌گیرد. فهرست هنگام ساخت توکن تعیین می‌شود.
محدودیت نرخ
حداکثر 20 درخواست در ثانیه برای هر توکن و 100 در ثانیه برای هر نشانی IP مبدأ. در صورت عبور: 429 rate_limited و هدر Retry-After. همان تعداد ثانیه صبر کنید و دوباره تلاش کنید.
خطاها
هر خطا ساختار یکسانی دارد. همان شناسه در هدر پاسخ X-Request-Id هم برمی‌گردد: آن را به پشتیبانی بگویید.
{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}منطق را بر error.code بگذارید، نه بر متن پیام.
| HTTP | code | معنی |
|---|---|---|
| 400 | invalid | یک فیلد وجود ندارد یا خارج از محدوده است. |
| 400 | bad_request | درخواست قابل پردازش نبود. |
| 400 | idempotency_key_required | هدر Idempotency-Key در متدی که پول مصرف می‌کند وجود ندارد. |
| 400 | invalid_url | URL وب‌هوک در اعتبارسنجی رد شد (فقط https، بدون آدرس IP مستقیم و شبکه‌های خصوصی). |
| 400 | limit_below_spent | سقف جدید کلید کمتر از مبلغی است که کلید قبلاً مصرف کرده است. |
| 400 | currency_required | POST /balance/topups: این درگاه چند ارز می‌پذیرد، currency را بفرستید (ارزهای مجاز در topup_providers است). |
| 400 | method_unavailable | POST /balance/topups: چنین درگاهی در topup_providers نیست (bad_currency، bad_email و email_required دربارهٔ ارز و ایمیل همین‌طور پاسخ می‌دهند). |
| 401 | unauthorized | توکن وجود ندارد، ناشناخته است یا ابطال شده است. |
| 401 | token_expired | توکن منقضی شده است (expires_at در GET /me): توکن جدید بسازید. |
| 403 | forbidden_scope | توکن دسترسی لازم را ندارد. |
| 403 | ip_not_allowed | IP درخواست در فهرست مجاز توکن نیست. |
| 403 | reseller_disabled | نماینده فروش دسترسی خود را از دست داده است؛ همهٔ توکن‌ها همین پاسخ را می‌دهند. |
| 403 | banned | حساب مسدود است. |
| 404 | not_found | شیء وجود ندارد یا به نمایندهٔ دیگری تعلق دارد. |
| 404 | key_not_found | کلید وجود ندارد. |
| 409 | insufficient_balance | مبلغ در «قابل استفاده» (available_usd) جا نمی‌شود؛ به قاعدهٔ پول نگاه کنید. |
| 409 | idempotency_key_reused | همین Idempotency-Key قبلاً با بدنهٔ دیگری استفاده شده است: یک Idempotency-Key جدید بگیرید. |
| 409 | fund_first | ابتدا موجودی نماینده فروش را شارژ کنید. |
| 409 | not_activated | حساب نماینده فروش هنوز فعال نشده است. |
| 409 | name_taken | کلیدی با این نام از قبل وجود دارد. |
| 409 | key_limit | به حداکثر تعداد کلیدها رسیده‌اید. |
| 409 | plan_limit | به حداکثر تعداد بسته‌ها (20) رسیده‌اید. |
| 409 | customer_limit | به حداکثر تعداد مشتریان (10,000) رسیده‌اید. |
| 409 | plan_in_use | تا وقتی یک فاکتور پرداخت‌نشدهٔ تازه یا خرید پرداخت‌شدهٔ تحویل‌نشدهٔ ربات از بسته استفاده می‌کند، نمی‌توان آن را حذف کرد، گران‌تر کرد یا ارز آن را عوض کرد. |
| 409 | key_exhausted | صدور مجدد (rotate): کلید چیزی برای انتقال ندارد، باقی‌مانده 0 است. |
| 409 | key_expired | صدور مجدد (rotate): کلید منقضی شده است، ابتدا آن را تمدید کنید. |
| 409 | action_failed | اقدام روی کلید به دلیل دیگری ناموفق بود؛ دوباره تلاش کنید یا کلید را بررسی کنید. |
| 409 | code_used | کد قبلاً فعال شده است. |
| 409 | code_revoked | کد ابطال شده است. |
| 409 | code_busy | کد در حال پردازش است یا اکنون قابل فعال‌سازی نیست. |
| 409 | external_order_id_conflict | external_order_id قبلاً با پارامترهای دیگری استفاده شده است. |
| 409 | customer_exists | مشتری‌ای با این external_id از قبل وجود دارد. |
| 409 | customer_blocked | مشتری مسدود است: کلید، سفارش و فعال‌سازی کد برای او رد می‌شود. |
| 409 | token_limit | به حداکثر تعداد توکن‌های فعال (10) رسیده‌اید. |
| 409 | webhook_limit | به حداکثر تعداد وب‌هوک‌ها (5) رسیده‌اید. |
| 429 | rate_limited | بیش از 20 درخواست در ثانیه برای هر توکن (یا 100 در ثانیه برای هر نشانی IP)؛ به اندازهٔ Retry-After ثانیه صبر کنید. |
| 429 | too_many_invoices | POST /balance/topups: فاکتور پرداخت‌نشدهٔ پشت‌سرهم زیاد است؛ فاکتورهای باز را بپردازید یا یک دقیقه بعد دوباره تلاش کنید. |
| 501 | sandbox_not_implemented | محیط آزمایشی (rsk_test_...) هنوز پیاده‌سازی نشده است. |
| 503 | provider_unavailable | یک درگاه پرداخت یا ارائه‌دهندهٔ مدل موقتاً در دسترس نیست: بعداً دوباره تلاش کنید. |
Idempotency
متدهایی که پول مصرف می‌کنند هدر Idempotency-Key را لازم دارند (1 تا 128 نویسهٔ قابل چاپ)؛ بدون آن (یا با مقدار نامناسب) پاسخ 400 idempotency_key_required است. در مرجع علامت‌گذاری شده‌اند. تکرار درخواست با همان Idempotency-Key و همان بدنه (در محدودهٔ هر نماینده فروش) هرگز دو بار پول مصرف نمی‌کند و همان شیء را برمی‌گرداند، از جمله رازِ کلیدی که آن فراخوانی ساخته است: پاسخی که در راه گم شده با تکرار فراخوانی بازیابی می‌شود. همان Idempotency-Key با بدنهٔ دیگر 409 idempotency_key_reused است. برای هر پرداخت یا سفارش جدید یک Idempotency-Key جدید بگیرید؛ در POST /orders هویت سفارش external_order_id است. هدر در PATCH /keys/{id} (extend_days/extend_hours تکراری یک بار تمدید می‌کند)، POST /plans و POST /webhooks اختیاری است (و اگر فرستاده شود رعایت می‌شود): تکرار همان شیء را برمی‌گرداند؛ رازِ وب‌هوک دوباره نمایش داده نمی‌شود.
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'کلید Idempotency-Key را همراه سابقهٔ سفارش خودتان نگه دارید تا پس از خطای شبکه دقیقاً همان درخواست را دوباره بفرستید.
صفحه‌بندی
متدهای فهرست ?limit=1..100 (پیش‌فرض 50) و &cursor= را می‌پذیرند. پاسخ {"items": [...], "next": "<cursor>"} است؛ در صفحهٔ آخر next برابر null است. cursor مبهم (opaque) است: همان‌طور که هست پس بفرستید.
curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"محیط آزمایشی
توکن‌های آزمایشی rsk_test_... به‌زودی می‌آیند. فعلاً چنین توکنی 501 sandbox_not_implemented می‌گیرد.