کلیدها و مشتریان API نماینده

صدور، شارژ، توقف و حذف کلیدهای مشتریان و مدیریت مشتریانتان از طریق API نماینده فروش، با نمونه‌های curl.

شیء کلید

صدور کلید

POST /keys (دسترسی keys؛ هدر Idempotency-Key الزامی است). الزامی: name و limit_usd؛ اختیاری: expires_days (1..365، پیش‌فرض 30) یا expires_hours (1 تا 8760، مثلاً 1 برای کلید یک‌ساعته؛ هر دو با هم نه)، customer_id، customer_label، concurrency.

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: key-anna-001" \
-H "Content-Type: application/json" \
-d '{"name":"anna-main","limit_usd":"25.00","expires_days":30,"customer_label":"Anna"}'
# a one-hour key
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys -H "Authorization: Bearer $OP_PARTNER_TOKEN" -H "Idempotency-Key: key-trial-001" -H "Content-Type: application/json" -d '{"name":"trial","limit_usd":"1.00","expires_hours":1}'

چند کلید یکسان با هم: POST /keys/bulk با count (1..50)، name_prefix و همان limit_usd و expires_days/expires_hours. کلیدها {name_prefix}-1 … {name_prefix}-N نام می‌گیرند. ابتدا کل مبلغ count x limit_usd بررسی می‌شود؛ اگر فراخوانی باز هم نیمه‌کاره بماند، آن را با همان Idempotency-Key تکرار کنید: کلیدهای ساخته‌شده دوباره برمی‌گردند و بقیه صادر می‌شوند.

{
"id": "<key id>",
"name": "anna-main",
"customer_label": "Anna",
"status": "active",
"limit_usd": "25.00",
"spent_usd": "0.00",
"remaining_usd": "25.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}

سقف کلید روی موجودی نماینده فروش رزرو می‌شود. اگر در «قابل استفاده» (Free، available_usd) جا نشود، پاسخ 409 insufficient_balance است؛ نام تکراری 409 name_taken می‌دهد و رسیدن به حداکثر تعداد کلیدها 409 key_limit.

فهرست و خواندن

# active keys of one customer
curl -s "https://app.oneprovider.dev/partner/v1/keys?status=active&customer_id=<customer id>&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# one key (no secret) with dashboard_url
curl -s https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

فیلترها: status، query (جست‌وجو در نام و برچسب)، customer_id. مصرف روزانه و به تفکیک مدل: GET /keys/{id}/usage?days=30 (دسترسی read، بازهٔ 1 تا 90 روز، پیش‌فرض 30). پاسخ {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]} است: روزهای UTC بدون شکاف (صفرها هم هستند)، مبلغ با همان اعداد صفحهٔ مصرف حساب کاربری، توکن‌ها: input، output، cache_read، cache_write. مصرف همهٔ کلیدهای فعال یک مشتری: GET /customers/{id}/usage (پاسخ keys و truncated را دارد؛ حداکثر 100 کلید خوانده می‌شود). وقتی ارائه‌دهنده از کار افتاده باشد: 503 provider_unavailable.

ویرایش، شارژ، توقف

# change the limit / expiry / name / label / concurrency
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"limit_usd":"40.00"}'
# add 10.00 USD to the key limit
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/topup \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-anna-001" \
-H "Content-Type: application/json" \
-d '{"amount_usd":"10.00"}'
# pause and resume
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/pause -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/resume -H "Authorization: Bearer $OP_PARTNER_TOKEN"

limit_usd در PATCH سقف کل جدید است؛ نمی‌تواند از مبلغ مصرف‌شده کمتر شود (400 limit_below_spent). افزایش، مثل کلید جدید، باید در «قابل استفاده» (Free) جا شود. کم کردن سقف، تفاوت مصرف‌نشده را بلافاصله به «قابل استفاده» (Free) برمی‌گرداند. توقف رزرو را نگه می‌دارد. انقضا: expires_days/expires_hours آن را روی اکنون + N می‌گذارند، extend_days/extend_hours به انقضای فعلی N اضافه می‌کنند (اگر گذشته باشد، از اکنون؛ کلید منقضی دوباره باقی‌ماندهٔ خود را رزرو می‌کند و آن باید در «قابل استفاده» (Free) جا شود)؛ این دو با هم مجاز نیستند و انقضا نباید بیش از 8760 ساعت جلوتر باشد. با Idempotency-Key اختیاری، extend_* تکراری یک بار تمدید می‌کند. کلید بدون انقضا (expires_at = null) چیزی برای تمدید ندارد: extend_* به آن اعمال نمی‌شود و expires_* برایش مدت تعیین می‌کند. کلید مشتریِ مسدودشده فقط name و customer_label را می‌پذیرد، هر چیز دیگر 409 customer_blocked است.

حذف کلید

curl -s -X DELETE https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

وقتی کلید فوراً حذف شود، پاسخ 200 {"state":"deleted"} است و تا وقتی حذف در جریان است 202 {"state":"deleting"}. باقی‌ماندهٔ مصرف‌نشدهٔ سقف بلافاصله به «قابل استفاده» (Free) برمی‌گردد.

صدور مجدد کلید (rotate)

POST /keys/{id}/rotate (دسترسی keys؛ هدر Idempotency-Key الزامی است): راز جدیدی برای همان مشتری، مثلاً وقتی راز قبلی لو رفته است. راز قبلی بلافاصله از کار می‌افتد. باقی‌ماندهٔ مصرف‌نشده و انقضا به کلید جدید منتقل می‌شوند.

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/rotate \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: rotate-anna-001"

این یک کلید جدید با id جدید است: سابقهٔ مصرف نزد کلید قبلی (که اکنون حذف شده) می‌ماند. پاسخ 201 شامل شیء کلید، key (راز جدید، فقط یک بار نمایش داده می‌شود) و rotated_from (شناسهٔ کلید قبلی) است. خطاها: 404 key_not_found، 409 key_limit، key_exhausted (چیزی نمانده)، key_expired (منقضی: ابتدا تمدید کنید)، 503 provider_unavailable.

مشتریان

مشتری خریدار شماست. می‌توان کلیدها، سفارش‌ها و کدها را به او وصل کرد: شناسهٔ خودتان در external_id ذخیره می‌شود (یکتا، تا 64 نویسه).

curl -s -X POST https://app.oneprovider.dev/partner/v1/customers \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"external_id":"user-77","name":"Anna","note":"from the Telegram shop"}'
curl -s "https://app.oneprovider.dev/partner/v1/customers?external_id=user-77" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

شیء مشتری: id، external_id، name، note، blocked، keys_count، created_at. نام و یادداشت را با PATCH /customers/{id} ویرایش کنید. external_id تکراری 409 customer_exists می‌دهد.

مسدود کردن مشتری

curl -s -X PATCH https://app.oneprovider.dev/partner/v1/customers/<customer id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"blocked":true}'

مسدودسازی (دسترسی keys) همهٔ کلیدهای فعال مشتری را متوقف می‌کند و خود مشتری را با blocked: true علامت می‌زند. صدور کلید، سفارش و فعال‌سازی کد برای او 409 customer_blocked می‌دهد. رفع مسدودیت ({"blocked":false}) فقط کلیدهایی را از سر می‌گیرد که مسدودسازی متوقف کرده بود: کلیدهایی که خودتان متوقف کرده‌اید متوقف می‌مانند.