BLS CAPTCHA-Anweisungen und Code-Parameter – tiefer Einblick

Zwei optionale Parameter entscheiden bei BLS-CAPTCHAs oft über Erfolg oder Fehlschlag: instructions und code. Wer sie sauber aus der Seite ausliest und mitschickt, hebt die Trefferquote spürbar – besonders bei den mehrdeutigen Bildraster-Abfragen, wie sie BLS-Portale für Visumtermine einsetzen. Dieser Deep-Dive zeigt, welche Felder die CaptchaAI-API erwartet, wie Sie sie extrahieren und in der richtigen Reihenfolge übermitteln.

Für Leserinnen und Leser aus dem DACH-Raum ist das ein vertrautes Szenario: Wer einen Visumtermin über ein BLS-Portal buchen möchte, stößt regelmäßig auf genau diese CAPTCHA-Abfrage. Die folgenden Beispiele automatisieren ausschließlich Ihren eigenen, legitimen Buchungsablauf – nicht mehr und nicht weniger.

Die BLS-CAPTCHA-Parameter im Überblick

Bevor Sie eine Zeile Code schreiben, lohnt der Blick auf die sechs Felder, die die CaptchaAI-API für die Methode bls kennt. Pflicht sind nur drei davon; instructions und code sind optional, verbessern aber das Ergebnis bei kniffligen Abfragen.

Der Ablauf in fünf Schritten

Bevor wir in den Code einsteigen, hier der komplette Weg vom Aufruf der Seite bis zum abgesendeten Formular in Kurzform:

1. Seite laden und auf das gerenderte CAPTCHA-Element warten.
2. sitekey, pageurl sowie – falls vorhanden – instructions und code extrahieren.
3. Die Aufgabe per in.php an CaptchaAI übermitteln und die Task-ID entgegennehmen.
4. Das Ergebnis über res.php abfragen (Polling), bis der Status auf fertig springt.
5. Das zurückgegebene Token in das Formularfeld einfügen und das Formular absenden.

Die folgenden Abschnitte gehen jeden dieser Schritte im Detail durch – in genau dieser Reihenfolge.

sitekey, instructions und code aus der Seite auslesen

Der erste Schritt ist immer die Extraktion. Der sitekey steckt meist in einem data-sitekey-Attribut, der Anweisungstext in einem sichtbaren Element und der Variantencode oft in einer versteckten Eingabe oder im Seiten-Quelltext. Das folgende Skript liest alle drei in einem Durchgang aus.

# extract_bls.py
import re
from selenium import webdriver
from selenium.webdriver.common.by import By


def extract_bls_params(url):
    """Extract BLS CAPTCHA parameters from a page."""
    driver = webdriver.Chrome()
    driver.get(url)

    params = {"pageurl": url}

    # Extract sitekey
    captcha_el = driver.find_element(By.CSS_SELECTOR, "[data-sitekey], .bls-captcha")
    sitekey = captcha_el.get_attribute("data-sitekey")
    if sitekey:
        params["sitekey"] = sitekey

    # Extract instructions if visible
    try:
        instructions_el = driver.find_element(
            By.CSS_SELECTOR, ".captcha-instructions, .captcha-text"
        )
        params["instructions"] = instructions_el.text.strip()
    except Exception:
        pass

    # Extract code from hidden input or script
    page_source = driver.page_source
    code_match = re.search(r'captcha_code["\']?\s*[:=]\s*["\']([^"\']+)', page_source)
    if code_match:
        params["code"] = code_match.group(1)

    driver.quit()
    return params


# Usage
params = extract_bls_params("https://bls-example.com/appointment")
print(params)

Wenn das CAPTCHA dynamisch nachgeladen wird

Viele BLS-Portale rendern das CAPTCHA erst nach dem initialen Seitenaufbau. Greifen Sie zu früh zu, ist das data-sitekey-Attribut noch leer. Warten Sie deshalb mit WebDriverWait auf das Element, bevor Sie die Attribute auslesen.

BLS-CAPTCHA an die CaptchaAI-API übermitteln

Steht das Parameter-Dictionary, folgt die Übermittlung an den Endpunkt in.php. Das Muster ist bei allen CaptchaAI-Methoden gleich: Sie schicken die Aufgabe ab, erhalten eine Task-ID zurück und fragen anschließend das Ergebnis über res.php ab (Polling).

Grundgerüst der Übermittlung

# solve_bls_basic.py
import requests
import time
import os


def solve_bls(sitekey, pageurl, instructions=None, code=None):
    """Solve BLS CAPTCHA via CaptchaAI API."""
    api_key = os.environ["CAPTCHAAI_API_KEY"]

    payload = {
        "key": api_key,
        "method": "bls",
        "sitekey": sitekey,
        "pageurl": pageurl,
        "json": 1,
    }

    # Add optional parameters for higher accuracy
    if instructions:
        payload["instructions"] = instructions
    if code:
        payload["code"] = code

    resp = requests.post(
        "https://ocr.captchaai.com/in.php",
        data=payload,
        timeout=30,
    )
    result = resp.json()

    if result.get("status") != 1:
        raise RuntimeError(f"Submit failed: {result.get('request')}")

    task_id = result["request"]

    # Poll for result
    time.sleep(10)
    for _ in range(30):
        resp = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1,
        }, timeout=15)
        data = resp.json()

        if data.get("status") == 1:
            return data["request"]
        if data["request"] != "CAPCHA_NOT_READY":
            raise RuntimeError(data["request"])
        time.sleep(5)

    raise TimeoutError("BLS solve timeout")


# Usage
solution = solve_bls(
    sitekey="your-bls-sitekey",
    pageurl="https://bls-example.com/appointment",
    instructions="Select images in the correct order",
)
print(f"Solution: {solution}")

Das Ergebnis per Polling abfragen

Nach dem Absenden liefert die API zunächst nur eine Task-ID. Der Status CAPCHA_NOT_READY ist dabei kein Fehler, sondern signalisiert, dass die Lösung noch läuft. Fragen Sie das Ergebnis in kurzen Abständen ab, bis der Status auf fertig wechselt.

Der instructions-Parameter richtig einsetzen

instructions teilt CaptchaAI mit, was die Abfrage konkret verlangt. Der Parameter zahlt sich immer dann aus, wenn der Aufgabentext neben dem Bild steht und nicht in die Grafik eingebettet ist – dann fehlt der Lösung sonst der Kontext. Übergeben Sie den Text möglichst wörtlich so, wie er auf der Seite erscheint.

# Common BLS instruction patterns:
instructions_examples = [
    "Select images in the correct order",
    "Click the images in order from left to right",
    "Arrange the images by number",
    "Select the matching image",
    "Click in the order shown",
]

# Extract instructions from the CAPTCHA image area
def get_instructions_from_page(driver):
    """Try multiple selectors to find instruction text."""
    selectors = [
        ".captcha-instructions",
        ".bls-captcha-text",
        "#captcha-prompt",
        ".challenge-text",
    ]

    for sel in selectors:
        try:
            el = driver.find_element(By.CSS_SELECTOR, sel)
            text = el.text.strip()
            if text:
                return text
        except Exception:
            continue

    return None

Der code-Parameter: BLS-Varianten erkennen

code benennt die BLS-CAPTCHA-Variante. Manche Implementierungen setzen mehrere Challenge-Typen ein, die über eine solche Kennung unterschieden werden. Steht sie im Quelltext, sollten Sie sie mitschicken – und bei jedem Durchlauf neu auslesen, da sie je nach Sitzung oder Region wechseln kann.

# Detect BLS CAPTCHA code from page
def detect_bls_code(page_source):
    """Detect which BLS CAPTCHA code/type is being used."""
    patterns = [
        (r'captchaType["\']?\s*[:=]\s*["\'](\w+)', "captchaType"),
        (r'data-captcha-code["\']?\s*=\s*["\'](\w+)', "data attribute"),
        (r'bls_code["\']?\s*[:=]\s*["\'](\w+)', "bls_code"),
    ]

    for pattern, source in patterns:
        match = re.search(pattern, page_source)
        if match:
            return match.group(1)

    return None

Kompletter BLS-Ablauf mit Selenium

Alle Bausteine zusammengesetzt ergeben einen durchgehenden Ablauf: Formularfelder befüllen, Parameter extrahieren, über die API lösen, das Token in das Formular einfügen und absenden. Das folgende Skript zeigt die Schritte in der richtigen Reihenfolge.

# full_bls_flow.py
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import os
import re


def solve_bls_with_selenium(url, form_data=None):
    """Complete BLS CAPTCHA flow using Selenium."""
    driver = webdriver.Chrome()
    driver.get(url)

    wait = WebDriverWait(driver, 15)

    # Fill any form fields before CAPTCHA
    if form_data:
        for field_id, value in form_data.items():
            el = wait.until(EC.presence_of_element_located((By.ID, field_id)))
            el.clear()
            el.send_keys(value)

    # Extract CAPTCHA parameters
    captcha_container = wait.until(
        EC.presence_of_element_located((By.CSS_SELECTOR, "[data-sitekey], .bls-captcha"))
    )
    sitekey = captcha_container.get_attribute("data-sitekey")

    # Get instructions
    instructions = None
    try:
        inst_el = driver.find_element(By.CSS_SELECTOR, ".captcha-instructions")
        instructions = inst_el.text.strip()
    except Exception:
        pass

    # Solve via API
    solution = solve_bls(
        sitekey=sitekey,
        pageurl=driver.current_url,
        instructions=instructions,
    )

    # Inject solution
    driver.execute_script("""
        var input = document.querySelector('input[name="captcha-response"], #captcha-response');
        if (input) {
            input.value = arguments[0];
        } else {
            var hidden = document.createElement('input');
            hidden.type = 'hidden';
            hidden.name = 'captcha-response';
            hidden.value = arguments[0];
            document.forms[0].appendChild(hidden);
        }
    """, solution)

    # Submit form
    submit_btn = driver.find_element(By.CSS_SELECTOR, "button[type='submit'], #submit")
    submit_btn.click()

    # Wait for confirmation
    wait.until(EC.url_changes(url))
    result_url = driver.current_url
    driver.quit()

    return result_url

Typische Fehler und ihre Behebung

Die meisten Probleme bei der BLS-Integration gehen auf zwei Ursachen zurück: falsch oder zu früh extrahierte Parameter und ein fehlender Anweisungstext. Die folgende Tabelle ordnet Symptom, Ursache und Lösung zu.

Best Practices für stabile BLS-Integrationen

Damit Ihr Ablauf auch bei wechselnden Portalen zuverlässig bleibt, haben sich in der Praxis einige Punkte bewährt:

• Extrahieren Sie sitekey und code bei jedem Durchlauf frisch – beide können sich je nach Sitzung oder Region ändern.
• Übergeben Sie instructions immer dann, wenn der Aufgabentext neben dem Bild steht statt darin.
• Warten Sie mit WebDriverWait explizit auf das gerenderte CAPTCHA-Element, statt mit festen Pausen zu arbeiten.
• Behandeln Sie CAPCHA_NOT_READY als normalen Zwischenstand und nicht als Fehler.
• Legen Sie den API-Schlüssel in einer Umgebungsvariablen ab, niemals fest im Quelltext.

Rechtlicher Rahmen bei Visumterminen

Gerade bei BLS-Visumportalen lohnt ein Blick auf die Rahmenbedingungen. Automatisieren Sie ausschließlich Ihren eigenen, berechtigten Buchungsvorgang und halten Sie sich an die Nutzungsbedingungen des jeweiligen Portals. Werden dabei personenbezogene Daten – etwa Passnummern oder IP-Adressen – verarbeitet, greifen die Vorgaben der DSGVO: Prüfen Sie Ihre Rechtsgrundlage und dokumentieren Sie, welche Daten wohin fließen. Die hier gezeigten Skripte lösen die CAPTCHA-Abfrage, treffen aber keine Aussage über die Zulässigkeit eines konkreten Anwendungsfalls – diese Einschätzung bleibt bei Ihnen.

Häufige Fragen

Wofür stehen die Parameter instructions und code?

instructions überträgt den sichtbaren Aufgabentext der Abfrage, code benennt die eingesetzte BLS-Variante. Beide sind optional, schärfen aber den Kontext für die Lösung bei mehrdeutigen Bildraster-Abfragen.

Muss ich instructions immer mitschicken?

Nein. CaptchaAI löst die meisten BLS-CAPTCHAs auch ohne. Bei mehrdeutigen Abfragen – etwa „Bilder in der richtigen Reihenfolge auswählen" – erhöht ein mitgeschickter Anweisungstext jedoch die Genauigkeit.

Wie erkenne ich, ob eine Seite überhaupt ein BLS-CAPTCHA nutzt?

Suchen Sie im Markup nach einem data-sitekey-Attribut oder einem .bls-captcha-Container. Fehlt beides und Sie sehen stattdessen ein reCAPTCHA- oder Turnstile-Widget, ist die Methode bls die falsche Wahl.

Wie schnell löst CaptchaAI ein BLS-CAPTCHA?

Der eigentliche Lösungsvorgang liegt bei BLS-CAPTCHAs typischerweise unter einer Sekunde. Inklusive Übermittlung und Polling erhalten Sie die Antwort meist innerhalb weniger Sekunden – bei einer hohen Erfolgsquote auf unterstützten Typen.

Welcher CaptchaAI-Tarif passt zu regelmäßigen BLS-Abfragen?

Für einzelne Terminbuchungen genügt BASIC (15 $/Monat, 5 Threads). Wer parallel viele Abfragen fährt, skaliert über mehr Threads, etwa mit ADVANCE (90 $/Monat, 50 Threads). Abgerechnet wird pro Thread – nicht pro Lösung.

Verwandte Leitfäden

• BLS-CAPTCHA: Bildraster-Reihenfolge und Antwortverarbeitung
• BLS-CAPTCHA-Fehler richtig beheben

BLS-CAPTCHA-Parameter im Griff? Starten Sie mit CaptchaAI.