Acceso al servidor
Proceso de comunicación del producto
Proceso normal
Cuando el servicio de verificación funciona con normalidad y la red del usuario carga correctamente, se ejecuta el flujo del código de verificación. El servidor debe centrarse en la fase de verificación secundaria.

Proceso de excepción
Proceso sin conexión integrado en el código de verificación
Cuando el servicio de verificación presenta una anomalía y se utiliza el modo sin conexión integrado en el código de verificación, el servidor debe centrarse en la fase de verificación secundaria. En este caso, la solicitud del servidor al servicio de código de verificación encontrará una excepción. Se recomienda capturar la excepción y determinar si se permite al usuario continuar en función del escenario de negocio.

Proceso de contingencia personalizado (solo como referencia)
Cuando el servicio de verificación presenta una anomalía y se utiliza una verificación de contingencia personalizada, como la verificación por caracteres, se recomienda que el servidor añada una interfaz o un mecanismo de activación para que el frontend determine el método de verificación específico. El servidor puede utilizar la interfaz check_status proporcionada por el código de verificación para determinar si el código de verificación funciona con normalidad.

Plan de integración del código de verificación en el servidor
Preparativos previos a la integración
Obtener del lado del cliente de integración los recursos necesarios. La información, como las direcciones de dominio, debe obtenerse del contacto interno de la empresa una vez completado el despliegue.
| Tipo de cliente | Recursos necesarios | Descripción de los recursos |
| Servidor | captchaId | ID del escenario de verificación, se puede crear mediante la consola de administración |
| captchaKey | KEY del escenario de verificación, se genera al crear un nuevo escenario en la consola de administración y corresponde uno a uno con captchaId |
Integración del servidor
Tras completar el usuario la verificación en la interfaz del frontend, se generará un conjunto de parámetros relacionados con el código de verificación. La solicitud de negocio del usuario incluirá estos parámetros, y la interfaz de negocio del backend cargará estos parámetros en la interfaz de verificación secundaria de EngageLab para confirmar la validez de la verificación del usuario.
Si tomamos como ejemplo el escenario de inicio de sesión:
- Antes de integrar el código de verificación, el frontend envía el nombre de usuario y la contraseña para solicitar la interfaz de inicio de sesión del negocio. El sistema determina si el nombre de usuario y la contraseña coinciden. Si coinciden, el inicio de sesión es correcto; si no, se deniega el inicio de sesión.
- Tras integrar el código de verificación, el frontend envía la información de negocio y los parámetros relacionados con el código de verificación para solicitar la interfaz de inicio de sesión del negocio. El sistema envía los parámetros relacionados con el código de verificación para solicitar la interfaz de verificación secundaria (validate) del servidor de código de verificación, con el fin de obtener el resultado de verificación. En función del resultado de verificación y del resultado de coincidencia del nombre de usuario y la contraseña, se determina si se permite al usuario continuar con los procesos de negocio posteriores.
Descripción de la interfaz validate
| Información de la interfaz | Descripción |
|---|---|
| Dirección de la interfaz | https://captcha-api.engagelab.com/validate |
| Método de solicitud | POST |
| Formato de solicitud | application/json |
| Tipo de respuesta | json |
Parámetros de la solicitud
| Nombre del parámetro | Tipo | Descripción | Origen |
|---|---|---|---|
| lot_number | string | Número de serie de verificación del servidor | Se transmite desde el frontend |
| captcha_output | string | Información de salida de la verificación | Se transmite desde el frontend |
| pass_token | string | Token de aprobación de la verificación | Se transmite desde el frontend |
| gen_time | string | Marca de tiempo de aprobación de la verificación | Se transmite desde el frontend |
| captcha_id | string | ID del escenario de verificación | Archivo de configuración de negocio; debe coincidir con el captchaId utilizado por el frontend |
| sign_token | string | Firma de verificación | Se genera del lado de negocio |
El sign_token se genera de la siguiente manera:
Utilizar el número de serie de verificación actual del usuario lot_number como mensaje original, emplear la clave privada de verificación del cliente captchaKey como clave, y aplicar el algoritmo hash hmac_sha256 para realizar un hash unidireccional del mensaje y la clave, a fin de generar la firma final.
Un ejemplo en código Java es el siguiente:
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
Ejemplo de cuerpo de la solicitud
{
"lot_number": "f26d13345c9980c7705b9111b9398a0f",
"captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
"sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
"pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
"gen_time": "1684826917",
"captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}
Parámetros de respuesta
| Nombre del parámetro | Tipo | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
| status | String | Sí | success | Estado de respuesta de la interfaz; success indica que la respuesta se ha realizado correctamente |
| data | Object | Sí | Consulte la descripción del campo data | Campo devuelto cuando la interfaz responde correctamente |
La descripción del campo data es la siguiente:
| Nombre del parámetro | Tipo | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
| result | String | Sí | success | Resultado de la verificación secundaria, success indica que la verificación se ha superado; otros valores indican que la verificación ha fallado |
| reason | String | Sí | "" | Descripción del resultado de la verificación |
| captcha_args | Object | Sí | {} | Información devuelta al cliente, que incluye principalmente algunos resultados de estrategia |
El identificador de aprobación de la verificación es: el campo status de la respuesta es success y el campo result también es success
Los parámetros incluidos en captcha_args son los siguientes:
| Nombre del parámetro | Tipo | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
| model_cnn | int | Sí | 0 | Resultado de evaluación del modelo CNN de la trayectoria de deslizamiento; 0 indica trayectoria normal y 1 indica trayectoria anómala |
| model_probability | int | Sí | 0 | Si se trata de una solicitud de plataforma de captcha; 0 para usuarios normales y 1 para solicitudes de captcha; se recomienda gestionarlo en tiempo real |
| used_type | String | Sí | slide | Método de verificación utilizado en esta ocasión |
| web_simulator | int | Sí | 0 | Si se trata de un simulador; 0 indica un navegador normal y 1 indica un simulador |
| user_ip | String | Sí | "127.0.0.1" | IP del usuario cuando la verificación se aprueba |
| user_referer | String | Sí | "" | Referer de la solicitud del usuario cuando la verificación se aprueba |
| cnn_records | int | Sí | 0 | Si hubo una única predicción de trayectoria anómala durante todo el proceso |
| user_agent | String | Sí | "User-Agent" | UA del usuario cuando la verificación se aprueba |
| lot_number | String | Sí | "9b57c5289e" | Número de serie de verificación del usuario |
Nota: model_probability es el identificador de captcha. Cuando este identificador es 1, se reconoce como una solicitud de captcha anómala. Se recomienda que el lado de negocio lo gestione posteriormente.
Cuando el campo result en data es success, indica que el resultado de la verificación se ha superado
Ejemplo de respuesta
{
"status": "success",
"data": {
"captcha_args": {
"cnn_records": 0,
"lot_number": "a989b864ad08cc08f270c22d9ab1fba0",
"model_cnn": 0,
"model_probability": 0,
"used_type": "slide",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
"user_ip": "59.174.224.96",
"user_referer": "http://127.0.0.1:5000/",
"web_simulator": 0
},
"reason": "validate success",
"result": "success"
}
}
Ejemplo de integración de código Java
Si tomamos como ejemplo el desarrollo del lado de negocio en lenguaje Java, el código de referencia es el siguiente:
package com.engagelab.demo.controller;
import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
import org.json.JSONObject;
import org.springframework.http.*;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;
import java.util.HashMap;
import java.util.Map;
@RestController
public class MainController {
@RequestMapping(value = "/login", method = {RequestMethod.GET})
public String userLogin(@RequestParam Map<String, String> getParams) {
// 1. Initialize parameter information, needs to be consistent with the captchaId used by the frontend, or can be placed in the configuration file
String captchaId = "37830cbb24f5a2134d39c7cf3093bc14";
String captchaKey = "ab8aeb88a3c30e170ab04af8ada6e6ec";
// domain is the domain name of EngageLab's verification code service
String domain = "https://captcha-api.engagelab.com";
// 2. Get the verification serial number and other parameters passed from the frontend after user verification
String lotNumber = getParams.get("lot_number");
String captchaOutput = getParams.get("captcha_output");
String passToken = getParams.get("pass_token");
String genTime = getParams.get("gen_time");
// 3. Generate signature
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
// 4. Upload verification parameters to the secondary verification interface to validate the user verification status
Map<String, String> queryParams = new HashMap<>();
queryParams.put("captcha_id", captchaId);
queryParams.put("lot_number", lotNumber);
queryParams.put("captcha_output", captchaOutput);
queryParams.put("pass_token", passToken);
queryParams.put("gen_time", genTime);
queryParams.put("sign_token", signToken);
String url = String.format(domain + "/validate");
SimpleClientHttpRequestFactory clientHttpRequestFactory = new SimpleClientHttpRequestFactory();
clientHttpRequestFactory.setConnectTimeout(3000); // Set connection timeout
clientHttpRequestFactory.setReadTimeout(1500); // Set Read timeout
RestTemplate client = new RestTemplate();
client.setRequestFactory(clientHttpRequestFactory);
JSONObject responseJsonObject = new JSONObject();
try {
RequestEntity<Map<String, String>> requestEntity = RequestEntity.post(url).accept(MediaType.APPLICATION_JSON).body(queryParams);
ResponseEntity<String> response = client.exchange(requestEntity, String.class);
String resBody = response.getBody();
responseJsonObject = new JSONObject(resBody);
} catch (Exception e) {
responseJsonObject.put("status", "success");
responseJsonObject.put("data", new JSONObject("{\"result\": \"success\", \"reason\": \"request captcha api fail\"}"));
}
JSONObject res = new JSONObject();
String status = responseJsonObject.getString("status");
if (status.equals("success")) {
String data = responseJsonObject.getJSONObject("data").getString("result");
if (data.equals("success")) {
res.put("login", "success");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
} else {
res.put("login", "fail");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
}
JSONObject captchaArgs = responseJsonObject.getJSONObject("data").getJSONObject("captcha_args");
Integer model_probability = captchaArgs.getInt("model_probability");
System.out.println("The captcha recognition result is: " + model_probability);
} else {
res.put("login", "fail");
res.put("reason", "captcha verify fail");
}
return res.toString();
}
}
