قرارداد HTTP API

مرجع API

همهٔ بدنه‌ها JSON هستند و حداکثر 64 KiB. فیلد ناشناخته رد می‌شود (400 INVALID_BODY). هر پاسخ هدر X-Request-ID دارد که در بدنهٔ خطا هم تکرار می‌شود

هدرها و اعتبارها

هدر	کجا	توضیح
`Authorization: Bearer dck_…`	بک‌اند	اعتبار بک‌اند با scope لازم؛ هرگز در مرورگر
`X-DigiCaptcha-Site-Key`	مرورگر	کلید عمومی سایت؛ راز نیست
`X-DigiCaptcha-Session-Token`	مرورگر	`completion_token` نشست برای challenge، redeem و complete
`Idempotency-Key`	همه‌جا	برای ایجاد intent، نشست، complete و siteverify الزامی است؛ 16 تا 128 نویسه از `A-Z a-z 0-9 . _ : -`
`Origin`	مرورگر	مرورگر خودش می‌فرستد و باید در مبدأهای مجاز سایت باشد
`X-CSRF-Token`	پنل	برای تغییرات API مدیریت، همراه کوکی `digicaptcha_session`

مسیرهای عمومی

POST/v1/intentsBearer · intents:create

site_id: شناسهٔ سایت؛ باید همان سایت اعتبار باشد
action: نام عملیات، الگوی ^[a-zA-Z0-9_.:-]{1,64}$
request_hash: الگوی ^sha256:[a-f0-9]{64}$
binding_version: فقط "jcs-v1"
expires_in_seconds: 30 تا 600؛ پیش‌فرض 300

پاسخ 201: {intent_id, action, expires_at}

POST/v1/sessionsSite key · Origin

intent_id: الزامی؛ intent همان سایت
locale: اختیاری
client_capabilities: اختیاری؛ هر JSON

پاسخ 201: {session_id, intent_id, completion_token, expires_at, policy_version, challenge} ساختار challenge و renderer به موتور انتخاب‌شده وابسته است، تنظیمات Cap قرارداد همهٔ موتورهای دیگر نیستند توکن نشست را محرمانه نگه دارید؛ تکرار مجاز با همان کلید idempotency می‌تواند همان پاسخ اولیه را برگرداند

POST/v1/sessions/{id}/cap/challengeSite key · Session token

بدنه {}. پاسخ Cap را بدون تغییر و با همان کد وضعیت برمی‌گرداند. موفقیت به حساب نمی‌آید

POST/v1/sessions/{id}/cap/redeemSite key · Session token

بدنه {token, solutions} از حل‌کنندهٔ Cap. پاسخ Cap با token برگردانده می‌شود. هنوز رسیدی صادر نشده است

نمونهٔ زیر برای Cap است ساختار provider_evidence برای هر موتور متفاوت است پس از ارسال verify و قطع ارتباط، نتیجه نامعین است و نباید موفقیت یا انتقال به موتور دیگر فرض شود

POST/v1/sessions/{id}/completeSite key · Session token

بدنه {"provider_evidence": {"token": "…"}} با توکن redeem. Captchas.ir توکن را با رمز سایت نزد Cap تأیید می‌کند. پاسخ 200: {receipt, receipt_expires_at, intent_id, session_id}. تکرار با همان Idempotency-Key همان رسید را برمی‌گرداند و Cap را دوباره صدا نمی‌زند

همان درخواست و همان Idempotency-Key، پاسخ اولیه را در همان دورهٔ بازیابی برمی‌گرداند مصرف دوبارهٔ رسید با کلید تازه رد می‌شود پس از بازیابی پایگاه داده، رسید قدیمی قابل اتکا نیست

POST/v1/siteverifyBearer · receipts:verify

بدنه {receipt, intent_id, action, request_hash}. پاسخ 200: {success: true, verification_id, intent_id, site_id, action, request_hash, verified_at}. رسید مصرف‌شده 409 ALREADY_CONSUMED، رسید سایت دیگر 403 BINDING_MISMATCH و رسید منقضی 410 SESSION_EXPIRED می‌گیرد

GET/v1/stats?days=30Bearer · dcs_…

آمار فقط‌خواندنی یک سایت برای داشبورد یا اسکریپت بیرونی. توکن را در صفحهٔ سایت بخش «محافظت و دسترسی آمار» بسازید؛ فقط یک بار نشان داده می‌شود و هر سایت یک توکن فعال دارد. پاسخ 200: {site_id, name, days, totals, series, countries}. توکن باطل یا نادرست 401 می‌گیرد

مسیرهای دیگر

مسیر	توضیح
OPTIONS `/v1/sessions…`	preflight برای مبدأهای ثبت‌شده؛ `Access-Control-Max-Age: 60`
GET `/livez`	زنده بودن فرایند
GET `/readyz`	در دسترس بودن پایگاه؛ `stage` برابر `m1-sqlite` یا `m1-postgres`
GET `/v1/capabilities`	کاتالوگ هشت موتور با `implemented` و `readiness`
GET `/widget/cap.js`	اسکریپت ویجت Captchas.ir
GET `/widget/vendor/{name}`	`cap.min.js`، `cap_wasm_bg.wasm` و `hashwx.wasm`
GET `/playground/`	آزمایش کامل جریان در مرورگر؛ فراخوانی‌هایش نشست مدیر می‌خواهند

API مدیریت

پنل از این مسیرها استفاده می‌کند. احراز هویت با کوکی digicaptcha_session است و هر تغییر هدر X-CSRF-Token برابر کوکی digicaptcha_csrf می‌خواهد

مسیر	کاربرد
POST `/admin/v1/session/login`	ورود با `{username, password}`
POST `/admin/v1/session/mfa`	تکمیل رمز دوم با `{method, code}`
POST `/admin/v1/session/mfa/email`	ارسال کد ایمیلی هنگام ورود
POST `/admin/v1/session/bootstrap`	ورود اولیه با `{token}`
GET `/admin/v1/session`	نشست فعلی
POST `/admin/v1/session/logout`	خروج
GET `/admin/v1/monitor`	داده‌های صفحهٔ پایش
GET `/admin/v1/security/mfa`	وضعیت رمز دوم؛ مسیرهای `…/mfa/totp` و `…/mfa/email` برای فعال‌سازی و تغییر
GET `/admin/v1/sites`	فهرست سایت‌ها با `cursor` و `page_size`
POST `/admin/v1/sites`	سایت تازه با `{name, environment, allowed_origins}` و Idempotency-Key
GET `/admin/v1/sites/{id}`	جزئیات سایت، کلیدها، اعتبارها و نمونه‌ها
POST `/admin/v1/sites/{id}/public-keys`	کلید عمومی تازه
POST `/admin/v1/sites/{id}/credentials`	اعتبار بک‌اند با `{scopes}`
POST `/admin/v1/credentials/{id}/rotate`	چرخش اعتبار
POST `/admin/v1/sites/{id}/cap-instances`	اتصال Cap با `{name, endpoint, admin_key, hashwx_difficulty}`
POST `/admin/v1/cap-instances/{id}/rotate-secret`	چرخش رمز سایت در Cap
GET `/admin/v1/providers`	کاتالوگ موتورها
PUT `/admin/v1/public-keys/{id}`	برچسب کلید عمومی با `{label}`
POST `/admin/v1/public-keys/{id}/revoke`	باطل کردن یک کلید عمومی
PUT `/admin/v1/credentials/{id}`	برچسب و دسترسی کلید سرور با `{label, scopes}`
POST `/admin/v1/credentials/{id}/revoke`	باطل کردن یک کلید سرور
DELETE `/admin/v1/sites/{id}`	حذف سایت با `{confirm_name}` که باید دقیقاً نام سایت باشد
POST `/admin/v1/security/mfa/recovery`	ده رمز پشتیبان تازه با `{password}`، هر رمز یک بار
PUT `/admin/v1/sites/{id}`	ویرایش `{name, environment, allowed_origins, status, revision}`؛ `status` یکی از `active` و `disabled` است و `revision` کهنه پاسخ 409 می‌گیرد
GET `/admin/v1/stats/overview?days=30`	سری روزانه، امروز و جمع همهٔ سایت‌ها، از 1 تا 366 روز
GET `/admin/v1/stats/sites`	امروز به تفکیک سایت
GET `/admin/v1/sites/{id}/stats?days=30`	سری روزانهٔ یک سایت
POST `/admin/v1/session/password`	تغییر گذرواژه با `{current_password, new_password}`؛ نشست‌های دیگر بسته می‌شوند
GET `/admin/v1/version`	revision ساخت، نسخهٔ Go، طرح پایگاه داده و نسخهٔ Cap
GET `/healthz`	همان پاسخ `/readyz`
GET `/admin/v1/events/traffic`	رویدادهای ترافیک با `site`، `kind`، `country`، `ip`، `cursor` و `limit`. نوع‌ها: `session.issued`، `cap.solved`، `cap.failed`، `cap.indeterminate`، `verify.ok`، `verify.rejected`، `blocked.rate`
GET `/admin/v1/events/audit`	سابقهٔ ممیزی با `prefix` مثل `cap.` و `cursor`
GET `/admin/v1/stats/countries?days=30`	شمارش به تفکیک کشور، با `site` اختیاری
GET `/admin/v1/stats/hourly?hours=24`	سری ساعتی، با `site` اختیاری
GET `/admin/v1/stats/addresses`	نشانی‌های پرتکرار بر اساس شیوهٔ نگهداری IP
GET PUT `/admin/v1/settings`	`{ip_mode, retention_days, login_captcha_site}`؛ `ip_mode` یکی از `masked`، `full` و `off`، نگهداری 1 تا 90 روز. سایت کپچای ورود باید کلید عمومی و نمونهٔ Cap فعال داشته باشد وگرنه `409`
GET POST `/admin/v1/mcp-tokens`	فهرست و ساخت توکن MCP با `{name}`، حداکثر بیست توکن فعال؛ `DELETE /admin/v1/mcp-tokens/{id}` باطل می‌کند
PUT `/admin/v1/sites/{id}/settings`	`{rate_limit_per_min}` از 0 تا 100٬000؛ صفر یعنی بی‌سقف
POST DELETE `/admin/v1/sites/{id}/stats-token`	صدور یا ابطال توکن آمار سایت
PUT `/admin/v1/cap-instances/{id}/config`	`{hashwx_difficulty, obfuscation_level}`؛ سختی 50٬000 تا 5٬000٬000 و درهم‌سازی 1 تا 10. اول روی Cap اعمال و بعد ثبت می‌شود
GET `/admin/v1/session/login-captcha`	آیا کپچای ورود روشن است. قاب `/login-captcha` با `POST` همین مسیر intent ورود را می‌سازد و رسید در `captcha` بدنهٔ ورود فرستاده می‌شود

خطاها

همهٔ خطاها یک شکل دارند:

json

{
  "error": {
    "code": "ALREADY_CONSUMED",
    "message": "This receipt was already consumed.",
    "request_id": "5f0c2a9e8b7d4c3e1a2b3c4d5e6f7a8b",
    "retryable": false
  }
}

HTTP	code	معنی
400	`INVALID_BODY` · `INVALID_REQUEST`	JSON نامعتبر، فیلد ناشناخته یا اعتبارسنجی ناموفق، از جمله نبود Idempotency-Key
401	`UNAUTHENTICATED`	اعتبار، کلید یا نشست وجود ندارد یا معتبر نیست
403	`FORBIDDEN`	scope ناکافی، مبدأ غیرمجاز یا CSRF نادرست
403	`BINDING_MISMATCH`	رسید یا intent به سایت، action یا نصب دیگری تعلق دارد
404	`NOT_FOUND`	منبع در این tenant نیست
409	`ALREADY_CONSUMED`	رسید قبلاً مصرف شده است
409	`IDEMPOTENCY_CONFLICT`	همان کلید با بدنهٔ متفاوت
409	`OPERATION_IN_PROGRESS`	همان عملیات هنوز در جریان است؛ `retryable: true`
409	`CONFLICT`	منبع در وضعیتی نیست که این عملیات را بپذیرد
410	`SESSION_EXPIRED`	intent، نشست یا رسید منقضی شده است
413	`BODY_TOO_LARGE`	بدنه بیش از 64 KiB
400	`CAPTCHA_REQUIRED`	کپچای ورود پنل روشن است و رسید آن فرستاده نشده یا پذیرفته نشد
422	`INVALID_PROOF`	Cap توکن را رد کرد یا توکن مال سایت Cap دیگری است
502	`UPSTREAM_REJECTED`	Cap درخواست مدیریتی را رد کرد
503	`UPSTREAM_UNAVAILABLE`	Cap برای challenge یا redeem در دسترس نبود؛ `retryable: true`
503	`UPSTREAM_RESULT_UNKNOWN`	نتیجهٔ تأیید نامعلوم است؛ رسیدی صادر نشده و نباید با همان proof تکرار شود
503	`NO_ELIGIBLE_PROVIDER`	هیچ موتور واجد شرایط و فعالی برای این سایت در دسترس نیست
503	`STORAGE_UNAVAILABLE`	پایگاه داده در دسترس نیست؛ `retryable: true`
429	`RATE_LIMITED`	درخواست ورود یا نشست مرورگر از یک نشانی زیاد است، یا سقف نشست سایت برای هر IP پر شده؛ به اندازهٔ `Retry-After` ثانیه صبر کنید
503	`MAIL_NOT_CONFIGURED`	SMTP تنظیم نشده است
503	`ADAPTERS_NOT_IMPLEMENTED`	حالت foundation، بدون پایگاه
500	`INTERNAL_ERROR`	خطای داخلی؛ عملیات بسته شکست خورد

Idempotency

برای هر عملیات منطقی یک کلید تصادفی بسازید و در تلاش‌های مجدد همان عملیات، همان کلید را بفرستید
همان کلید با همان بدنه، پاسخ ذخیره‌شده را برمی‌گرداند. این مصرف دوم رسید نیست و موفقیت تازه نمی‌سازد
همان کلید با بدنهٔ متفاوت 409 IDEMPOTENCY_CONFLICT می‌گیرد
اگر عملیات قبلی هنوز در جریان باشد 409 OPERATION_IN_PROGRESS برمی‌گردد
پس از UPSTREAM_RESULT_UNKNOWN کور تلاش نکنید. یک intent و نشست تازه بسازید

مسیرهای پروتکل موتور

این فهرست از ثبت مسیرهای همین نسخه استخراج شده است وجود مسیر به معنی پیکربندی، مجوز یا آزمون موفق آن موتور در محیط شما نیست کلید عمومی، Origin و توکن نشست صادرشده باید با همان سایت و موتور تطبیق داشته باشند

Method	Route
POST	`/v1/sessions/{id}/cap/challenge`
POST	`/v1/sessions/{id}/cap/redeem`
POST	`/v1/sessions/{id}/wicketkeeper/challenge`
GET	`/v1/sessions/{id}/fcaptcha/api/pow/challenge`
POST	`/v1/sessions/{id}/fcaptcha/api/verify`
POST	`/v1/sessions/{id}/gocaptcha/data`
POST	`/v1/sessions/{id}/gocaptcha/check`
POST	`/v1/sessions/{id}/digitalcaptcha/challenge`
POST	`/v1/sessions/{id}/digitalcaptcha/check`
POST	`/v1/sessions/{id}/captchapro/data`
POST	`/v1/sessions/{id}/captchapro/verify`
POST	`/v1/sessions/{id}/iconcaptcha`
POST	`/v1/sessions/{id}/mosparo/api/v1/frontend/{action}`
POST	`/v1/sessions/{id}/mcaptcha/config`
POST	`/v1/sessions/{id}/mcaptcha/verify`
POST	`/v1/sessions/{id}/mcaptcha/frame`
POST	`/v1/sessions/{id}/altcha/challenge`
POST	`/v1/sessions/{id}/altcha/verify`

قرارداد قابل دانلود

مسیرهای JSON ثبت‌شده در این نسخه از کد استخراج می‌شوند و نمونه‌های درخواست و پاسخ آزمون‌ها با قرارداد بررسی می‌شوند پاسخ‌های عبوری موتور ممکن است ساختار باز داشته باشند مسیرهای HTML، دمو و فایل‌های ثابت خارج از این قراردادند

OpenAPI 3.1 JSON · OpenAPI 3.1 YAML