Интеграция CaptchaAI Soft ID и отслеживания рефералов

Один ключ CaptchaAI может обслуживать сразу несколько клиентов и проектов — без метки все их решения CAPTCHA сольются в общий пул. soft_id помечает каждое решение тегом приложения, клиента или партнёра: агентствам это даёт биллинг по клиентам, вендорам — атрибуцию внутри продукта, партнёрам — учёт трафика. Настраивается параметр один раз на уровне запроса, не требует отдельного ключа API на каждого клиента и не влияет ни на скорость решения, ни на итоговую стоимость.

Что такое soft_id в CaptchaAI

soft_id — параметр запроса к in.php, который CaptchaAI сохраняет вместе с задачей. На решение он не влияет, но метка видна в панели управления и в партнёрской статистике:

Without soft_id:
  All solves tracked as one pool
  No way to know which project/client generated usage

With soft_id:
  Solve #1 ──▶ soft_id=PROJECT_A ──▶ Tracked separately
  Solve #2 ──▶ soft_id=PROJECT_B ──▶ Tracked separately
  Solve #3 ──▶ soft_id=CLIENT_123 ──▶ Tracked separately

Кто и зачем обычно включает эту метку:

• Агентства — видят расход потоков по каждому клиенту в одной панели, без создания отдельного ключа API на клиента.
• Вендоры и разработчики инструментов — получают атрибуцию использования внутри своего продукта, даже когда ключ API принадлежит конечному клиенту.
• Партнёры программы CaptchaAI — получают учёт трафика и вознаграждение по зарегистрированному soft_id, а не по догадкам о происхождении решений.

Как добавить soft_id к запросу

Добавьте soft_id к любому запросу на решение — независимо от типа CAPTCHA. Поле необязательное для базовой работы API, но обязательное, если вам нужна разбивка по клиентам, проектам или партнёрским кампаниям в панели управления:

import requests

API_KEY = "YOUR_API_KEY"
SOFT_ID = "1234"  # Your registered soft_id

resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "soft_id": SOFT_ID,
    "json": 1,
})

Совет: держите soft_id в переменной окружения или конфиге рядом с API_KEY — так его не забудут скопировать при разворачивании нового окружения.

Работает одинаково для reCAPTCHA, Turnstile, изображений и любого другого поддерживаемого типа — параметр не привязан к конкретному method, поэтому его можно передавать в общей функции-обёртке над in.php:

# Turnstile with soft_id
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "turnstile",
    "sitekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "soft_id": SOFT_ID,
    "json": 1,
})

# Image CAPTCHA with soft_id
resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "base64",
    "body": base64_image,
    "soft_id": SOFT_ID,
    "json": 1,
})

Сценарии использования soft_id

1. Учёт клиентов агентства

Агентство, решающее CAPTCHA для нескольких клиентов через один аккаунт, обычно хочет видеть расход потоков по каждому клиенту — для биллинга и оценки нагрузки. Единый soft_id на аккаунт агентства уже даёт эту метку на уровне панели CaptchaAI, а локальный client_tag в обёртке над API добавляет разбивку внутри самого агентства. Обёртка над API сохраняет client_tag при каждой отправке задачи:

class AgencySolver:
    """Track CAPTCHA usage per client."""

    def __init__(self, api_key, agency_soft_id):
        self.api_key = api_key
        self.soft_id = agency_soft_id
        self.base = "https://ocr.captchaai.com"

    def solve(self, method, client_tag=None, **params):
        data = {
            "key": self.api_key,
            "method": method,
            "soft_id": self.soft_id,
            "json": 1,
        }
        data.update(params)

        resp = requests.post(f"{self.base}/in.php", data=data)
        task_id = resp.json()["request"]

        # Log client attribution locally
        if client_tag:
            self._log_usage(client_tag, method, task_id)

        return self._poll(task_id)

    def _poll(self, task_id, timeout=120):
        import time
        start = time.time()
        while time.time() - start < timeout:
            time.sleep(5)
            resp = requests.get(f"{self.base}/res.php", params={
                "key": self.api_key, "action": "get",
                "id": task_id, "json": 1,
            })
            data = resp.json()
            if data["request"] != "CAPCHA_NOT_READY":
                return data["request"]
        raise TimeoutError("Solve timeout")

    def _log_usage(self, client_tag, method, task_id):
        import csv
        import datetime
        with open("client_usage.csv", "a", newline="") as f:
            writer = csv.writer(f)
            writer.writerow([
                datetime.datetime.utcnow().isoformat(),
                client_tag, method, task_id,
            ])


# Track usage per client
solver = AgencySolver("YOUR_API_KEY", agency_soft_id="1234")

# Client A's solves
solver.solve("userrecaptcha",
    client_tag="client_acme",
    googlekey="KEY", pageurl="https://acme.com",
)

# Client B's solves
solver.solve("turnstile",
    client_tag="client_beta",
    sitekey="KEY", pageurl="https://beta.com",
)

2. Встраивание soft_id в продукт вендора ПО

Если вы собираете инструмент, использующий ключ конечного пользователя, ваш soft_id даёт атрибуцию и партнёрскую комиссию, даже когда ключ принадлежит клиенту. Достаточно зашить один и тот же soft_id в код продукта — регистрировать его заново для каждого пользователя не нужно:

class MyScraper:
    """Scraping tool with embedded CaptchaAI integration."""

    SOFT_ID = "5678"  # Registered when joining partner program

    def __init__(self, user_api_key):
        self.api_key = user_api_key

    def solve_captcha(self, method, **params):
        data = {
            "key": self.api_key,
            "method": method,
            "soft_id": self.SOFT_ID,  # Always include vendor ID
            "json": 1,
        }
        data.update(params)
        resp = requests.post(
            "https://ocr.captchaai.com/in.php", data=data,
        )
        return resp.json()

3. Разделение проектов одним ключом

Если ключ обслуживает несколько проектов — мониторинг цен, лидогенерацию, QA-тестирование, — присваивайте каждому свой soft_id, чтобы разделить нагрузку без отдельных ключей. Такой словарь с проектными ID удобно держать в конфиге рядом с остальными настройками окружения:

# Different soft_ids per project
PROJECTS = {
    "price_monitor": "1001",
    "lead_gen": "1002",
    "qa_testing": "1003",
}

def solve_for_project(project_name, method, **params):
    soft_id = PROJECTS.get(project_name, "0000")
    data = {
        "key": API_KEY,
        "method": method,
        "soft_id": soft_id,
        "json": 1,
    }
    data.update(params)
    return requests.post("https://ocr.captchaai.com/in.php", data=data)

soft_id и партнёрское вознаграждение

Партнёрская программа CaptchaAI учитывает решения именно по зарегистрированному soft_id — вознаграждение начисляется за трафик и объём решений под вашей меткой, независимо от того, кто пополняет баланс API-ключа. Точные условия и ставки смотрите в личном кабинете партнёра — этот текст не заменяет договор оферты.

Перед запуском кампании стоит проверить три вещи:

• soft_id зарегистрирован в партнёрской программе, а не придуман произвольно.
• Одна и та же метка используется во всех интеграциях, где вы хотите видеть свою атрибуцию.
• Панель управления показывает решения по этому soft_id — если атрибуции нет, см. раздел «Типичные проблемы» ниже.

Локальный учёт использования

Панель показывает агрегированную статистику по soft_id, но для биллинга клиентов удобнее дублировать записи локально:

import csv
import datetime
from collections import defaultdict


class UsageTracker:
    """Track CAPTCHA solve usage for billing and analytics."""

    def __init__(self, log_file="captchaai_usage.csv"):
        self.log_file = log_file
        self._init_log()

    def _init_log(self):
        try:
            with open(self.log_file, "r"):
                pass
        except FileNotFoundError:
            with open(self.log_file, "w", newline="") as f:
                writer = csv.writer(f)
                writer.writerow([
                    "timestamp", "soft_id", "client",
                    "method", "task_id", "status",
                ])

    def record(self, soft_id, client, method, task_id, status="submitted"):
        with open(self.log_file, "a", newline="") as f:
            writer = csv.writer(f)
            writer.writerow([
                datetime.datetime.utcnow().isoformat(),
                soft_id, client, method, task_id, status,
            ])

    def get_summary(self, days=30):
        """Summarize usage by client over the last N days."""
        cutoff = datetime.datetime.utcnow() - datetime.timedelta(days=days)
        usage = defaultdict(lambda: defaultdict(int))

        with open(self.log_file, "r") as f:
            reader = csv.DictReader(f)
            for row in reader:
                ts = datetime.datetime.fromisoformat(row["timestamp"])
                if ts > cutoff:
                    usage[row["client"]][row["method"]] += 1

        return dict(usage)


# Usage
tracker = UsageTracker()
tracker.record("1234", "client_acme", "userrecaptcha", "TASK123")

summary = tracker.get_summary(days=30)
for client, methods in summary.items():
    print(f"{client}: {dict(methods)}")

Если в логе хранятся метки клиентов (client_tag), храните только необходимое для биллинга и ограничьте доступ к CSV — разумная гигиена и по 152-ФЗ, и по GDPR.

Вопросы про soft_id

Как зарегистрировать soft_id?

Через партнёрскую или developer-программу CaptchaAI — вам выдадут уникальный soft_id для приложения. Регистрация занимает пару минут и не требует отдельного договора для старта.

Нужно ли передавать soft_id в каждом запросе?

Да, в каждом запросе к in.php. На уровне ключа API soft_id не хранится, поэтому его нельзя один раз «привязать» к аккаунту и забыть — это осознанное ограничение, чтобы одна интеграция могла обслуживать сразу несколько меток.

Влияет ли soft_id на скорость решения или на цену?

Нет, это только метка для атрибуции. Ни время решения, ни доля успешных решений, ни стоимость по тарифу от неё не зависят.

Можно ли использовать один soft_id для нескольких клиентов агентства?

Да, но вы теряете разбивку по клиентам внутри панели CaptchaAI. Для раздельного биллинга держите client_tag в собственном логе либо регистрируйте отдельный soft_id на каждого крупного клиента.

Нужен ли отдельный soft_id для staging и production?

Формально не обязательно, но раздельные метки для тестового и боевого окружения удобны на практике: вы сразу отличаете нагрузочное тестирование от реального трафика клиентов и не искажаете статистику по проектам.

Что делать, если атрибуция не появляется?

Проверьте написание (soft_id, а не softId) и регистрацию в партнёрской программе — незарегистрированные ID не попадают в отчёты.

Типичные проблемы с soft_id

Большинство обращений в поддержку по soft_id сводятся к четырём причинам — сверьтесь с таблицей, прежде чем открывать тикет:

Связанные руководства

• Проверка баланса и автопополнение
• Панель управления и мониторинг использования

Настройте атрибуцию использования по клиентам и проектам — зарегистрируйтесь в партнёрской программе CaptchaAI.