سفارش‌های API نماینده

فروشگاه خودتان را بسازید: مشتری به شما پرداخت می‌کند، شما POST /orders را صدا می‌زنید و کلید می‌گیرید. Idempotency با external_order_id و شارژ کلیدهای موجود.

روند فروش

1. مشتری شما در سایت شما و با صفحهٔ پرداخت خودتان پول می‌دهد (OneProvider در این پرداخت نقشی ندارد).
2. سرور شما تأیید پرداخت را می‌گیرد و POST /orders را صدا می‌زند.
3. سرویس OneProvider سقف کلید را روی موجودی نماینده فروش شما رزرو می‌کند (پول به‌اندازهٔ مصرف کسر می‌شود) و سفارشی با وضعیت completed می‌سازد.
4. کلید موجود در پاسخ و در صورت تمایل dashboard_url را به مشتری می‌دهید.

سفارش یا کلید جدید صادر می‌کند (kind: "new_key") یا کلید موجود را شارژ می‌کند (kind: "topup"، وقتی key_id فرستاده شود).

ساخت سفارش

آنچه باید تحویل شود را یک بسته (plan_id، نگاه کنید به کدها و بسته‌ها ) یا مستقیماً یک مبلغ تعیین می‌کند: limit_usd و expires_days یا expires_hours. مشتری را می‌توان با customer_id یا customer_external_id فرستاد (مشتریِ ساخته‌شده از قبل). فیلدهای charged_amount و charged_currency ثبت می‌کنند مشتری چه چیزی به شما پرداخته؛ آن‌ها در GET /stats می‌آیند و روی مبلغ کسرشده اثری ندارند.

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1042" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "shop-1042",
"limit_usd": "10.00",
"expires_days": 30,
"customer_external_id": "user-77",
"name": "anna-main",
"charged_amount": "890.00",
"charged_currency": "RUB"
}'

{
"id": 42,
"external_order_id": "shop-1042",
"status": "completed",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00",
"charged_amount": "890.00",
"charged_currency": "RUB",
"created_at": "2026-10-08T12:00:00Z",
"key": {
"id": "<key id>",
"name": "anna-main",
"status": "active",
"limit_usd": "10.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}
}

key شیء کلید است (مثل پاسخ صدور) و راز در key.key است. فقط برای کلید جدید و در پاسخ POST /orders (و در تکرار دقیق آن) می‌آید؛ GET /orders و GET /orders/{id} آن را ندارند. راز را در همان تراکنشی که سفارش را ثبت می‌کنید ذخیره کنید. وقتی سفارش از بسته‌ای بدون مدت (expires_never) ساخته شود، expires_at کلید برابر null است.

Idempotency با external_order_id

external_order_id شمارهٔ سفارش در سیستم شماست. تکرار درخواست با همان شماره و همان پارامترها نه کلید دوم صادر می‌کند و نه دو بار پول کسر می‌کند: همان سفارش و همان کلید را پس می‌گیرید (با همان راز، پس پاسخی که در راه گم شده با تکرار فراخوانی بازیابی می‌شود). همان شماره با پارامترهای متفاوت 409 external_order_id_conflict می‌دهد. به این ترتیب تلاش دوباره پس از تایم‌اوت یا قطع اتصال بی‌خطر است. سفارش را می‌توانید با GET /orders?external_order_id=shop-1042 پیدا کنید.

شارژ کلید موجود

key_id و یک مبلغ (limit_usd یا یک بسته) بفرستید:

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1043" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"shop-1043","key_id":"<key id>","limit_usd":"10.00","charged_amount":"890.00","charged_currency":"RUB"}'

در پاسخ kind برابر topup است و راز وجود ندارد. مبلغ به سقف کل کلید اضافه می‌شود و مثل بقیه باید در «قابل استفاده» (Free) جا شود (رزرو می‌شود و به‌اندازهٔ مصرف کسر می‌شود).

نمونهٔ پردازشگر پرداخت (Python)

import os
import requests
BASE = "https://app.oneprovider.dev/partner/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["OP_PARTNER_TOKEN"]}
def fulfil_paid_order(order_no: str, user_id: str, plan_id, paid: str, currency: str) -> dict:
"""Call it after YOUR payment provider confirmed the payment (it may be called twice)."""
r = requests.post(
BASE + "/orders",
headers={**HEADERS, "Idempotency-Key": "order-" + order_no},
json={
"external_order_id": order_no,
"plan_id": plan_id,
"customer_external_id": user_id,
"charged_amount": paid,
"charged_currency": currency,
},
timeout=30,
)
if r.status_code == 409 and r.json()["error"]["code"] == "insufficient_balance":
raise RuntimeError("Top up the reseller balance, then retry the same call")
r.raise_for_status()
order = r.json()
# order["key"] (the key object, the secret is order["key"]["key"]) is present on a new_key order, a repeat returns it again
return order

available_usd را زیر نظر بگیرید و مشترک وب‌هوک balance.low شوید تا پیش از آنکه سفارشی به 409 insufficient_balance بخورد، موجودی را شارژ کنید. نگاه کنید به وب‌هوک‌ها .