API ناشر

همهٔ کارهای این پرتال با API ناشر در Control Plane کرسی انجام می‌شود: /developer/v1. همین API را می‌توانید مستقیم از CI خودتان صدا بزنید، مثلاً برای ارسال خودکار هر نسخه.

کلید ناشر

کلید ناشر را تیم کرسی صادر می‌کند؛ ثبت‌نام خودکار نیست. برای گرفتن کلید با تیم کرسی تماس بگیرید. هر کلید با kp_ شروع می‌شود و فقط یک بار، موقع صدور، نشان داده می‌شود؛ کرسی فقط hash آن را نگه می‌دارد. کلید گم‌شده را تیم کرسی باطل می‌کند و کلید تازه می‌دهد.

هر درخواست کلید را در این هدر می‌فرستد:

Authorization: Bearer kp_…

کلید فقط روی /developer/v1 پذیرفته می‌شود و هیچ دسترسی دیگری در کرسی نمی‌دهد. همهٔ مسیرها ناشر را از خود کلید می‌خوانند؛ هیچ مسیری نام ناشر نمی‌گیرد، پس هیچ کلیدی دربارهٔ افزونه‌های ناشر دیگر چیزی نمی‌فهمد. نسخهٔ ناشر دیگر «پیدا نشد» جواب داده می‌شود.

مسیرها

نشانی پایه: https://capi.korsi.ai

مسیر	چه می‌کند
`GET /developer/v1/me`	ناشر این کلید و خود کلید (شناسه، برچسب، چند حرف آخر)
`GET /developer/v1/plugins`	افزونه‌های شما و همهٔ نسخه‌های هر کدام، تازه‌ترین اول
`POST /developer/v1/releases`	ارسال نسخه برای بازبینی
`GET /developer/v1/releases/{plugin_id}/{version}`	وضعیت یک نسخه، با یادداشت بازبین
`GET /developer/v1/usage?month=YYYY-MM`	ماه شما: نصب‌ها با نام مستعار و MU مصرف‌شده

ارسال نسخه

بدنه، manifest را به شکل JSON می‌خواهد؛ فایل YAML را پیش از ارسال تبدیل کنید:

python -c 'import json,sys,yaml; print(json.dumps({"manifest": yaml.safe_load(open("korsi-plugin.yaml")), "requested_tier": "community", "notes": "first release"}))' \
  | curl -sS -X POST "https://capi.korsi.ai/developer/v1/releases" \
      -H "Authorization: Bearer $KORSI_PUBLISHER_KEY" \
      -H "Content-Type: application/json" \
      --data @-

requested_tier یکی از community، verified یا private است، یا خالی. سطح نهایی را بازبین تعیین می‌کند.
notes تا ۴۰۰۰ نویسه: چه چیزی عوض شده و بازبین چطور امتحانش کند.
جواب 201 نسخه است با وضعیت submitted و warnings: چیزهایی که بازبین احتمالاً به آن‌ها ایراد می‌گیرد.

خطاهای ارسال

کد	یعنی
`catalogue.manifest_invalid`	ساختار manifest درست نیست؛ همهٔ مشکل‌ها با هم در `params.problems` آمده‌اند
`catalogue.publisher_mismatch`	`publisher` در manifest ناشر این کلید نیست
`catalogue.plugin_owned_elsewhere`	این `id` مال ناشر دیگری است
`catalogue.version_exists`	این نسخه قبلاً ارسال شده؛ اصلاح یعنی نسخهٔ تازه
`auth.publisher_key_invalid`	کلید نیست، اشتباه است یا باطل شده

کرسی موقع ارسال فقط ساختار کلی manifest را می‌سنجد (schema، id، نسخه، ناشر، نوع، نام‌ها، محل اجرا و plugin_api). بقیه را هر instance موقع انتشار می‌سنجد.

وضعیت نسخه

وضعیت	یعنی
`submitted`	ارسال شده و منتظر بازبینی است
`in_review`	بازبین آن را برداشته است
`approved`	تأیید و امضا شده و آمادهٔ انتشار است
`rejected`	رد شده؛ دلیلش در `review_notes` است
`published`	به instanceهای سازگار فرستاده شده و قابل نصب است
`suspended`	روی کل ناوگان متوقف شده؛ دلیلش در `status_reason` است
`withdrawn`	پس گرفته شده؛ دلیلش در `status_reason` است

مصرف

GET /developer/v1/usage?month=2026-10 برای هر افزونه و هر نصب، MU مصرف‌شده، خریده‌شده و هدیه‌شده و شمار پیشنهادهای اعمال‌شده و ردشده را می‌دهد. ماه به وقت تهران بریده می‌شود. نصب‌ها با نام مستعاری می‌آیند که برای شما ثابت است و برای هیچ کس دیگر معنایی ندارد؛ نام و شناسهٔ سازمان هرگز نمی‌آید. partial: true یعنی بعضی instanceها جواب نداده‌اند و عددها کمینه‌اند.

این API مبلغ ریالی نمی‌دهد: تسویهٔ ناشر را کرسی ماهانه و بر اساس مصرف انجام می‌دهد.