Scarnox · Blog

API bộ giải captcha: cách hoạt động và cách gọi

API bộ giải captcha là một dịch vụ web mà bạn gọi qua HTTP. Bạn gửi cho nó thông tin của một captcha, gồm loại tác vụ, sitekey của trang và URL trang, và nó trả về một token mà website chấp nhận như bằng chứng rằng thử thách đã được vượt qua. Endpoint của Scarnox hoạt động theo cách này và là đồng bộ, nên một yêu cầu cho bạn câu trả lời ngay.

Hướng dẫn này bao quát yêu cầu, phản hồi, cấu trúc lỗi và các chi tiết quyết định việc một tích hợp có đứng vững trên production hay không. Nếu bạn muốn một script chạy được trước, hãy bắt đầu với Cách giải PopularCaptcha bằng Python.

API làm gì và không làm gì

Mã của bạn tìm captcha trên một trang, đọc sitekey của nó và gửi cho bộ giải. Bộ giải trả về một token. Mã của bạn ghi token đó vào trường form mà website mong đợi và submit form.

Bộ giải không tải trang của bạn, không click vào đâu và không submit form của bạn. Nó chỉ tạo ra token. Ghi nhớ ranh giới này giúp mọi thứ còn lại của tích hợp dễ hiểu hơn: mọi thứ liên quan đến phiên, cookie và thời gian yêu cầu đều nằm trong mã của bạn.

Hiện tại loại tác vụ duy nhất đang chạy là PopularCaptcha, proxyless, tức PopularCaptchaTaskProxyless. Các loại captcha khác đang trong lộ trình phát triển. Hướng dẫn các loại captcha liệt kê loại nào là loại nào.

Endpoint

Gửi một yêu cầu POST đến:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

Thân yêu cầu mô tả tác vụ:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

Ba trường bắt buộc là:

Có ba trường tùy chọn. proxy nhận giá trị có dạng http://user:pass@host:port và được dùng với các loại tác vụ proxy. rqdata và is_invisible dành cho các biến thể widget cụ thể. Danh sách đầy đủ các loại tác vụ và chi tiết trường nằm trong tài liệu API.

Đồng bộ nghĩa là không cần polling

Lời gọi bị chặn cho đến khi token sẵn sàng. Bạn không cần polling, và trong luồng này không có yêu cầu "lấy kết quả" thứ hai. Đặt thời gian chờ của HTTP client khoảng 185 giây để một lần giải chậm không bị nhầm thành lỗi mạng.

Trong Python với thư viện requests, điều đó trông như sau:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Đọc khóa từ biến môi trường thay vì ghi nó vào script. Ai đọc được mã nguồn cũng không nên có thể dùng số dư của bạn.

Đọc phản hồi

Một lần giải thành công trả về errorId là 0, token nằm trong solution và một trường cost:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Một lần giải thất bại trả về errorId khác 0, cùng với errorCode dạng máy đọc được và errorDescription dạng người đọc được:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Kiểm tra errorId trong thân phản hồi ở mọi lần gọi. Đừng cho rằng một yêu cầu HTTP đã hoàn thành nghĩa là bạn có token. Quy tắc quan trọng nhất là: bạn chỉ bị tính phí khi errorId là 0. Các lần giải thất bại không bị tính phí. Để biết mức giá hiện tại, xem trang bảng giá.

Thời hạn của token

Token PopularCaptcha hết hạn trong khoảng hai phút. Hãy submit token ngay khi nhận được. Đừng lưu token để dùng sau, và đừng giải trước khi submit form. Nếu mã của bạn thực hiện nhiều bước giữa lúc nhận token và lúc gửi form, hãy chuyển việc giải xuống thời điểm cuối cùng.

Đưa token vào form

Hầu hết website đọc phản hồi PopularCaptcha từ trường form tên h-captcha-response. Nhiều website cũng chấp nhận g-recaptcha-response với cùng giá trị, nên gửi cả hai là một lựa chọn an toàn phổ biến:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Nếu form không chấp nhận token, nguyên nhân thường là sitekey hoặc URL trang không khớp với trang mà widget thực sự nằm trên đó. Kiểm tra lại các giá trị trước khi đổ lỗi cho bộ giải.

Xử lý lỗi

Một tích hợp production cần một danh sách ngắn các thói quen:

Hướng dẫn xử lý lỗi và thử lại đi sâu hơn vào từng điểm này.

Bắt đầu

Tạo tài khoản và bạn có thể bắt đầu với tín dụng dùng thử miễn phí, không cần thẻ. Sau đó chạy yêu cầu ở trên trên một trang thử nghiệm mà bạn kiểm soát, và kiểm tra form có chấp nhận token trước khi nối nó vào bất cứ thứ gì quan trọng.

Các bước tiếp theo