Insomnia REST-Client für die CaptchaAI-API-Entwicklung

Bevor Sie eine Zeile Integrationscode schreiben, sollten Sie den CaptchaAI-Ablauf einmal von Hand durchspielen:

• eine Aufgabe an in.php übermitteln,
• das Ergebnis an res.php abfragen,
• und das zurückgegebene Token prüfen.

Genau dafür ist Insomnia gemacht: Der REST-Client bildet beide Endpunkte als klickbare Anfragen ab – Parameter, Guthaben und Fehler prüfen Sie ohne Skript.

Insomnia oder Postman für CaptchaAI?

Für den Funktionstest der CaptchaAI-API genügt ein schlanker REST-Client – meist Insomnia oder Postman:

Für Ad-hoc-Tests reicht Insomnia; Postman lohnt sich erst bei vielen Testskripten oder Cloud-Kollaboration.

Arbeitsbereich und Umgebungsvariablen einrichten

Legen Sie zuerst einen Arbeitsbereich an und lagern Sie Schlüssel und URLs in Umgebungsvariablen aus.

CaptchaAI-Arbeitsbereich anlegen

Öffnen Sie Insomnia, klicken Sie auf Create → Design Document oder Request Collection und nennen Sie ihn „CaptchaAI API“.

Umgebungsvariablen statt fest verdrahteter Werte

Nutzen Sie Insomnias Umgebungssystem, damit Schlüssel und URLs nicht in jeder Anfrage stehen:

1. Auf das Dropdown-Menü „Environment“ (oben links) klicken.
2. Manage Environments wählen.
3. Eine Base Environment mit den gemeinsamen Werten anlegen:

{
  "base_url": "https://ocr.captchaai.com",
  "api_key": "YOUR_API_KEY"
}

Ergänzen Sie Sub Environments für Entwicklung und Produktion:

Entwicklung:

{
  "test_sitekey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
  "test_pageurl": "https://www.google.com/recaptcha/api2/demo"
}

Produktion:

{
  "test_sitekey": "YOUR_PRODUCTION_SITEKEY",
  "test_pageurl": "https://your-target-site.com"
}

Über {{ base_url }} und {{ api_key }} greifen Sie in Anfragen darauf zu und wechseln per Klick zwischen Test und Produktion.

Die zentralen API-Anfragen

Der Ablauf ist bei jedem Typ gleich: an in.php übermitteln, an res.php abfragen.

1. Guthaben prüfen

GET an {{ base_url }}/res.php mit diesen Abfrageparametern:

Erwartete Antwort:

{
  "status": 1,
  "request": "12.3456"
}

Das Guthaben wird in US-Dollar geführt – CaptchaAI rechnet pro Thread ab, nicht pro Lösung.

2. reCAPTCHA-v2-Aufgabe übermitteln

POST an {{ base_url }}/in.php (Form URL Encoded) mit diesen Formularparametern:

Erwartete Antwort:

{
  "status": 1,
  "request": "TASK_ID_HERE"
}

3. Ergebnis abfragen (Polling)

GET an {{ base_url }}/res.php, um das Ergebnis abzufragen:

Erwartete Antworten:

Noch in Bearbeitung:

{
  "status": 0,
  "request": "CAPCHA_NOT_READY"
}

Fertig gelöst:

{
  "status": 1,
  "request": "03AGdBq24PBCb..."
}

4. Cloudflare-Turnstile-Aufgabe übermitteln

Für Turnstile ändern sich nur method und Schlüsselparameter:

5. Bild-CAPTCHA übermitteln

Bild-CAPTCHAs als Base64 per POST an {{ base_url }}/in.php:

Vorlagen für die unterstützten CAPTCHA-Typen

Jeder Typ unterscheidet sich nur in method und den Schlüsselparametern:

Hinweis: hCaptcha und FunCaptcha werden von CaptchaAI nicht unterstützt; GeeTest v4 ist bald verfügbar, aber noch nicht nutzbar.

Anfragen in Ordnern organisieren

Strukturieren Sie den Arbeitsbereich mit Ordnern:

CaptchaAI API/
├── Account/
│   └── Check Balance
├── reCAPTCHA/
│   ├── Submit v2 Task
│   ├── Submit v3 Task
│   ├── Submit Enterprise Task
│   └── Poll Result
├── Cloudflare/
│   ├── Submit Turnstile Task
│   └── Poll Result
├── Image/
│   ├── Submit Base64 Image
│   └── Poll Result
└── hCaptcha/
    ├── Submit hCaptcha Task
    └── Poll Result

Übermittlung und Polling verketten

Insomnia kann sich auf frühere Antworten beziehen – so koppeln Sie „Übermitteln → Abfragen“ ohne manuelles Kopieren der Aufgaben-ID.

Schritt 1: Auf die Übermittlungsantwort verweisen

Nach dem Absenden steht die Aufgaben-ID bereit; nachfolgende Anfragen können darauf zugreifen.

Schritt 2: Antwortreferenz in der Polling-Anfrage verwenden

Im id-Parameter der Polling-Anfrage:

1. Im Wertfeld Ctrl+Space drücken.
2. Response → Body Attribute wählen.
3. Konfigurieren: Request = Übermittlungsanfrage, Filter = $.request (JSONPath für die Aufgaben-ID), Trigger Behavior = „Always“.

Insomnia zieht die Aufgaben-ID nun automatisch aus der letzten Übermittlungsantwort.

Antworten validieren

Insomnia hat keine Testaussagen, doch die Antworten lassen sich visuell prüfen.

Erfolgsindikatoren

Häufige Fehlermeldungen

Fehlerbehebung

Stolpersteine und Lösungen:

Sammlung im Team teilen

In DACH-Teams mit GitLab CI lohnt sich eine geteilte Collection – gleicher Ablauf, eigener Schlüssel.

Collection exportieren

1. Rechtsklick auf den Arbeitsbereich.
2. Export Data wählen.
3. Format wählen: Insomnia v4 (JSON) oder HAR.
4. API-Schlüssel entfernen, bevor Sie die Datei teilen.

Git Sync nutzen

1. Die Arbeitsbereichseinstellungen öffnen.
2. Ein Git-Repository konfigurieren.
3. Die Request-Collection committen und pushen.
4. Teammitglieder klonen sie und tragen eigene Umgebungsvariablen mit eigenen Schlüsseln ein.

Sicherheitshinweis: Committen Sie nie Umgebungsdateien mit echten API-Schlüsseln in gemeinsame Repositorys – nutzen Sie private Umgebungen oder .gitignore.

Häufige Fragen

Antworten aus der Praxis:

Kann ich Insomnia so einrichten, dass CaptchaAI-Tests nach Zeitplan laufen?

Nicht direkt – Insomnia ist interaktiv. Exportieren Sie Ihre Anfragen als cURL-Befehle und starten Sie sie in einer CI/CD-Pipeline (GitLab CI, GitHub Actions).

Wie halte ich meinen API-Schlüssel aus einer geteilten Collection heraus?

Legen Sie ihn nur in einer privaten Sub Environment ab und setzen Sie die Umgebungsdatei auf .gitignore. Beim Export entfernen Sie den Wert von Hand.

Löst CaptchaAI in dieser Umgebung auch hCaptcha?

Nein, beide werden nicht unterstützt. Verfügbar sind reCAPTCHA v2/v3, Cloudflare Turnstile und Challenge, GeeTest v3 sowie Bild- und Grid-CAPTCHAs.

Fazit

Ein Insomnia-Arbeitsbereich prüft Übermittlung, Polling und Fehlercodes vor dem Integrationscode. Drei Punkte bleiben entscheidend:

• Umgebungsvariablen statt hartcodierter Schlüssel – und nie mit echten Schlüsseln committen.
• Der Ablauf bleibt gleich: an in.php übermitteln, an res.php abfragen.
• Nur Vorlagen für tatsächlich unterstützte Typen anlegen.

Verwandte Leitfäden

• CaptchaAI in wenigen Minuten einrichten
• API-Antwortformate und Fehlercodes im Überblick
• Cloudflare Turnstile per API lösen