logoDocumentación
Buscar

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.

image-20250427154654130

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.

image-20250427154749118

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.

image-20250427154933547

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:

  1. 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.
  2. 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);
              
              String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);

            
Este bloque de código se muestra en una ventana flotante
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" }
              
              {
    "lot_number": "f26d13345c9980c7705b9111b9398a0f",
    "captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
    "sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
    "pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
    "gen_time": "1684826917",
    "captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}

            
Este bloque de código se muestra en una ventana flotante
Parámetros de respuesta
Nombre del parámetro Tipo Obligatorio Ejemplo Descripción
status String success Estado de respuesta de la interfaz; success indica que la respuesta se ha realizado correctamente
data Object 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 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 "" Descripción del resultado de la verificación
captcha_args Object {} 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 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 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 slide Método de verificación utilizado en esta ocasión
web_simulator int 0 Si se trata de un simulador; 0 indica un navegador normal y 1 indica un simulador
user_ip String "127.0.0.1" IP del usuario cuando la verificación se aprueba
user_referer String "" Referer de la solicitud del usuario cuando la verificación se aprueba
cnn_records int 0 Si hubo una única predicción de trayectoria anómala durante todo el proceso
user_agent String "User-Agent" UA del usuario cuando la verificación se aprueba
lot_number String "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" } }
              
              {
    "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"
    }
}

            
Este bloque de código se muestra en una ventana flotante

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(); } }
              
              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();
    }
}

            
Este bloque de código se muestra en una ventana flotante
Icon Solid Transparent White Qiyu
Contacto