New Methods & extendedResponse option (#19)

* FriendlyCaptcha

* FriendlyCaptchaExample

* response type json

* response type json

* json param

* json param

* added json param to tests

* added json param to tests

* readme

* new TwoCaptcha()

* new TwoCaptcha()

* cleanup

* new TwoCaptcha(args[0])

* extendedResponse

* MtCaptcha

* Tencent

* Tencent

* pom.xml

* json response

* Update hCaptcha examples

* json to string

* Update Friendly Captcha param

* Add example of Friendly captcha

* Add tencent example

* Update pageurl

* Update README.md

* Update MtCaptcha examples

* Update README.md

---------

Co-authored-by: dzmitry-duboyski <[email protected]>

Author: victorkowalski

README.md

@@ -9,7 +9,7 @@
 
 # JAVA Module for 2Captcha API (captcha solver)
 The easiest way to quickly integrate [2Captcha] into your code to automate solving of any types of captcha.
-Examples of API requests for different captcha types are available on the [Java captcha solver](https://2captcha.com/lang/java) page.
+Examples of API requests for different captcha types are available on the [Java captcha solver] page.
 
 - [JAVA Module for 2Captcha API (captcha solver)](#java-module-for-2captcha-api-captcha-solver)
   - [Installation](#installation)
@@ -37,6 +37,9 @@ Examples of API requests for different captcha types are available on the [Java
     - [Lemin](#lemin)
     - [Turnstile](#turnstile)
     - [AmazonWaf](#amazonwaf)
+    - [Friendly Captcha](#friendly-captcha)
+    - [MTCaptcha](#mtcaptcha)
+    - [Tencent](#tencent)
   - [Other methods](#other-methods)
     - [send / getResult](#send--getresult)
     - [balance](#balance)
@@ -64,21 +67,30 @@ solver.setCallback("https://your.site/result-receiver");
 solver.setDefaultTimeout(120);
 solver.setRecaptchaTimeout(600);
 solver.setPollingInterval(10);
+solver.setExtendedResponse(1);
 ```
 
 ### TwoCaptcha instance options
 
-| Option           | Default value | Description                                                                                                                                        |
-| ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| softId           | -             | your software ID obtained after publishing in [2captcha sofware catalog]                                                                           |
-| callback         | -             | URL of your web-sever that receives the captcha recognition result. The URl should be first registered in [pingback settings] of your account      |
-| defaultTimeout   | 120           | Polling timeout in seconds for all captcha types except ReCaptcha. Defines how long the module tries to get the answer from `res.php` API endpoint |
-| recaptchaTimeout | 600           | Polling timeout for ReCaptcha in seconds. Defines how long the module tries to get the answer from `res.php` API endpoint                          |
-| pollingInterval  | 10            | Interval in seconds between requests to `res.php` API endpoint, setting values less than 5 seconds is not recommended                              |
-
->  **IMPORTANT:** once *callback URL* is defined for `TwoCaptcha` instance with `setCallback`, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL.
+| Option           | Default value| Description                                                                                                                                        |
+|------------------| ------------ |----------------------------------------------------------------------------------------------------------------------------------------------------|
+| host             |`2captcha.com`| API server. You can set it to `rucaptcha.com` if your account is registered there                                                                  |
+| softId           | 4581         | your software ID obtained after publishing in [2captcha sofware catalog]                                                                           |
+| callback         | -            | URL of your web-sever that receives the captcha recognition result. The URl should be first registered in [pingback settings] of your account      |
+| defaultTimeout   | 120          | Polling timeout in seconds for all captcha types except ReCaptcha. Defines how long the module tries to get the answer from `res.php` API endpoint |
+| recaptchaTimeout | 600          | Polling timeout for ReCaptcha in seconds. Defines how long the module tries to get the answer from `res.php` API endpoint                          |
+| pollingInterval  | 10           | Interval in seconds between requests to `res.php` API endpoint, setting values less than 5 seconds is not recommended                              |
+| extendedResponse | 0            | Json or String format response from `res.php` API endpoint, extendedResponse = 1 returns JSON format response                                      |
+
+>  [!IMPORTANT] once *callback URL* is defined for `TwoCaptcha` instance with `setCallback`, all methods return only the captcha ID and DO NOT poll the API to get the result. The result will be sent to the callback URL.
 To get the answer manually use [getResult method](#send--getresult)
 
+> [!TIP]
+> Use the `extendedResponse(1)` setting to obtain an extended response for the captcha. When using `extendedResponse(1)`, the response will be presented as a `JSON` string. Utilizing the extended response `extendedResponse(1)` will be helpful when solving captchas such as [hCaptcha](#hcaptcha) and [ClickCaptcha](#clickcaptcha). When using `extendedResponse(1)` for hCaptcha, the response will include additional fields, such as `respKe`y and `useragent`.<br>
+> Default answer for hCaptcha answer looks like this: `P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...`<br>
+> An extended response using `extendedResponse(1)` for an hCaptcha answer looks like this: `{"request":"P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...","respKey":"E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...","useragent":"Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.6478.127 Safari/537.36","status":1}`
+
+
 ## Solve captcha
 When you submit any image-based captcha use can provide additional options to help 2captcha workers to solve it properly.
 
@@ -206,12 +218,13 @@ captcha.setProxy("HTTPS", "login:password@IP_address:PORT");
 ```
 
 ### hCaptcha
-Method to solve GeeTest puzzle captcha. Returns a set of tokens as JSON.
+Method to solve hCaptcha captcha. Returns a token.
+Use `setExtendedResponse` to get `respKey` and `useragent` in captcha answer.
 
 ```java
 HCaptcha captcha = new HCaptcha();
-captcha.setSiteKey("10000000-ffff-ffff-ffff-000000000001");
-captcha.setUrl("https://www.site.com/page/");
+captcha.setSiteKey("c0421d06-b92e-47fc-ab9a-5caa43c04538");
+captcha.setUrl("https://2captcha.com/demo/hcaptcha");
 captcha.setProxy("HTTPS", "login:password@IP_address:PORT");
 ```
 
@@ -293,7 +306,7 @@ captcha.setHintText("Put the images in the correct way up");
 This method can be used to solve a audio captcha
 
 ```java
-TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+TwoCaptcha solver = new TwoCaptcha(args[0]);
 byte[] bytes = Files.readAllBytes(Paths.get("src/main/resources/audio-en.mp3"));
 String base64EncodedImage = Base64.getEncoder().encodeToString(bytes);
 Audio captcha = new Audio();
@@ -304,7 +317,7 @@ captcha.setBase64(base64EncodedImage);
 Use this method to solve Yandex and obtain a token to bypass the protection.
 
 ```java
-TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+TwoCaptcha solver = new TwoCaptcha(args[0]);
 Yandex captcha = new Yandex();
 captcha.setSiteKey("Y5Lh0tiycconMJGsFd3EbbuNKSp1yaZESUOIHfeV");
 captcha.setUrl("https://rutube.ru");
@@ -314,7 +327,7 @@ captcha.setUrl("https://rutube.ru");
 Use this method to solve Lemin and obtain a token to bypass the protection.
 
 ```java
-TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+TwoCaptcha solver = new TwoCaptcha(args[0]);
 Lemin captcha = new Lemin();      
 captcha.setСaptchaId("CROPPED_d3d4d56_73ca4008925b4f83a8bed59c2dd0df6d");
 captcha.setUrl("http://sat2.aksigorta.com.tr");
@@ -325,7 +338,7 @@ captcha.setApiServer("api.leminnow.com");
 Use this method to solve Turnstile and obtain a token to bypass the protection.
 
 ```java
-TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+TwoCaptcha solver = new TwoCaptcha(args[0]);
 Turnstile captcha = new Turnstile();
 captcha.setSiteKey("0x4AAAAAAAChNiVJM_WtShFf");
 captcha.setUrl("https://ace.fusionist.io");
@@ -335,14 +348,44 @@ captcha.setUrl("https://ace.fusionist.io");
 Use this method to solve AmazonWaf and obtain a token to bypass the protection.
 
 ```java
-TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+TwoCaptcha solver = new TwoCaptcha(args[0]);
 AmazonWaf captcha = new AmazonWaf();
 captcha.setSiteKey("AQIDAHjcYu/GjX+QlghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AF5H1K/siwSLK7RfstKtN5bAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglg");
 captcha.setUrl("https://non-existent-example.execute-api.us-east-1.amazonaws.com");
 captcha.setIV("test_iv");
 captcha.setContext("test_context");
 ```
 
+### Friendly Captcha
+Use this method to solve Friendly Captcha and obtain a token to bypass the protection.
+
+```java
+TwoCaptcha solver = new TwoCaptcha(args[0]);
+FriendlyCaptcha friendlyCaptcha = new FriendlyCaptcha();
+friendlyCaptcha.setSiteKey("FCMST5VUMCBOCGQ9");
+friendlyCaptcha.setPageUrl("https://mysite.com/page/with/FriendlyCaptcha");
+```
+
+### MtCaptcha
+Use this method to solve MtCaptcha and obtain a token to bypass the protection.
+
+```java
+TwoCaptcha solver = new TwoCaptcha(args[0]);
+MtCaptcha mtCaptcha = new MtCaptcha();
+mtCaptcha.setSiteKey("MTPublic-KzqLY1cKH");
+mtCaptcha.setPageUrl("https://2captcha.com/demo/mtcaptcha");
+```
+
+### Tencent
+Use this method to solve Tencent and obtain a token to bypass the protection.
+
+```java
+TwoCaptcha solver = new TwoCaptcha(args[0]);
+Tencent tencent = new Tencent();
+tencent.setAppId("2092215077");
+tencent.setPageUrl("https://mysite.com/page/with/tencent");
+```
+
 ## Other methods
 
 ### send / getResult
@@ -423,3 +466,4 @@ The graphics and trademarks included in this repository are not covered by the M
 [Pingback settings]: https://2captcha.com/setting/pingback
 [Post options]: https://2captcha.com/2captcha-api#normal_post
 [List of supported languages]: https://2captcha.com/2captcha-api#language
+[Java captcha solver]: https://2captcha.com/lang/java

pom.xml

@@ -52,6 +52,11 @@
     </properties>
 
     <dependencies>
+        <dependency>
+            <groupId>org.json</groupId>
+            <artifactId>json</artifactId>
+            <version>20240303</version>
+        </dependency>
         <dependency>
             <groupId>com.squareup.okhttp3</groupId>
             <artifactId>okhttp</artifactId>

src/main/java/com/twocaptcha/TwoCaptcha.java

@@ -6,6 +6,8 @@
 import com.twocaptcha.exceptions.NetworkException;
 import com.twocaptcha.exceptions.TimeoutException;
 import com.twocaptcha.exceptions.ValidationException;
+import org.json.JSONException;
+import org.json.JSONObject;
 
 import java.io.File;
 import java.util.HashMap;
@@ -54,6 +56,8 @@ public class TwoCaptcha {
      */
     private boolean lastCaptchaHasCallback;
 
+    private int extendedResponse = 0;
+
     /**
      * Network client
      */
@@ -76,6 +80,12 @@ public TwoCaptcha(String apiKey) {
         setApiKey(apiKey);
     }
 
+    public TwoCaptcha(String apiKey, int extendedResponse) {
+        this();
+        setApiKey(apiKey);
+        this.extendedResponse = extendedResponse;
+    }
+
     /**
      * @param apiKey
      */
@@ -189,9 +199,10 @@ public void waitForResult(Captcha captcha, Map<String, Integer> waitOptions) thr
             }
 
             try {
-                String result = getResult(captcha.getId());
+                Object result = getResult(captcha.getId());
+
                 if (result != null) {
-                    captcha.setCode(result);
+                    captcha.setCode(String.valueOf(result));
                     return;
                 }
             } catch (NetworkException e) {
@@ -219,11 +230,55 @@ public String send(Captcha captcha) throws Exception {
 
         String response = apiClient.in(params, files);
 
-        if (!response.startsWith("OK|")) {
-            throw new ApiException("Cannot recognise api response (" + response + ")");
+        return getCaptchaId(response);
+    }
+
+    String getCaptchaId(String response) throws ApiException {
+        try {
+            JSONObject jsonObject = new JSONObject(response);
+            String request = jsonObject.getString("request");
+
+            if (request.equals("CAPCHA_NOT_READY")) {
+                return null;
+            }
+
+            return jsonObject.getString("request");
+
+        } catch (JSONException exception) {
+            if (response.equals("CAPCHA_NOT_READY")) {
+                return null;
+            }
+
+            if (!response.startsWith("OK|")) {
+                throw new ApiException("Cannot recognise api response (" + response + ")");
+            }
+
+            return response.substring(3);
         }
+    }
+
+    String handleResponse(String response) throws ApiException {
+        try {
+            JSONObject jsonObject = new JSONObject(response);
+            Object requestVal = jsonObject.get("request");
+
+            if (requestVal.equals("CAPCHA_NOT_READY")) {
+                return null;
+            }
 
-        return response.substring(3);
+            return jsonObject.toString();
+
+        } catch (JSONException exception) {
+            if (response.equals("CAPCHA_NOT_READY")) {
+                return null;
+            }
+
+            if (!response.startsWith("OK|")) {
+                throw new ApiException("Cannot recognise api response (" + response + ")");
+            }
+
+            return response.substring(3);
+        }
     }
 
     /**
@@ -237,18 +292,11 @@ public String getResult(String id) throws Exception {
         Map<String, String> params = new HashMap<>();
         params.put("action", "get");
         params.put("id", id);
+        params.put("json", String.valueOf(this.extendedResponse));
 
         String response = res(params);
 
-        if (response.equals("CAPCHA_NOT_READY")) {
-            return null;
-        }
-
-        if (!response.startsWith("OK|")) {
-            throw new ApiException("Cannot recognise api response (" + response + ")");
-        }
-
-        return response.substring(3);
+        return handleResponse(response);
     }
 
     /**
@@ -314,6 +362,7 @@ private String res(Map<String, String> params) throws Exception {
      */
     private void sendAttachDefaultParams(Map<String, String> params) {
         params.put("key", apiKey);
+        params.put("json", String.valueOf(this.extendedResponse));
 
         if (callback != null) {
             if (!params.containsKey("pingback")) {
@@ -350,4 +399,7 @@ private void validateFiles(Map<String, File> files) throws ValidationException {
         }
     }
 
+    public void setExtendedResponse(int extendedResponse) {
+        this.extendedResponse = extendedResponse;
+    }
 }

src/main/java/com/twocaptcha/captcha/FriendlyCaptcha.java

@@ -0,0 +1,17 @@
+package com.twocaptcha.captcha;
+
+public class FriendlyCaptcha extends Captcha {
+
+    public FriendlyCaptcha() {
+        super();
+        params.put("method", "friendly_captcha");
+    }
+
+    public void setSiteKey(String siteKey) {
+        params.put("sitekey", siteKey);
+    }
+
+    public void setPageUrl(String url) {
+        params.put("pageurl", url);
+    }
+}

src/main/java/com/twocaptcha/captcha/MtCaptcha.java

@@ -0,0 +1,17 @@
+package com.twocaptcha.captcha;
+
+public class MtCaptcha extends Captcha {
+
+    public MtCaptcha() {
+        super();
+        params.put("method", "mt_captcha");
+    }
+
+    public void setSiteKey(String siteKey) {
+        params.put("sitekey", siteKey);
+    }
+
+    public void setPageUrl(String url) {
+        params.put("pageurl", url);
+    }
+}

src/main/java/com/twocaptcha/captcha/Tencent.java

@@ -0,0 +1,17 @@
+package com.twocaptcha.captcha;
+
+public class Tencent extends Captcha {
+
+    public Tencent() {
+        super();
+        params.put("method", "tencent");
+    }
+
+    public void setAppId(String appId) {
+        params.put("app_id", appId);
+    }
+
+    public void setPageUrl(String url) {
+        params.put("pageurl", url);
+    }
+}

src/main/java/examples/AmazonWafExample.java

@@ -6,7 +6,7 @@
 public class AmazonWafExample {
 
     public static void main(String[] args) {
-        TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+        TwoCaptcha solver = new TwoCaptcha(args[0]);
 
         AmazonWaf captcha = new AmazonWaf();
         captcha.setSiteKey("AQIDAHjcYu/GjX+QlghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AF5H1K/siwSLK7RfstKtN5bAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglg");

src/main/java/examples/AmazonWafOptionsExample.java

@@ -6,7 +6,7 @@
 public class AmazonWafOptionsExample {
 
     public static void main(String[] args) {
-        TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+        TwoCaptcha solver = new TwoCaptcha(args[0]);
         solver.setHost("rucaptcha.com");
         solver.setSoftId(0);
         solver.setDefaultTimeout(120);

src/main/java/examples/AudioExample.java

@@ -10,7 +10,7 @@
 public class AudioExample {
 
     public static void main(String[] args) throws Exception {
-        TwoCaptcha solver = new TwoCaptcha("YOUR_API_KEY");
+        TwoCaptcha solver = new TwoCaptcha(args[0]);
 
         byte[] bytes = Files.readAllBytes(Paths.get("src/main/resources/audio-en.mp3"));
         String base64EncodedImage = Base64.getEncoder().encodeToString(bytes);