إعداد مفتاح CaptchaAI API والمصادقة

مفتاح واحد يفتح كامل واجهة CaptchaAI API: به تُرسل اختبارات CAPTCHA للحل، وتستطلع نتيجتها، وتتحقق من رصيدك — من دون توقيعات طلب إضافية أو رموز OAuth أو أسرار منفصلة لكل نقطة نهاية. هذا يجعل البدء سريعاً، لكنه يعني أيضاً أنّ حماية المفتاح مسؤوليتك وحدك، تماماً كما تحمي كلمة مرور قاعدة البيانات. في السطور التالية تحصل على المفتاح، ثم تتعلّم كيف تُرفقه بكل طلب، وتتحقق من صحته قبل كتابة أي كود، وتؤمّنه في بيئتي التطوير والإنتاج.

الحصول على مفتاح CaptchaAI API

للانطلاق تحتاج حساباً ومفتاحاً ورصيداً أولياً:

1. أنشئ حساباً على captchaai.com.
2. سجّل الدخول إلى لوحة التحكم.
3. انتقل إلى إعدادات API أو صفحة الحساب.
4. انسخ مفتاح الـ API — وهو سلسلة سداسية عشرية من 32 خانة بأحرف صغيرة، مثل 1a2b3c4d5e6f7890abcdef1234567890.
5. أضف رصيداً إلى حسابك (يبدأ من دولار واحد).

قبل أن تربط المفتاح بأي عميل برمجي، اختبره مرة واحدة عبر نداء الرصيد الموضّح في القسم التالي. إنه أرخص طلب مصادَق عليه، ويؤكّد ثلاثة أمور دفعة واحدة: أنّ المفتاح صحيح، وأنّ عنوان IP لديك يصل إلى الخدمة، وأنّ الحساب مموّل. أي استجابة تبدأ بـ ERROR_ أو IP_BANNED تعني أنّ المفتاح أو مخرج الشبكة أو حالة الحساب تحتاج معالجة قبل المتابعة.

مصادقة الطلبات في CaptchaAI API

كل استدعاء للواجهة يحمل مفتاحك في المعلمة key؛ فالمعلمة نفسها هي بيان الاعتماد الكامل، دون ترويسات مصادقة إضافية.

إرسال اختبار CAPTCHA

تُرسل تفاصيل الاختبار إلى in.php، فتعود باستجابة تحمل معرّف المهمة:

GET https://ocr.captchaai.com/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=SITE_KEY&pageurl=URL

استطلاع النتيجة

استخدم معرّف المهمة للاستفسار عن النتيجة من res.php؛ ستحصل على التوكن أو على مؤشّر بأنّ الحل لم يكتمل بعد:

GET https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=TASK_ID

التحقق من الرصيد

النداء نفسه مع action=getbalance يعيد رصيدك بالدولار رقماً عشرياً واحداً:

GET https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=getbalance

أمثلة عملية بالكود

الأمثلة التالية تنفّذ المسار كاملاً — قراءة المفتاح من البيئة، والتحقق من الرصيد، ثم إرسال reCAPTCHA v2 — في Python وNode.js وcURL. تخيّل فريق أتمتة صغيراً في القاهرة أو الرياض يبني خط معالجة لجمع البيانات: يخزّن المفتاح مرة واحدة كمتغيّر بيئة على الخادم، ثم يعيد استخدام الدالة نفسها في كل خدمة دون نسخ المفتاح في أي ملف.

Python

import requests
import os

# Load from environment variable (recommended)
API_KEY = os.environ.get("CAPTCHAAI_API_KEY")

# Check balance
balance = requests.get("https://ocr.captchaai.com/res.php", params={
    "key": API_KEY,
    "action": "getbalance"
})
print(f"Balance: ${balance.text}")

# Submit a CAPTCHA
resp = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "6Le-wvkS...",
    "pageurl": "https://example.com"
})
print(f"Response: {resp.text}")

Node.js

const axios = require("axios");

const API_KEY = process.env.CAPTCHAAI_API_KEY;

// Check balance
const balance = await axios.get("https://ocr.captchaai.com/res.php", {
  params: { key: API_KEY, action: "getbalance" },
});
console.log(`Balance: $${balance.data}`);

// Submit a CAPTCHA
const resp = await axios.get("https://ocr.captchaai.com/in.php", {
  params: {
    key: API_KEY,
    method: "userrecaptcha",
    googlekey: "6Le-wvkS...",
    pageurl: "https://example.com",
  },
});
console.log(`Response: ${resp.data}`);

cURL

# Check balance
curl "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=getbalance"

# Submit reCAPTCHA v2
curl "https://ocr.captchaai.com/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=SITE_KEY&pageurl=https://example.com"

تأمين مفتاح CaptchaAI API

المفتاح هو بيان الاعتماد الوحيد، لذا يستحق العناية نفسها التي تمنحها لكلمات مرور الإنتاج.

استخدم متغيرات البيئة

لا تضع المفتاح مباشرةً في الكود المصدري:

# ❌ Bad — key in source code
API_KEY = "abc123def456"

# ✅ Good — key from environment
API_KEY = os.environ["CAPTCHAAI_API_KEY"]

ثم عيّن المتغيّر بحسب نظام التشغيل:

# Linux/macOS
export CAPTCHAAI_API_KEY="abc123def456"

# Windows PowerShell
$env:CAPTCHAAI_API_KEY = "abc123def456"

# Windows CMD
set CAPTCHAAI_API_KEY=abc123def456

استخدم ملفات .env

في التطوير المحلي، احفظ المفتاح في ملف .env واقرأه عند إقلاع التطبيق:

# .env
CAPTCHAAI_API_KEY=abc123def456

# Python
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.environ["CAPTCHAAI_API_KEY"]

// Node.js
require("dotenv").config();
const API_KEY = process.env.CAPTCHAAI_API_KEY;

أضف .env إلى ملف .gitignore حتى لا يُرفع المفتاح إلى مستودع الكود:

# .gitignore
.env

دوّر المفاتيح بانتظام

إذا اشتبهت في تسرّب مفتاح، لا تنتظر:

1. سجّل الدخول إلى لوحة التحكم.
2. أنشئ مفتاح API جديداً.
3. حدّث متغيرات البيئة على كل خوادمك.
4. ألغِ المفتاح القديم.

قيّد المفتاح بعناوين IP موثوقة

تتيح لوحة تحكم CaptchaAI إضافة قائمة بيضاء لعناوين IP، بحيث لا يصادق المفتاح إلا على الطلبات القادمة من عناوين الإنتاج لديك. مفتاح مسرّب من خارج هذا النطاق يصبح بلا قيمة، وهو خط دفاع بسيط وفعّال يكمّل تخزين المفتاح بأمان.

استخدم مدير أسرار للبيئات المشتركة

ملفات .env كافية لمطوّر واحد، لكن ما إن يتجاوز الأمر ذلك — منفّذات CI، أو عدّة خوادم، أو فريق كامل — فالأفضل سحب المفتاح من مدير أسرار بدلاً من نسخ الملفات يدوياً. خدمات مثل AWS Secrets Manager وHashiCorp Vault وGoogle Secret Manager تخزّن المفتاح مركزياً وتمنح كل خدمة صلاحية الوصول إليه وقت التشغيل فقط، فلا يُكتب المفتاح على القرص في أي مكان.

راقب استخدام المفتاح في الإنتاج

لا توفّر الواجهة نقطة قياس لكل مفتاح عدا الرصيد، لذا أحِط كل نداء بقدر يسير من التتبّع. هذا يكشف المفتاح المسرّب عبر استنزاف مفاجئ للرصيد من عنوان مجهول، ويضبط عواصف إعادة المحاولة مبكراً:

• استطلع getbalance مرة كل دقيقة وسجّله كمقياس، ونبّه عند هبوط الرصيد بمقدار عشرة أضعاف خلال أي نافذة من خمس دقائق.
• وسِم كل سجلّ طلب باسم الخدمة والبيئة، وبمعرّف الفريق إن كان عدّة فرق يتشاركون المفتاح نفسه، لتفصل الاستهلاك لاحقاً.
• خزّن أخطاء المصادقة (ERROR_WRONG_USER_KEY وERROR_KEY_DOES_NOT_EXIST) مؤقتاً لستين ثانية على الأقل، حتى لا يُغرق عاملٌ سيئ الإعداد الواجهة ويدفعها إلى حالة IP_BANNED.

ردود الأخطاء

الأسئلة الشائعة

كيف يبدو مفتاح CaptchaAI API وما طوله؟

هو سلسلة سداسية عشرية من 32 خانة بأحرف صغيرة. إن ظهرت مسافات أو أحرف كبيرة عند النسخ، أعِد نسخه من لوحة التحكم لتتجنّب ERROR_WRONG_USER_KEY.

ماذا يعني الخطأ IP_BANNED وكيف أرفعه؟

يظهر بعد محاولات كثيرة بمفتاح غير صالح. صحّح المفتاح، ثم انتظر خمس دقائق ليُرفع الحظر تلقائياً. ولتفادي تكراره، خزّن أخطاء المصادقة مؤقتاً بدل إعادة المحاولة فوراً.

هل قائمة IP البيضاء إلزامية؟

لا، لكنها موصى بها في الإنتاج. تقصر صلاحية المفتاح على عناوين خوادمك، فيصبح أي تسرّب عديم الأثر خارج نطاقك.

هل يعمل المفتاح نفسه مع reCAPTCHA v2 وباقي الأنواع؟

نعم، مفتاح واحد يخدم جميع الأنواع المدعومة وكل نقاط النهاية؛ يتغيّر فقط المعامل method بحسب نوع اختبار CAPTCHA.

كيف أخزّن المفتاح عند مشاركته بين عدة خوادم؟

استخدم مدير أسرار مثل AWS Secrets Manager أو HashiCorp Vault بدل توزيع ملفات .env، وامنح كل خدمة صلاحية القراءة وقت التشغيل فقط.

أدلة ذات صلة

• نشر عمّال CaptchaAI عبر Ansible
• تشغيل حلّ CAPTCHA من داخل قاعدة بيانات Airtable