API نماینده فروش: نحوهٔ کار

پلتفرم نمایندگی فروش چگونه کار می‌کند: موجودی نماینده فروش، رزرو، کلیدهای مشتریان، کدها، بسته‌ها و هر کاری که حساب کاربری از طریق REST API برای سایت یا ربات خودتان انجام می‌دهد.

چگونه کار می‌کند

نماینده فروش موجودی خودش را با قیمت عمده شارژ می‌کند و توکن‌ها را به‌صورت کلید و کد به مشتریانش می‌فروشد. هر کاری که در حساب کاربری (تب نماینده فروش در app.oneprovider.dev) می‌توانید انجام دهید، از طریق API هم در دسترس است؛ پس می‌توانید سایت، ربات یا صفحهٔ پرداخت خودتان را بسازید.

• موجودی نماینده فروش. موجودی USD جدا از پول شخصی شما. آن را با قیمت عمده شارژ می‌کنید؛ GET /pricing قیمت هر 1 USD و تخفیف را برمی‌گرداند.
• کلیدهای مشتریان. هر کلید یک سقف هزینهٔ USD و یک تاریخ انقضا دارد (کلیدی که از یک بسته یا دستهٔ کد ساخته شود می‌تواند بدون انقضا هم باشد: آن‌وقت expires_at برابر null است و سقف همچنان اعمال می‌شود). مشتری شما آن را مثل هر کلید OneProvider به کار می‌برد.
• کدها. دسته‌هایی از کدهای یک‌بارمصرف که هر جا بخواهید می‌فروشید. کد فعال‌شده به کلیدی تبدیل می‌شود که سقف آن برابر مبلغ کد است.
• بسته‌ها. قیمت‌های شما برای مشتریان: مبلغ کلید، قیمت، ارز و انقضا. کلیدها از روی آن‌ها با POST /orders صادر می‌شوند.
• داشبورد بی‌طرف برای هر کلید. هر کلید یک پیوند dashboard_url دارد: مشتری شما مصرف و موجودی باقی‌مانده را می‌بیند، بدون اینکه برند شما یا راز کلید آشکار شود.

قاعدهٔ پول: رزرو و کسر

موجودی نماینده فروش سه عدد دارد:

Reseller balance (balance_usd) = your money on the platform
Reserved (reserved_usd) = unredeemed codes + remaining limits of live keys
Free (available_usd) = Reseller balance - Reserved

پول هنگام ساختن چیزی کسر نمی‌شود، بلکه وقتی کسر می‌شود که مشتری ارزش را دریافت کند و آن را مصرف کند. تا آن موقع فقط رزرو شده است:

• دستهٔ کد فقط مبلغ را رزرو می‌کند. با ابطال کدهای فعال‌نشده، رزرو آزاد می‌شود.
• کد فعال‌شده به کلیدی تبدیل می‌شود که سقف آن رزرو می‌ماند.
• صدور کلید سقف آن را رزرو می‌کند؛ مصرف روی کلید، از موجودی نماینده فروش کسر می‌شود.
• حذف کلید یا کم کردن سقف آن، باقی‌ماندهٔ مصرف‌نشده را بلافاصله به «قابل استفاده» (Free) برمی‌گرداند.
• توقف کلید رزرو آن را نگه می‌دارد.

هر کلید جدید، شارژ کلید و دستهٔ کد باید در «قابل استفاده» (Free) جا شود؛ وگرنه پاسخ 409 insufficient_balance است. هر سه عدد را GET /balance برمی‌گرداند: balance_usd، reserved_usd، available_usd.

اولین درخواست

1. در حساب کاربری، تب نماینده فروش و بخش «API و تنظیمات» را باز کنید و یک توکن بسازید. مقدار آن فقط یک بار نمایش داده می‌شود.
2. توکن را در یک متغیر محیطی روی سرور خود بگذارید و /balance را صدا بزنید:

export OP_PARTNER_TOKEN="rsk_..."
curl -s https://app.oneprovider.dev/partner/v1/balance \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"balance_usd": "120.00",
"reserved_usd": "35.50",
"available_usd": "84.50"
}

مثال فقط بعضی از فیلدهای پاسخ را نشان می‌دهد؛ مبلغ همیشه یک رشته با دو رقم اعشار است. فهرست کامل در مرجع متدها و در OpenAPI است.

شارژ موجودی نماینده فروش

درگاه‌های پرداخت در دسترس و حداقل مبلغ آن‌ها در topup_providers از GET /balance هستند. پرداخت با POST /balance/topups ساخته می‌شود (دسترسی billing؛ هدر Idempotency-Key الزامی است). پیوند پرداختی را که در پاسخ برمی‌گردد به پرداخت‌کننده می‌دهید.

curl -s -X POST https://app.oneprovider.dev/partner/v1/balance/topups \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-2026-10-08-001" \
-H "Content-Type: application/json" \
-d '{"balance_usd":"100.00","provider":"<id from topup_providers>"}'

پاسخ شامل order_id و pay_url است (201). وضعیت پرداخت: GET /balance/topups/{order_id}؛ واریز را رویداد balance.topped_up وب‌هوک هم اعلام می‌کند.

گزارش اقدامات

GET /audit (دسترسی read) گزارش همهٔ اقدام‌های حساب شما را برمی‌گرداند: از حساب کاربری، با توکن‌های API و از سوی سیستم. ردیف‌ها تغییرناپذیرند (مسیری برای ویرایش یا حذف وجود ندارد) و هرگز رازی ندارند: نه کلید، نه توکن، نه کد و نه راز وب‌هوک. شیء فقط کوتاه نشان داده می‌شود: انتهای کلید، برچسب دسته یا نام بسته.

curl -s "https://app.oneprovider.dev/partner/v1/audit?period=7d&action=key.&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"items": [
{
"id": "<row id>",
"at": "2026-10-08T12:00:00Z",
"actor": { "kind": "token", "label": "shop backend" },
"action": "key.created",
"object": { "type": "key", "label": "anna-main (...4f2a)" },
"money": { "reserve_delta": "25.00", "debit_delta": "0.00", "available_after": "59.50" },
"ip": "203.0.113.7",
"request_id": "req_..."
}
],
"next": null,
"actions": ["key.created", "key.topped_up"]
}

actor.kind یکی از این‌هاست: user (حساب کاربری)، token، system یا bot (ربات فروشگاه نماینده). money (اگر اقدام به پول ربطی نداشته باشد null است) تغییرهای علامت‌دار رزرو و کسر را نشان می‌دهد؛ available_after ممکن است null باشد. پاسخ فهرست کامل اقدام‌ها را هم در actions دارد:

key.created key.topped_up key.limit_changed key.updated key.paused key.resumed key.exhausted key.rotated key.extended key.expiry_changed key.deleted
code_batch.created code_batch.revoked code_batch.expired code.redeemed
plan.created plan.updated plan.deleted
token.created token.revoked
webhook.created webhook.deleted webhook.tested webhook.retried
balance.topup order.completed
customer.created customer.updated customer.blocked customer.unblocked
settings.updated account.activated

قراردادها

• Base URL: https://app.oneprovider.dev/partner/v1.
• همه‌جا JSON؛ مبلغ یک رشتهٔ USD با دو رقم اعشار است ("12.50")؛ زمان‌ها ISO 8601 و UTC هستند (2026-10-08T12:00:00Z).
• فقط از سرور خودتان API را صدا بزنید: CORS وجود ندارد و توکن هرگز نباید در مرورگر یا برنامهٔ موبایل قرار بگیرد.
• توکن‌ها، دسترسی‌ها، محدودیت نرخ، خطاها، Idempotency و صفحه‌بندی: مجوزدهی و سقف‌ها .

بعدی

• کلیدها و مشتریان : صدور، شارژ، توقف، حذف.
• سفارش‌ها : چگونه سایت خودتان را بسازید.
• کدها و بسته‌ها .
• وب‌هوک‌ها : رویدادها و بررسی امضا.
• مرجع متدها و openapi.yaml .