Scarnox · Blog

API solver captcha: cara kerjanya dan cara memanggilnya

API solver captcha adalah layanan web yang Anda panggil lewat HTTP. Anda mengirim detail captcha, yaitu tipe task, sitekey halaman, dan URL halaman, lalu ia mengembalikan token yang diterima situs sebagai bukti bahwa tantangannya sudah dilewati. Endpoint Scarnox bekerja seperti ini dan bersifat sinkron, jadi satu request memberi Anda jawabannya.

Panduan ini membahas request, respons, bentuk error, dan detail yang menentukan apakah sebuah integrasi tahan di produksi. Jika Anda ingin script yang bisa langsung dijalankan terlebih dahulu, mulailah dengan cara solve PopularCaptcha dengan Python.

Apa yang dilakukan API dan apa yang tidak

Kode Anda menemukan captcha di halaman, membaca sitekey-nya, dan mengirimkannya ke solver. Solver mengembalikan token. Kode Anda menulis token itu ke field form yang diharapkan situs dan mengirim form.

Solver tidak memuat halaman Anda, tidak mengklik apa pun, dan tidak mengirim form Anda. Ia hanya menghasilkan token. Menjaga batas ini dalam pikiran membuat sisa integrasi lebih mudah dipahami: semua yang berkaitan dengan sesi, cookie, dan waktu request tetap berada di kode Anda.

Saat ini satu-satunya tipe task yang live adalah PopularCaptcha, proxyless, yaitu PopularCaptchaTaskProxyless. Tipe captcha lain ada dalam roadmap. Panduan jenis-jenis captcha menjelaskan mana yang mana.

Endpoint

Kirim request POST ke:

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

Body menjelaskan task-nya:

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

Tiga field wajib adalah:

captcha_type: tipe task. Untuk solve live saat ini nilainya PopularCaptchaTaskProxyless.
site_key: sitekey yang dibaca dari halaman. Sitekey PopularCaptcha berupa UUID.
site_url: URL halaman tempat captcha muncul. Gunakan halaman yang sebenarnya, bukan halaman utama, karena token terikat pada halaman yang menampilkan widget.

Ada tiga field opsional. proxy menerima nilai dengan format http://user:pass@host:port dan dipakai dengan tipe task proxy. rqdata dan is_invisible dipakai untuk varian widget tertentu. Daftar lengkap tipe task dan detail field ada di referensi API.

Sinkron berarti tanpa polling

Panggilan akan memblokir sampai token siap. Anda tidak perlu polling, dan tidak ada request "ambil hasil" kedua dalam alur ini. Atur timeout HTTP client Anda sekitar 185 detik agar solve yang lambat tidak dianggap sebagai kegagalan jaringan.

Dengan library requests di Python, bentuknya seperti ini:

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()

Baca key dari environment variable, jangan menuliskannya langsung ke script. Siapa pun yang bisa membaca source tidak seharusnya bisa memakai saldo Anda.

Membaca respons

Solve yang berhasil mengembalikan errorId bernilai 0, token di dalam solution, dan field cost:

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

Solve yang gagal mengembalikan errorId selain 0, ditambah errorCode yang bisa dibaca mesin dan errorDescription yang bisa dibaca manusia:

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

Periksa errorId di body pada setiap panggilan. Jangan berasumsi bahwa request HTTP yang selesai berarti Anda sudah mendapat token. Aturan yang paling penting: Anda hanya ditagih saat errorId bernilai 0. Solve yang gagal tidak dikenai biaya. Untuk tarif terkini, lihat halaman harga.

Masa berlaku token

Token PopularCaptcha kedaluwarsa dalam sekitar dua menit. Kirimkan token segera setelah Anda menerimanya. Jangan menyimpan token untuk dipakai nanti, dan jangan melakukan solve jauh sebelum form dikirim. Jika kode Anda menjalankan beberapa langkah di antara mendapatkan token dan mengirim form, pindahkan solve ke saat-saat terakhir.

Memasukkan token ke form

Kebanyakan situs membaca respons PopularCaptcha dari field form bernama h-captcha-response. Banyak juga yang menerima g-recaptcha-response dengan nilai yang sama, jadi mengirim keduanya adalah pilihan aman yang umum:

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

Jika form tidak menerima token, penyebabnya biasanya adalah sitekey atau URL halaman yang tidak cocok dengan halaman tempat widget sebenarnya berada. Periksa kembali nilainya sebelum menyalahkan solver.

Penanganan error

Integrasi produksi membutuhkan beberapa kebiasaan:

Periksa errorId dan catat errorCode setiap kali. Kode itulah yang pertama kali akan ditanyakan tim support.
Coba ulang solve yang gagal dengan backoff kecil. Karena solve yang gagal tidak dikenai biaya, retry tidak memakan solve, tetapi loop yang ketat tetap membuang waktu dan bisa menyentuh rate limit Anda sendiri.
Atur timeout client sekitar 185 detik, dan perlakukan timeout sebagai error yang perlu di-retry, bukan sebagai keberhasilan.
Jaga token dan pengiriman form tetap berdekatan dalam waktu, karena token cepat kedaluwarsa.

Panduan retry dan penanganan error membahas masing-masing lebih dalam.

Memulai

Buat akun dan Anda bisa mulai dengan kredit uji coba gratis, tanpa kartu. Lalu jalankan request di atas terhadap halaman uji yang Anda kontrol, dan pastikan form menerima token sebelum Anda menghubungkannya ke hal yang penting.