کدها و بسته‌های API نماینده

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

دسته‌های کد

دسته با POST /code-batches ساخته می‌شود (دسترسی codes؛ هدر Idempotency-Key الزامی است): label، count تا 200، amount_usd تا 5000 برای هر کد. اختیاری: key_expires_days یا key_expires_hours (کلید پس از فعال شدن کد چقدر زنده می‌ماند؛ پیش‌فرض 90 روز) یا key_expires_never: true (کلید بدون انقضا، سقف همچنان اعمال می‌شود؛ همراه با مدت عمر مجاز نیست) و codes_valid_until (تا چه زمانی می‌توان کد را فعال کرد، ISO 8601، در آینده و حداکثر 2 سال بعد؛ پس از آن کدهای فعال‌نشده خودکار ابطال می‌شوند و رزرو آزاد می‌شود).

curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: batch-oct-001" \
-H "Content-Type: application/json" \
-d '{"label":"October promo","count":50,"amount_usd":"5.00","key_expires_hours":24,"codes_valid_until":"2026-12-31T23:59:59Z"}'

دسته فقط هزینهٔ خود (count x amount_usd) را روی موجودی نماینده فروش رزرو می‌کند: باید در «قابل استفاده» (Free) جا شود، اما چیزی کسر نمی‌شود. وقتی کدی فعال شود به کلیدی تبدیل می‌شود که سقف آن رزرو می‌ماند و پول به‌اندازهٔ مصرف کسر می‌شود. ابطال کدهای فعال‌نشده رزرو را آزاد می‌کند. شیء دسته: id، label، count، amount_usd، used، revoked، key_expires_hours، key_expires_days، key_expires_never، codes_valid_until، created_at (key_expires_hours و key_expires_days هم برای دستهٔ بدون انقضای کلید و هم برای دستهٔ با پیش‌فرض 90 روز null هستند: key_expires_never این دو را از هم جدا می‌کند). GET /code-batches/{id} فعال‌سازی‌ها را هم دارد: چه کسی کدام کد را و کی فعال کرد (code_tail، redeemed_at، key_id)، جدیدترین‌ها اول، حداکثر 1000؛ پاسخ ابطال هم revoked_now و refunded_usd را دارد.

# list batches, read one, list its codes
curl -s https://app.oneprovider.dev/partner/v1/code-batches -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s https://app.oneprovider.dev/partner/v1/code-batches/<batch id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s "https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/codes?status=active&limit=100" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# revoke what is still unredeemed
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/revoke -H "Authorization: Bearer $OP_PARTNER_TOKEN"

شیء کد: code، status (active، used، revoked: active/used/revoked)، amount_usd، batch_id، redeemed_at، key_id. وضعیت یک کد: GET /codes/{code}.

فعال‌سازی کد از طریق API

اگر خودتان کد را به کلید تبدیل می‌کنید، POST /codes/{code}/redeem را صدا بزنید (هدر Idempotency-Key الزامی است). مشتری را می‌توان با customer_id یا customer_external_id فرستاد.

curl -s -X POST https://app.oneprovider.dev/partner/v1/codes/<code>/redeem \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: redeem-<code>" \
-H "Content-Type: application/json" \
-d '{"customer_external_id":"user-77"}'

پاسخ 201 کلید و راز آن را دارد (تکرار همان فراخوانی با همان Idempotency-Key همان کلید را برمی‌گرداند). کدی که قبلاً به راه دیگری فعال شده 409 code_used می‌دهد و کد ابطال‌شده 409 code_revoked؛ customer_id همراه با customer_external_id یعنی 400 invalid، و مشتری مسدودشده 409 customer_blocked.

بسته‌ها

بسته قیمت شما برای مشتریان است: کلید چند USD می‌گیرد، مشتری چقدر و با چه ارزی به شما می‌پردازد، و برای چه مدتی. بسته‌ها ورودی POST /orders هستند (پارامتر plan_id). حداکثر 20 بسته مجاز است (409 plan_limit). خواندن بسته‌ها به دسترسی read نیاز دارد و تغییرشان به plans.

curl -s -X POST https://app.oneprovider.dev/partner/v1/plans \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Start 10 USD","balance_usd":"10.00","price":"890.00","currency":"RUB","expires_days":30,"sort":1,"active":true}'
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" -d '{"active":false}'
curl -s -X DELETE https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"

GET /pricing محدودیت‌هایی را که باید رعایت کنید برمی‌گرداند: حداقل و حداکثر مبلغ کلید، حداکثر مدت عمر، حداکثر مبلغ کد، اندازهٔ دسته، تعداد بسته‌ها و توکن‌ها، تعداد کلیدهای زنده (key_limit) و plan_currencies (ارزهای بسته‌ها). بسته را می‌توان با Idempotency-Key ساخت (اختیاری): تکرار همان بسته را برمی‌گرداند و بستهٔ دوم نمی‌سازد. PATCH که به مدت عمر اشاره نکند آن را همان‌طور که بود نگه می‌دارد. تا وقتی یک خرید باز در ربات برای این بسته وجود دارد، حذف، گران‌تر کردن و تغییر ارز رد می‌شود (409 plan_in_use).