مستندات کپچاکینگ

همه endpoint‌ها زیر پیشوند /captcha/ قرار دارند. برای همه درخواست‌های POST هدر Content-Type را تنظیم کنید.

 /captcha/verify-token 

Content-Type: application/json — این endpoint باید فقط از سرور فراخوانی شود

فیلد	نوع	توضیح
publicKey	ضروریstring	کلید عمومی
privateKey	ضروریstring	کلید خصوصی — هرگز در frontend نگه ندارید
token	ضروریstring	توکن دریافتی از validate

پاسخ موفق:

{ "success": true, "publicKey": "PUB_123" }    

همه پاسخ‌ها JSON هستند. کد HTTP همیشه وضعیت کلی را نشان می‌دهد.

موفق — validate

{ "success": true, "token": "3f2a1b..." }

خطا — validate

{ "success": false, "error": "Invalid time window" }

موفق — verify-token

{ "success": true, "publicKey": "PUB_123" }

خطا — verify-token

{ "success": false, "errorNumber": 2, "error": "Invalid or expired token" }

اضافه کردن اسکریپ اصلی به وب سایت شما:

<script src="https://kingcaptcha.ir/captcha/script.js?publicKey=YOUR_PUBLIC_KEY"></script>

اضافه کردن اسکریپ کپچاکینگ به صفحه html و یا view سایت:

• در این تگ، میتوانید مقدار data-lang را روی fa یعنی فارسی و یا en یعنی انگلیسی قرار دهید.
• همچنین میتوانید با ست کردن مقدار data-bgcolor بصورت هگزادسیمال، رنگ کپچاکینگ را تغییر دهید.

<div class="KingCaptcha"
         id="mycaptchaId"
         data-lang="en">
</div>

فراخوانی کپچاکینگ:

• این دستور هم میتواند برای کپچاهای visible و هم invisible استفاده شود اما منطقا برای invisible طراحی شده است. در صورت استفاده از این دستور برای کپچاهای «ظاهر - visible»، کاربر شما مجبور به حل کردن پازل دوبار خواهد بود.
• پس از اتمام فرآیند کپچا، در صورت موفقیت آمیز بودن وارد بلاک می شویم. در این بلاک ارسال توکن تولید شده به سمت سرور جهت بررسی وجود خواهد داشت.

function launchCaptcha(mycaptchaId) {
    KingCaptcha.execute(mycaptchaId, () => {
        // وقتی که پازل حل شد
        // وارد این بلاک میشویم
        alert(mycaptchaId+ ": verfied");
    });
}

/*
// اگر از حالت await و async در کد جاوااسکریپ استفاده میکنید بصورت زیر فراخوانی ها را انجام دهید:
    KingCaptcha.execute(mycaptchaId, async () => {
    ...
    }
*/            

مثال تکمیلی:

فرض کنید که تابع login قرار است به سمت سرور مقادیر ورودی کاربر مانند ایمیل و پسورد را بفرستد.

function Login(mycaptchaId) {

    if (!validateLogin()) return;

    KingCaptcha.execute(mycaptchaId, () => {
        // وقتی که پازل حل شد
        // وارد این بلاک میشویم

        const token = KingCaptcha.getToken(mycaptchaId); // گرفتن توکن از پازل حل شده
        const publicKey = KingCaptcha.getPublicKey(mycaptchaId); // گرفتن کلیدعمومی از پازل حل شده
        if (!token || !publicKey) return;

        var postData = {
            'email': _email_,
            'Password': _password_,
            'Token': token,
            'PublicKey': publicKey,
        }
        $.ajax({
            contentType: 'application/x-www-form-urlencoded',
            dataType: 'json',
            type: 'POST',
            data: postData,
            url: '/api/your-method-to-check-user',
            success: function (result) {
                if (result.isSuccess) {
                    // redirect the user to dashboard
                }
                else {
                    // catch the error
                }
            },
            error(e) {
               // catch the error
            }
        })
    });
}
            

• mycaptchaId= آیدی ویجت کپچاکینگ هست که در چند کُد بالاتر در صفحه html خود قرار داده اید.
• if (!validateLogin()) return; = دستوری جهت بررسی مقادیر قبل از رسیدن به تابع است (اختیاری)
• KingCaptcha.execute(mycaptchaId, () => {...}= ابتدا صفحه کپچا را باز کرده و در صورت حل شدن درست، وارد بلاک زیرین میشود
• const token = KingCaptcha.getToken(mycaptchaId);= توکن تولید شده را براساس آیدی ویجت دریافت میکند
• const publicKey = KingCaptcha.getPublicKey(mycaptchaId);= کلید عمومی را براساس آیدی ویجت دریافت میکند. شما میتوانید بجای این دستور، بطور مستقیم کلیدعمومی را ارسال کنید
• postData= در این آبجکت، key و value ها جهت ارسال توسط ajax به سرور آماده سازی میشود که در بین آنها، token و publickey قرار خواهد گرفت

فراخوانی متد بررسی توکن توسط بک‌اند:

• این ajax متصل به بک‌اند شما بوده و باید سرویس آن توسط شما پیاده سازی شود. نمونه ی سی‌شارپ آن در قسمت بعدی قرار داده شده است.

function CheckToken(mycaptchaId) {
    const token = KingCaptcha.getToken(mycaptchaId);  // گرفتن توکن از پازل حل شده
    const publicKey = KingCaptcha.getPublicKey(mycaptchaId);  // گرفتن کلیدعمومی از پازل حل شده
    if (!token || !publicKey) {
        alert('Please solve the captcha first');
        return;
    }
    // Send token to backend
    $.ajax({
        contentType: 'application/x-www-form-urlencoded',
        dataType: 'json',
        type: 'POST',
        data: { captchaToken: token, publicKey: publicKey },
        url: '/home/checkToken',
        success: function (data) {
            if (data.success === false) {
                alert("Error: " + data.error);
            } else {
                alert("Verification successful");
            }
        },
        error: function (xhr) {
            var error = JSON.parse(xhr.responseText);
            alert("Error: " + (error.error || "Unknown error"));
        }
    });
}

بررسی صحت کپچا:

• با دستورات زیر که خاص کپچاهای مدل «ظاهر - visible» طراحی شده است شما پس از یا قبل از حل شدن پازل و سبز شدن دور کپچا می‌توانید از صحت حل شدن پازل مطمئن شود و سپس توکن را جهت بررسی به بک‌اند ارسال کنید. توجه فرمائید که در این حالت دیگر نیازی به استفاده از دستور KingCaptcha.execute(mycaptchaId, () => {...} نخواهد بود.

if (KingCaptcha.getToken(mycaptchaId) == null) { // بررسی میکند که آیا پازل حل شده است یا نه
    alert('ابتدا کپچا را حل کنید');
}
const token = KingCaptcha.getToken(mycaptchaId); // این توکن را به بک‌اند ارسال کنید.

فراخوانی خودکار:

• بجای فراخوانی دستی (کد قبل) میتوانید با دستورات زیر، پس از تکمیل شدن و حل پازل، توکن را بصورت خودکار بررسی و دستورات بعدی را اجرا کنید.
• این حالت مناسب حالیتی است که میخواهد از کپچاکینگ به عنوان trigger نهایی استفاده کنید.

    document.getElementById('mycaptchaId').addEventListener('captchaSuccess', (e) => {
    const token = e.detail.token;
    const publicKey = e.detail.publicKey;
    $.ajax({
        contentType: 'application/x-www-form-urlencoded',
        dataType: 'json',
        type: 'POST',
        data: { captchaToken: token, publicKey: publicKey },
        url: '/home/checkToken',
        success: function (data) {
            if (data.success === false) {
                alert("Error: " + data.error);
            } else {
                alert("Verification successful");
            }
        },
        error: function (xhr) {
            var error = JSON.parse(xhr.responseText);
            alert("Error: " + (error.error || "Unknown error"));
        }
    });
});

دستور بک‌اند سی شارپ جهت بررسی توکن

• نکته بسیار مهم: کلیک خصوصی (private-key) خود را بطور مستقیم و بصورت hardcode استفاده نکنید.

public class VerifyTokenResponse
{
    public bool   Success     { get; set; }
    public string Error       { get; set; }
    public int    ErrorNumber { get; set; }
}

[HttpPost]
public async Task<bool> CheckToken(string token)
{
    try
    {
        var payload = new
        {
        token      = token,              // گرفته شده توسط و یا ارسال شده آبجکتی توسط ajax خواهد بود. KingCaptcha.getToken()
            publicKey = "pub-xxxxxxxxxxxx",  // کلید عمومی شما - این کلید توسط ajax هم میتواند ارسال شود
            privateKey = "prv-xxxxxxxxxxxx" // کلید خصوصی شما - باید آن را در جایی امن مانند appsettings.json نگهداری کنید.
        };

        var client = _httpClientFactory.CreateClient();
        var json = JsonSerializer.Serialize(payload);
        var verifyUrl = $"https://kingcaptcha.ir/captcha/verify-token";

        var request = new HttpRequestMessage(HttpMethod.Post, verifyUrl)
        {
            Content = new StringContent(json, Encoding.UTF8, "application/json")
        };

        // Forward end-user's Origin so GetPureDomain() can resolve the domain
        var origin = Request.Headers["Origin"].FirstOrDefault();
        var referer = Request.Headers["Referer"].FirstOrDefault();
        if (!string.IsNullOrEmpty(origin))
            request.Headers.TryAddWithoutValidation("Origin", origin);
        else if (!string.IsNullOrEmpty(referer))
            request.Headers.TryAddWithoutValidation("Referer", referer);

        var response = await client.SendAsync(request);
        if (!response.IsSuccessStatusCode) return false;

        var result = await response.Content.ReadFromJsonAsync<VerifyTokenResponse>();
        return result is { Success: true };
    }
    catch (Exception ex) { }
    return false;
}

دستور بک‌اند ویژال بیسیک جهت بررسی توکن

• نکته بسیار مهم: کلیک خصوصی (private-key) خود را بطور مستقیم و بصورت hardcode استفاده نکنید.

Imports System.Net.Http
Imports System.Net.Http.Json
Imports System.Text
Imports System.Text.Json
Imports Microsoft.AspNetCore.Mvc

Public Class VerifyTokenResponse
    Public Property Success As Boolean
    Public Property Error As String
    Public Property ErrorNumber As Integer
End Class

<ApiController>
Public Class CaptchaController
    Inherits ControllerBase

    Private ReadOnly _httpClientFactory As IHttpClientFactory

    Public Sub New(httpClientFactory As IHttpClientFactory)
        _httpClientFactory = httpClientFactory
    End Sub

    <HttpPost>
    Public Async Function SubmitForm(<FromForm> token As String) As Task(Of IActionResult)
        Using client = _httpClientFactory.CreateClient()
            ' Build the JSON payload
            Dim payload = New With {
                .token = token,
                .publicKey = "pub-xxxxxxxxxxxx",
                .privateKey = "prv-xxxxxxxxxxxx"
            }

            Dim json = JsonSerializer.Serialize(payload)
            Dim content = New StringContent(json, Encoding.UTF8, "application/json")

            Dim request = New HttpRequestMessage(HttpMethod.Post,
                "https://kingcaptcha.ir/captcha/verify-token") With {
                .Content = content
            }

            ' Add the Origin header (same as the requesting host)
            request.Headers.TryAddWithoutValidation("Origin",
                $"{Request.Scheme}://{Request.Host}")

            Dim response = Await client.SendAsync(request)

            ' If the API call failed
            If Not response.IsSuccessStatusCode Then
                Return BadRequest("Captcha verification failed")
            End If

            ' Deserialize the response
            Dim result = Await response.Content.ReadFromJsonAsync(Of VerifyTokenResponse)()

            ' Check if verification succeeded
            If result Is Nothing OrElse Not result.Success Then
                Dim errorMessage = If(result Is Nothing, "Invalid token", result.Error)
                Return BadRequest(errorMessage)
            End If

            ' Captcha is valid – proceed with the rest of your logic
            Return Ok()
        End Using
    End Function
End Class

دستور بک‌اند php جهت بررسی توکن

• نکته بسیار مهم: کلیک خصوصی (private-key) خود را بطور مستقیم و بصورت hardcode استفاده نکنید.

$captchaToken = $_POST['captcha_token'];

$payload = json_encode([
    'token'      => $captchaToken,
    'publicKey'  => 'pub-xxxxxxxxxxxx',
    'privateKey' => 'prv-xxxxxxxxxxxx'
]);

$ch = curl_init('https://kingcaptcha.ir/captcha/verify-token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Origin: https://' . $_SERVER['HTTP_HOST']
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result   = json_decode($response);

if ($result->success) {
    // ✅ captcha passed
} else {
    // ❌ failed: $result->error
}

دستور بک‌اند پایتون جهت بررسی توکن

• نکته بسیار مهم: کلیک خصوصی (private-key) خود را بطور مستقیم و بصورت hardcode استفاده نکنید.

from fastapi import FastAPI, Form, HTTPException
from pydantic import BaseModel
import httpx
import os

app = FastAPI()

# Configuration (store private key securely, e.g., in environment variables)
PUBLIC_KEY = "pub-xxxxxxxxxxxx"
PRIVATE_KEY = os.getenv("CAPTCHA_PRIVATE_KEY", "prv-xxxxxxxxxxxx")
VERIFY_URL = "https://kingcaptcha.ir/captcha/verify-token"


class VerifyTokenResponse(BaseModel):
    success: bool
    error: str | None = None
    error_number: int | None = None


@app.post("/ submit & quot;)
async def submit_form(token: str = Form(...)):
    """
    Endpoint that receives a captcha token via form data,
    validates it with KingCaptcha, and returns appropriate response.
    """
    # Build the JSON payload
    payload = {
        "token": token,
        "publicKey": PUBLIC_KEY,
        "privateKey": PRIVATE_KEY,
    }

    # Prepare headers and request
    headers = {
        "Content-Type": "application/json",
        "Origin": f"{request.url.scheme}://{request.url.netloc}",  # Dynamically set Origin
    }

    async with httpx.AsyncClient() as client:
        try:
            response = await client.post(
                VERIFY_URL,
                json=payload,
                headers=headers,
                timeout=10.0  # optional timeout
            )
            response.raise_for_status()  # raise if status >= 400
        except httpx.HTTPStatusError as e:
            raise HTTPException(status_code=400, detail="Captcha verification failed")
        except httpx.RequestError as e:
            raise HTTPException(status_code=500, detail="Unable to reach captcha service")

        # Deserialize response
        try:
            result = VerifyTokenResponse(**response.json())
        except Exception:
            raise HTTPException(status_code=400, detail="Invalid response from captcha service")

        # Check success flag
        if not result.success:
            error_msg = result.error or "Invalid token"
            raise HTTPException(status_code=400, detail=error_msg)

        # Captcha is valid – proceed
        return {"status": "ok", "message": "Captcha verified successfully"}