Google Apps Script + CaptchaAI: Otomatisasi CAPTCHA di Spreadsheet

Kalau tim Anda memakai Google Sheets sebagai database ringan — menampung URL gambar CAPTCHA dari form pendaftaran atau sumber data eksternal — menyalin tiap gambar ke situs solver lalu menempel hasilnya ke sel adalah kerja manual yang sebenarnya bisa dihilangkan. Google Apps Script menyediakan UrlFetchApp, yang memanggil API CaptchaAI langsung dari spreadsheet — image CAPTCHA, challenge OCR, dan CAPTCHA berbasis teks terselesaikan otomatis tanpa server tambahan.

Panduan ini membangun dua custom function — SOLVE_CAPTCHA() untuk URL gambar, SOLVE_CAPTCHA_BASE64() untuk sel berisi base64 — ditambah menu batch untuk satu kolom penuh sekaligus.

Kapan Pola Ini Masuk Akal

Bayangkan sheet Anda berisi ratusan baris URL gambar CAPTCHA hasil scraping form atau verifikasi dokumen. Alur manualnya: buka gambar satu per satu, baca teksnya, ketik ke kolom hasil. Untuk 20 baris masih wajar; untuk 500 baris itu jadi pekerjaan penuh waktu.

Function Apps Script di bawah menggantikan proses itu dengan empat langkah otomatis:

1. Ambil setiap gambar CAPTCHA dari URL-nya
2. Ubah ke base64
3. Kirim ke CaptchaAI
4. Tulis hasil solve langsung ke sel spreadsheet

Ini pola yang umum dipakai tim data kecil dan freelancer yang mengerjakan proyek client lewat Upwork atau Fastwork — Google Sheets sudah jadi database dan dashboard sekaligus, jadi solver yang dipanggil langsung dari formula lebih praktis daripada membangun endpoint terpisah. Kalau sumber gambar berasal dari data pihak ketiga, pastikan Anda punya otorisasi memprosesnya sesuai UU Pelindungan Data Pribadi (UU 27/2022).

Paket CaptchaAI yang Cocok untuk Volume Spreadsheet Anda

CaptchaAI menagih per thread, bukan per solve — yang menentukan biaya bulanan Anda bukan jumlah baris di sheet, melainkan berapa banyak solve yang berjalan bersamaan:

• BASIC ($15/bulan, 5 thread) — cukup untuk sheet pribadi atau proyek kecil yang menjalankan menu batch sesekali; custom function di sel diproses satu per satu, jadi kebutuhan thread-nya rendah.
• STANDARD ($30/bulan, 15 thread) atau ADVANCE ($90/bulan, 50 thread) — lebih masuk akal kalau Anda menjalankan trigger terjadwal di beberapa spreadsheet client sekaligus, pola yang umum di kalangan freelancer data Upwork atau Fastwork.

Semua paket di atas memberi solve tanpa batas per thread selama masa berlangganan, tanpa biaya tambahan per jenis CAPTCHA — cek detail paket terbaru di captchaai.com sebelum memilih.

Dengan paket sudah jelas, langkah selanjutnya adalah membangun scriptnya.

Langkah 1: Buat Project Apps Script di Google Sheets

Di Google Spreadsheet Anda, buka menu Extensions → Apps Script, lalu buat file script baru dan beri nama captchaai.gs. Project ini akan menampung dua custom function dan satu menu batch yang dibangun di langkah-langkah berikutnya.

Langkah 2: Tulis Function Solver CaptchaAI

Tempel kode berikut ke captchaai.gs: getApiKey() membaca API key dari Script Properties, SOLVE_CAPTCHA()/SOLVE_CAPTCHA_BASE64() adalah custom function yang dipanggil dari sel, dan submitCaptcha()/pollForResult() menjalankan alur kirim-lalu-polling ke CaptchaAI:

// captchaai.gs

// Store your API key in Script Properties for security
// File → Project Properties → Script Properties → Add: CAPTCHAAI_KEY
function getApiKey() {
  return PropertiesService.getScriptProperties().getProperty('CAPTCHAAI_KEY');
}

/**

 * Solve an image CAPTCHA from a URL.
 * @param {string} imageUrl URL of the CAPTCHA image to solve.
 * @return {string} The solved CAPTCHA text.
 * @customfunction
 */
function SOLVE_CAPTCHA(imageUrl) {
  if (!imageUrl) return 'No URL provided';

  try {
    // Fetch the image and convert to base64
    var imageResponse = UrlFetchApp.fetch(imageUrl);
    var imageBlob = imageResponse.getBlob();
    var base64Image = Utilities.base64Encode(imageBlob.getBytes());

    // Submit to CaptchaAI
    var taskId = submitCaptcha(base64Image);
    if (!taskId) return 'Submit failed';

    // Poll for result
    var result = pollForResult(taskId);
    return result || 'Solve failed';
  } catch (e) {
    return 'Error: ' + e.message;
  }
}

/**

 * Solve an image CAPTCHA from base64 text in a cell.
 * @param {string} base64Image Base64-encoded CAPTCHA image.
 * @return {string} The solved CAPTCHA text.
 * @customfunction
 */
function SOLVE_CAPTCHA_BASE64(base64Image) {
  if (!base64Image) return 'No image data';

  try {
    var taskId = submitCaptcha(base64Image);
    if (!taskId) return 'Submit failed';

    var result = pollForResult(taskId);
    return result || 'Solve failed';
  } catch (e) {
    return 'Error: ' + e.message;
  }
}

function submitCaptcha(base64Image) {
  var apiKey = getApiKey();

  var payload = {
    'key': apiKey,
    'method': 'base64',
    'body': base64Image,
    'json': '1'
  };

  var options = {
    'method': 'post',
    'payload': payload,
    'muteHttpExceptions': true
  };

  var response = UrlFetchApp.fetch(
    'https://ocr.captchaai.com/in.php', options
  );
  var result = JSON.parse(response.getContentText());

  if (result.status === 1) {
    return result.request;
  }

  Logger.log('Submit error: ' + result.request);
  return null;
}

function pollForResult(taskId) {
  var apiKey = getApiKey();
  var maxAttempts = 20;

  // Initial wait
  Utilities.sleep(5000);

  for (var i = 0; i < maxAttempts; i++) {
    var url = 'https://ocr.captchaai.com/res.php'
      + '?key=' + apiKey
      + '&action=get'
      + '&id=' + taskId
      + '&json=1';

    var response = UrlFetchApp.fetch(url, {muteHttpExceptions: true});
    var result = JSON.parse(response.getContentText());

    if (result.status === 1) {
      return result.request;
    }

    if (result.request !== 'CAPCHA_NOT_READY') {
      Logger.log('Solve error: ' + result.request);
      return null;
    }

    Utilities.sleep(5000);
  }

  return null; // Timeout
}

Langkah 3: Simpan API Key dengan Aman di Script Properties

Jangan hardcode API key di dalam script — simpan di Script Properties supaya tidak ikut ter-commit kalau project ini dibagikan ke rekan tim. Di editor Apps Script, klik Project Settings (ikon gear), lalu scroll ke bagian Script Properties, klik Add script property, isi Property dengan CAPTCHAAI_KEY dan Value dengan API key CaptchaAI Anda, lalu simpan. Function getApiKey() di Langkah 2 membaca nilai ini setiap kali dipanggil — tidak ada API key yang tersimpan di sel atau di kode .gs itu sendiri.

Langkah 4: Panggil Solver dari Sel Spreadsheet

Dua cara memanggil function di atas, tergantung volume CAPTCHA yang diproses:

Formula Langsung di Sel

Di sel mana pun, gunakan formula:

=SOLVE_CAPTCHA("https://example.com/captcha-image.jpg")

Atau untuk data base64 yang sudah ada di dalam sel:

=SOLVE_CAPTCHA_BASE64(A2)

Solve Satu Kolom Penuh via Menu Custom

Untuk memproses banyak CAPTCHA sekaligus, tambahkan custom menu yang mengolah satu kolom penuh URL gambar:

function onOpen() {
  SpreadsheetApp.getUi().createMenu('CaptchaAI')
    .addItem('Solve Column A CAPTCHAs', 'solveColumnCaptchas')
    .addItem('Check Balance', 'checkBalance')
    .addToUi();
}

function solveColumnCaptchas() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var lastRow = sheet.getLastRow();
  var urls = sheet.getRange('A2:A' + lastRow).getValues();

  for (var i = 0; i < urls.length; i++) {
    if (!urls[i][0]) continue;

    var row = i + 2;
    var existingResult = sheet.getRange('B' + row).getValue();
    if (existingResult) continue; // Skip already solved

    sheet.getRange('B' + row).setValue('Solving...');
    SpreadsheetApp.flush();

    var result = SOLVE_CAPTCHA(urls[i][0]);
    sheet.getRange('B' + row).setValue(result);
    sheet.getRange('C' + row).setValue(new Date()); // Timestamp

    // Avoid hitting Apps Script quotas
    Utilities.sleep(1000);
  }

  SpreadsheetApp.getUi().alert('Batch solving complete!');
}

function checkBalance() {
  var apiKey = getApiKey();
  var url = 'https://ocr.captchaai.com/res.php'
    + '?key=' + apiKey
    + '&action=getbalance'
    + '&json=1';

  var response = UrlFetchApp.fetch(url);
  var result = JSON.parse(response.getContentText());

  SpreadsheetApp.getUi().alert(
    'CaptchaAI Balance: $' + result.request
  );
}

Langkah 5: Baca Hasilnya di Spreadsheet

Kolom B menyimpan teks hasil solve, Kolom C mencatat waktunya. Begini isinya setelah solveColumnCaptchas selesai memproses tiga baris pertama:

• https://example.com/captcha1.jpg → Kolom B: ABC123, Kolom C: 04-04-2026 10:15:00
• https://example.com/captcha2.jpg → Kolom B: XYZ789, Kolom C: 04-04-2026 10:15:12
• https://example.com/captcha3.jpg → Kolom B: Solving... (baris ini masih diproses, Kolom C masih kosong)

Pertanyaan Umum

Berapa lama Apps Script bisa menjalankan proses solve sebelum timeout?

Custom function di dalam sel dibatasi 30 detik — cukup ketat untuk image CAPTCHA yang butuh beberapa kali polling. Fungsi yang dipicu dari menu custom (solveColumnCaptchas) punya limit 6 menit, dan time-based trigger punya limit yang sama (30 menit khusus akun Google Workspace). Untuk batch besar, selalu pakai jalur menu atau trigger, bukan formula langsung di sel.

Apakah script yang sama bisa dipakai untuk reCAPTCHA v2, bukan cuma image CAPTCHA?

Bisa, tapi payload-nya beda dari yang dipakai submitCaptcha di atas:

• method diganti dari base64 ke userrecaptcha
• googlekey (sitekey halaman) menggantikan data gambar
• pageurl ditambahkan sebagai parameter baru

Endpoint in.php dan res.php tetap sama persis.

Paket CaptchaAI mana yang cocok kalau saya cuma solve puluhan CAPTCHA sehari dari satu sheet?

BASIC ($15/bulan, 5 thread) biasanya lebih dari cukup — custom function memproses satu sel per waktu, jadi kebutuhan thread-nya rendah kecuali Anda menjalankan beberapa trigger paralel di banyak spreadsheet sekaligus.

Kenapa hasil OCR kadang meleset walau statusnya "solved"?

CaptchaAI mengembalikan teks yang menurut model paling mendekati gambar aslinya. Penyebab hasil paling sering meleset:

• Gambar buram atau kompresi terlalu berat
• Resolusi rendah setelah di-fetch ulang oleh UrlFetchApp
• Watermark atau noise yang menutupi sebagian karakter

Simpan URL gambar asli di Kolom A, supaya Anda bisa memeriksa ulang baris yang hasilnya mencurigakan tanpa menjalankan ulang seluruh batch.

Amankah menyimpan API key CaptchaAI langsung di sel Google Sheet yang dipakai bersama tim?

Jangan taruh API key di sel spreadsheet — siapa pun dengan akses edit bisa membacanya. Script Properties (Langkah 3) menyimpan key di level project, terpisah dari isi sheet, dan tetap bisa dipakai semua collaborator tanpa terlihat di tampilan spreadsheet.

Kalau Muncul Error

Error yang paling sering muncul saat menyambungkan Apps Script ke CaptchaAI, dan cara memperbaikinya:

• TypeError: Cannot read property 'getProperty' — Script Properties belum disetel. Tambahkan CAPTCHAAI_KEY di Project Settings.
• Exception: Address unavailable — URL gambar diblokir atau tidak valid. Pastikan URL gambar dapat diakses dari server Google.
• Custom function mengembalikan Loading... selamanya — timeout eksekusi Apps Script (30 detik untuk custom function). Gunakan pendekatan menu batch, karena menu function punya limit 6 menit.
• ERROR_ZERO_BALANCE — akun tidak memiliki kredit. Top up saldo CaptchaAI Anda.
• Kuota UrlFetchApp terlampaui — terlalu banyak API call dalam sehari. Tambahkan Utilities.sleep() antar panggilan dan proses dalam batch yang lebih kecil.
• Batch berjalan lambat atau macet di tengah — trigger paralel lebih banyak dari jumlah thread pada paket Anda. Naikkan paket (lihat bagian paket di atas) atau kurangi jumlah trigger yang berjalan bersamaan.

Sambungkan CaptchaAI ke Spreadsheet Anda

Sambungkan CaptchaAI ke Apps Script Anda — dapatkan API key CaptchaAI Anda dan tempel dua function di atas ke project baru dalam beberapa menit.

• Batch Image CAPTCHA Solving: Memproses 1.000 Gambar
• Otomatisasi CaptchaAI lewat Make (Integromat)