reCAPTCHA Enterprise: site key và API key khác nhau thế nào

Nếu task Enterprise đầu tiên trả về ERROR_WRONG_CAPTCHA_ID, gần như chắc chắn bạn đã dán nhầm key. CaptchaAI chỉ cần site key — chuỗi 6L... nằm công khai trong HTML. Còn API key dạng AIzaSy... là khóa riêng của backend, chỉ dùng để hỏi Google xem token có hợp lệ hay không.

• Gửi tới CaptchaAI: site key (6L...), pageurl và enterprise=1
• Không bao giờ gửi: API key AIzaSy... của Google Cloud

Bài viết dành cho dev tích hợp reCAPTCHA Enterprise vào luồng QA hoặc pipeline thu thập dữ liệu web (scraping): nhận diện hai key và gửi task đúng ngay lần đầu.

Site key: khóa công khai nằm ngay trong HTML

Site key quyết định trang sẽ tải cấu hình reCAPTCHA nào. Nó nằm ngay trong thẻ script:

<script src="https://www.google.com/recaptcha/enterprise.js?render=6LcR_RsTAAAAADge..."></script>

Hoặc trong lời gọi grecaptcha.enterprise.execute:

grecaptcha.enterprise.execute('6LcR_RsTAAAAADge...', { action: 'login' });

Nhận biết nhanh: chuỗi bắt đầu bằng 6L (giống reCAPTCHA tiêu chuẩn), nằm lộ thiên trong mã nguồn trang và chỉ chạy trên những domain đã khai báo trong Google Cloud Console.

API key: khóa riêng chỉ backend được giữ

API key xác thực cuộc gọi từ máy chủ trang web tới Google trong bước xác minh token:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=AIzaSy...

Nhận biết nhanh: chuỗi bắt đầu bằng AIzaSy theo định dạng Google Cloud, chỉ nằm trong biến môi trường hoặc cấu hình server. Thấy nó trong page source của trang mục tiêu là lỗi cấu hình phía họ, không phải key bạn cần.

Bảng so sánh nhanh hai key

Năm dòng dưới đây đủ để phân loại nhanh:

Vì sao chỉ site key ảnh hưởng tới việc giải

Luồng xác minh Enterprise đầy đủ gồm năm bước:

1. Trình duyệt tải enterprise.js bằng site key
2. Trình duyệt chạy thử thách và nhận token
3. Backend trang web gửi token kèm API key tới assessments
4. Google trả về điểm rủi ro và lý do
5. Backend chấp nhận hay từ chối request theo điểm đó

CaptchaAI thay thế bước 1 và 2: dùng site key tạo token hợp lệ rồi trả về cho bạn. Ba bước còn lại do trang web tự làm. Hệ quả khi vận hành:

• Trang web luân chuyển API key của họ: không ảnh hưởng tới bạn
• Trang web đổi site key hoặc thêm domain: bạn phải lấy lại site key
• Token bị từ chối dù giải xong: xem lại action, domain hoặc ngưỡng điểm

Ví dụ: đội QA outsourcing ở TP.HCM kiểm thử luồng đăng nhập

Đội QA làm dự án cho khách hàng nước ngoài thường chạy cùng bộ test trên hai môi trường: staging nội bộ và production của khách. Site key hai bên khác nhau vì mỗi môi trường đăng ký domain riêng. Kịch bản hay gặp:

• Kỹ sư copy site key từ tài liệu bàn giao (viết cho production)
• Chạy test trên staging.example.com/qa-login, task vẫn trả token
• Backend staging từ chối token vì domain không khớp

Cách xử lý: trích xuất site key trực tiếp từ URL đang test, lưu tách theo môi trường (SITE_KEY_STAGING, SITE_KEY_PROD) và ghi log key dùng cho mỗi lần chạy — log này cũng hữu ích khi rà soát tối thiểu hóa dữ liệu theo Nghị định 13/2023/NĐ-CP.

Cách lấy site key từ trang mục tiêu

Ba cách, theo thứ tự nên thử:

Cách 1: tìm trong page source

Mở mã nguồn trang rồi tìm enterprise.js:

View Source → Ctrl+F → "enterprise.js"

Site key nằm trong tham số render của URL script:

<script src="https://www.google.com/recaptcha/enterprise.js?render=6LcR_RsTAAAAADge..."></script>

Nếu render trống, trang đang render widget kiểu v2 và key nằm ở thuộc tính data-sitekey.

Cách 2: dùng JavaScript console

Đoạn dưới đây xác nhận trang có chạy Enterprise và liệt kê site key đang render:

// Check for Enterprise grecaptcha
if (window.grecaptcha && window.grecaptcha.enterprise) {
  console.log('reCAPTCHA Enterprise detected');
}

// Find site key from rendered widgets
document.querySelectorAll('[data-sitekey]').forEach(el => {
  console.log('Site key:', el.getAttribute('data-sitekey'));
});

Chuỗi in ra console là giá trị bạn copy vào googlekey.

Cách 3: xem tab Network

Lọc request theo enterprise.js hoặc recaptcha/enterprise. Cách này hữu ích khi:

• Widget được chèn động sau thao tác của người dùng
• Trang dùng nhiều site key cho nhiều biểu mẫu
• Bạn cần biết chính xác pageurl trình duyệt gửi kèm

Gửi task Enterprise tới CaptchaAI

Việc còn lại chỉ là một request POST:

POST https://ocr.captchaai.com/in.php

Tham số bắt buộc:

Hai tham số tùy chọn:

• enterprise_type — chỉ định v2 hay v3 Enterprise
• action — tên action, cần khai báo khi trang dùng v3 Enterprise

Sau đó polling res.php, nhận g-recaptcha-response rồi đặt token vào biểu mẫu QA.

reCAPTCHA Enterprise khác bản tiêu chuẩn ở đâu

Hai bản dùng chung tiền tố key; khác biệt nằm ở nơi cấp key và cách xác minh:

Cả hai đều gửi lên CaptchaAI với method=userrecaptcha; cờ enterprise=1 mới là thứ phân biệt.

Lỗi thường gặp khi nhầm hai key

Trước khi mở ticket hỗ trợ, kiểm tra ba điểm:

• Site key trong request có trùng chuỗi trong page source không
• pageurl có đúng scheme và domain đang chạy thử thách không
• Tài khoản còn thread trống để nhận task mới không

Câu hỏi thường gặp

Site key reCAPTCHA Enterprise có phải thông tin bí mật không?

Không. Site key được thiết kế để công khai và chỉ hoạt động trên domain đã đăng ký. Thứ cần giữ kín là API key AIzaSy... của backend và API key CaptchaAI của bạn.

Làm sao biết trang dùng Enterprise hay reCAPTCHA v2 thường?

Nhìn URL script: Enterprise tải từ /recaptcha/enterprise.js, bản tiêu chuẩn dùng /recaptcha/api.js. Trong JavaScript, Enterprise gọi grecaptcha.enterprise.execute() thay vì grecaptcha.execute().

Quên enterprise=1 thì chuyện gì xảy ra?

Task được xử lý như reCAPTCHA tiêu chuẩn và token thường bị từ chối ở bước assessments. Thêm enterprise=1 — kèm enterprise_type nếu trang dùng v3 — rồi gửi lại.

Giải Enterprise có tốn hơn reCAPTCHA v2 không?

Không. CaptchaAI tính tiền theo thread (số CAPTCHA giải đồng thời), không tính theo lần giải và không phụ thu theo loại CAPTCHA. Gói nhỏ nhất là BASIC ($15/tháng, 5 thread), task Enterprise dùng chung hạn mức thread đó.

Bài viết liên quan

• giải reCAPTCHA v2 dạng callback bằng API
• whitelist IP và bảo mật API key CaptchaAI
• luân chuyển API key CaptchaAI định kỳ

Bước tiếp theo

Lấy site key từ trang bạn đang kiểm thử, lấy API key CaptchaAI rồi gửi task đầu tiên kèm enterprise=1. Nếu backend chấp nhận token trả về, phần cấu hình còn lại đã đúng.