Add unified captcha third-party services skill with official API workflow

captcha-third-party-services/references/official-docs-and-analysis.md

@@ -0,0 +1,96 @@
+# Official Docs And Analysis
+
+This file summarizes official API documentation for 2Captcha, YesCaptcha, and Anti-Captcha and maps them into one operational workflow.
+
+## Official Sources
+
+### 2Captcha
+
+- API docs hub: https://2captcha.com/api-docs
+- `createTask`: https://2captcha.com/api-docs/create-task
+- `getTaskResult`: https://2captcha.com/api-docs/get-task-result
+- `getBalance`: https://2captcha.com/api-docs/get-balance
+
+### YesCaptcha
+
+- Dashboard: https://yescaptcha.com/dashboard.html
+- `createTask`: https://yescaptcha.atlassian.net/wiki/spaces/YESCAPTCHA/pages/7930129/createTask+submit+a+captcha+task
+- `getTaskResult`: https://yescaptcha.atlassian.net/wiki/spaces/YESCAPTCHA/pages/7930006/getTaskResult+Task+Result+Method
+- `getBalance`: https://yescaptcha.atlassian.net/wiki/spaces/YESCAPTCHA/pages/7930094/getBalance+balance+Method
+
+### Anti-Captcha
+
+- API docs hub: https://anti-captcha.com/apidoc
+- `createTask`: https://anti-captcha.com/apidoc/methods/createTask
+- `getTaskResult`: https://anti-captcha.com/apidoc/methods/getTaskResult
+- `getBalance`: https://anti-captcha.com/apidoc/methods/getBalance
+
+## Endpoint Matrix
+
+All three providers use `POST` + JSON and share the same core method names.
+
+| Provider | createTask | getTaskResult | getBalance |
+|---|---|---|---|
+| 2Captcha | `https://api.2captcha.com/createTask` | `https://api.2captcha.com/getTaskResult` | `https://api.2captcha.com/getBalance` |
+| YesCaptcha | `https://api.yescaptcha.com/createTask` | `https://api.yescaptcha.com/getTaskResult` | `https://api.yescaptcha.com/getBalance` |
+| Anti-Captcha | `https://api.anti-captcha.com/createTask` | `https://api.anti-captcha.com/getTaskResult` | `https://api.anti-captcha.com/getBalance` |
+
+## Shared Request Pattern
+
+### createTask
+
+```json
+{
+  "clientKey": "YOUR_API_KEY",
+  "task": {
+    "type": "RecaptchaV2TaskProxyless",
+    "websiteURL": "https://example.com",
+    "websiteKey": "SITE_KEY"
+  }
+}
+```
+
+### getTaskResult
+
+```json
+{
+  "clientKey": "YOUR_API_KEY",
+  "taskId": 123456789
+}
+```
+
+### getBalance
+
+```json
+{
+  "clientKey": "YOUR_API_KEY"
+}
+```
+
+## Shared Response Pattern
+
+- `errorId = 0`: request accepted/successful.
+- `errorId != 0`: inspect `errorCode` and `errorDescription`.
+- `getTaskResult.status`:
+  - `processing`
+  - `ready` with `solution`.
+
+## Practical Differences
+
+- **Domain and account pool differ**: task acceptance, queue depth, and solve latency vary by provider.
+- **Balance shape differs slightly**:
+  - 2Captcha and Anti-Captcha commonly return `balance`.
+  - YesCaptcha may also return additional balance fields (for example `softBalance` and invite-related fields).
+- **Task support overlap is high but not perfect**: always verify task type and required fields per provider docs before failover.
+
+## Integration Recommendations
+
+1. Keep one canonical `task` payload schema in your project.
+2. Swap only provider domain + API key for failover.
+3. Poll every 3-5 seconds; stop on timeout and switch provider.
+4. Log provider, task type, taskId, latency, and errorCode for reliability tuning.
+5. Never hardcode API keys into version-controlled files.
+
+## Live Connectivity Check (2026-03-03)
+
+`getBalance` was successfully called for all three providers (`errorId: 0`) during skill implementation on March 3, 2026.