From 37ebc63f826c26a53318b9098a573a019c72513c Mon Sep 17 00:00:00 2001 From: webbrain-one <295484252+webbrain-one@users.noreply.github.com> Date: Sun, 2 Aug 2026 19:19:26 +0300 Subject: [PATCH] docs: add Spanish README --- README.es-ES.md | 281 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 README.es-ES.md diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..82a45d5 --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,281 @@ + + +# Go-Cloudscraper + +[![Go Report Card](https://goreportcard.com/badge/github.com/Advik-B/cloudscraper)](https://goreportcard.com/report/github.com/Advik-B/cloudscraper) +[![Go.Dev reference](https://img.shields.io/badge/go.dev-reference-blue?logo=go&logoColor=white)](https://pkg.go.dev/github.com/Advik-B/cloudscraper/lib) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +Una portación completa e independiente para Go de la popular biblioteca Python [`cloudscraper`](https://github.com/VeNoMouS/cloudscraper), diseñada para eludir la protección anti-bots de Cloudflare. + +Esta biblioteca está escrita en Go puro y busca tener **ninguna dependencia de entorno de ejecución externo como Node.js** de forma predeterminada. Simula internamente un entorno de navegador para resolver incluso los desafíos modernos de JavaScript, haciendo que tu aplicación Go compilada sea verdaderamente portátil y autónoma. Para casos de uso avanzados, también admite delegar la ejecución de JS a entornos de ejecución externos como Node.js, Deno o Bun. + +## Características + +Esta biblioteca busca tener paridad de funcionalidades con la versión original de Python, proporcionando una solución robusta y lista para producción para aplicaciones Go. + +| Característica | Estado | Descripción | +| :--- | :--- | :--- | +| **Binario Independiente** | ✅ **Completo** | Usa `go:embed` y un intérprete de JS en Go puro (`otto`) de forma predeterminada. No se requiere Node.js. | +| **Entornos de Ejecución JS Externos**| ✅ **Completo** | Permite delegar la ejecución de JS a **Node.js, Deno o Bun** para máxima compatibilidad. | +| **Gestión de Sesiones y Cookies** | ✅ **Completo** | Administra automáticamente un `cookiejar` para manejar las cookies de sesión de Cloudflare. | +| **Resolvedor de Desafíos JS (v1)** | ✅ **Completo** | Resuelve internamente los clásicos desafíos basados en matemáticas de JavaScript. | +| **Resolvedor de Desafíos JS (v2/v3)** | ✅ **Completo** | Simula un DOM de navegador dentro de Go para resolver desafíos modernos de VM de JS. | +| **Modo Furtivo (Stealth)** | ✅ **Completo** | Aplica retrasos similares a los humanos, randomización de encabezados y peculiaridades específicas de navegadores. | +| **Gestión de Proxies** | ✅ **Completo** | Incluye un administrador de proxies seguro para hilos con rotación secuencial, aleatoria e inteligente. | +| **Recuperación ante 403 Prohibido** | ✅ **Completo** | Detecta y se recupera automáticamente de errores `403` refrescando la sesión. | +| **Marco de Trabajo para Resolvedores de Captcha** | ✅ **Extensible** | Proporciona una interfaz `Solver` y una implementación funcional de `2captcha`. | +| **Configuración Detallada** | ✅ **Completo** | Utiliza un patrón de opciones funcionales idiomático para una configuración fácil y detallada. | + +## Instalación + +Para obtener la última versión de la biblioteca, usa `go get`: +```bash +go get github.com/Advik-B/cloudscraper/lib +``` + +## Uso Básico + +La forma más simple de usar esto es hacer una solicitud GET a un sitio protegido. + +```go +package main + +import ( + "fmt" + "io" + "log" + "github.com/Advik-B/cloudscraper/lib" +) + +func main() { + // Create a new scraper with default settings + sc, err := cloudscraper.New() + if err != nil { + log.Fatalf("Failed to create scraper: %v", err) + } + + // Make a GET request + resp, err := sc.Get("https://nowsecure.nl") // A site known to be protected by Cloudflare + if err != nil { + log.Fatalf("Request failed: %v", err) + } + defer resp.Body.Close() + + fmt.Printf("Status: %s\n", resp.Status) + + // Read and print the body + body, err := io.ReadAll(resp.Body) + if err != nil { + log.Fatalf("Failed to read response body: %v", err) + } + + // Print a preview of the response + preview := string(body) + if len(preview) > 500 { + preview = preview[:500] + } + fmt.Printf("Body Preview:\n%s...\n", preview) +} +``` + +## Configuración Avanzada + +`go-cloudscraper` utiliza un patrón de opciones funcionales para la configuración, lo que te permite personalizar fácilmente su comportamiento. + +### Uso de Entornos de Ejecución JavaScript Externos + +De forma predeterminada, `go-cloudscraper` usa un intérprete de JavaScript basado en Go integrado (`otto`) para máxima portabilidad. Sin embargo, para los desafíos de Cloudflare más complejos o futuros, es posible que obtengas mejores resultados usando un entorno de ejecución JavaScript externo y completo como Node.js, Deno o Bun. + +Para usar un entorno de ejecución externo, debe estar instalado y disponible en el `PATH` de tu sistema. + +```go +import ( + "github.com/Advik-B/cloudscraper/lib" + "github.com/Advik-B/cloudscraper/lib/js" +) + +sc, err := cloudscraper.New( + // Use type-safe constants for the runtime. + // Can be js.Node, js.Deno, or js.Bun. + cloudscraper.WithJSRuntime(js.Node), +) +``` + +### Uso de Proxies + +Proporciona una `slice` de URLs de proxy. El administrador soporta rotación `Sequential` y `Random`. + +```go +import ( + "time" + "github.com/Advik-B/cloudscraper/lib" + "github.com/Advik-B/cloudscraper/lib/proxy" +) + +proxies := []string{ + "http://user:pass@proxy1.com:8080", + "http://user:pass@proxy2.com:8080", +} + +sc, err := cloudscraper.New( + cloudscraper.WithProxies(proxies, proxy.Random, 5*time.Minute), +) +``` + +### Uso de un Resolvedor de Captcha + +Si un sitio presenta un desafío de reCaptcha o Turnstile, puedes configurar un resolvedor. + +```go +import ( + "github.com/Advik-B/cloudscraper/lib" + "github.com/Advik-B/cloudscraper/lib/captcha" +) + +// Initialize your chosen captcha solver +solver := captcha.NewTwoCaptchaSolver("YOUR_2CAPTCHA_API_KEY") + +sc, err := cloudscraper.New( + cloudscraper.WithCaptchaSolver(solver), +) +``` + +### Personalización del Navegador y Modo Furtivo + +Puedes cambiar la identidad del navegador y ajustar las opciones de furtividad para adaptarse mejor a tu objetivo. + +```go +import ( + "time" + "github.com/Advik-B/cloudscraper/lib" + "github.com/Advik-B/cloudscraper/lib/stealth" + useragent "github.com/Advik-B/cloudscraper/lib/user_agent" +) + +sc, err := cloudscraper.New( + // Pretend to be Firefox on Linux + cloudscraper.WithBrowser(useragent.Config{ + Browser: "firefox", + Platform: "linux", + Desktop: true, + }), + // Configure stealth delays + cloudscraper.WithStealth(stealth.Options{ + Enabled: true, + MinDelay: 1 * time.Second, + MaxDelay: 5 * time.Second, + HumanLikeDelays: true, + }), +) +``` + +### Ejemplo de Configuración Completa + +Así es como puedes combinar múltiples opciones para crear una instancia de scraper altamente personalizada. + +```go +package main + +import ( + "fmt" + "log" + "time" + + "github.com/Advik-B/cloudscraper/lib" + "github.com/Advik-B/cloudscraper/lib/js" + "github.com/Advik-B/cloudscraper/lib/proxy" + "github.com/Advik-B/cloudscraper/lib/stealth" + useragent "github.com/Advik-B/cloudscraper/lib/user_agent" +) + +func main() { + var scraperOptions []cloudscraper.ScraperOption + + // Use an external JS runtime for better challenge compatibility + scraperOptions = append(scraperOptions, cloudscraper.WithJSRuntime(js.Node)) + + // Add proxies with random rotation + scraperOptions = append(scraperOptions, cloudscraper.WithProxies( + []string{"http://user:pass@proxy1:8080", "http://user:pass@proxy2:8080"}, + proxy.Random, + 5*time.Minute, + )) + + // Customize the browser to appear as Chrome on Windows + scraperOptions = append(scraperOptions, cloudscraper.WithBrowser(useragent.Config{ + Browser: "chrome", + Platform: "windows", + })) + + // Customize session handling + scraperOptions = append(scraperOptions, cloudscraper.WithSessionConfig( + true, // Auto-refresh on 403s + 30*time.Minute, // Refresh session every 30 mins + 5, // Max 403 retries + )) + + // Create the scraper with all our options + sc, err := cloudscraper.New(scraperOptions...) + if err != nil { + log.Fatalf("Failed to create scraper: %v", err) + } + + // Use the scraper... + resp, err := sc.Get("https://nowsecure.nl") + if err != nil { + log.Fatal(err) + } + defer resp.Body.Close() + + fmt.Println("Success:", resp.Status) +} +``` + +## ¿Cómo Funciona? + +Esta biblioteca imita el flujo de interacción que tendría un navegador real con un sitio protegido por Cloudflare: + +1. **Solicitud Inicial:** Se realiza una solicitud inicial a la URL objetivo. +2. **Detección de Desafío:** El scraper verifica la respuesta. Si recibe un `503 Service Unavailable` o `403 Forbidden` con los encabezados y cuerpo característicos de Cloudflare, identifica un desafío. +3. **Análisis del Desafío:** Analiza el HTML para determinar el tipo de desafío: + * **Desafío JavaScript v1:** Un problema basado en matemáticas ofuscado en JS. + * **Desafío JavaScript v2/v3:** Un script más complejo que espera un entorno similar al de un navegador. + * **reCaptcha/Turnstile:** Requiere un token de CAPTCHA. +4. **Resolución:** + * Para los **desafíos v1 y v2/v3**, utiliza el **Motor JavaScript** configurado (ya sea el `otto` integrado o un entorno de ejecución externo como `node`) con un entorno DOM simulado para ejecutar los scripts y calcular la respuesta correcta. + * Para los **desafíos de Captcha**, delega la clave del sitio al `CaptchaSolver` configurado para obtener un token. +5. **Envío y Manejo de Cookies:** La respuesta resuelta o el token se envía de vuelta a Cloudflare. Si es exitoso, Cloudflare devuelve una cookie `cf_clearance`. El `cookiejar` interno del scraper almacena esta cookie para solicitudes posteriores al sitio. +6. **Éxito:** La solicitud original se reintenta, ahora con la cookie de acceso, y debería tener éxito. + +## Convención de Versiones + +Las etiquetas en este proyecto siguen un formato de nomenclatura estructurado: + +``` +v-pyv +``` + +* `v` se refiere a la versión de esta biblioteca Go. +* `pyv` indica la versión del proyecto original Python `cloudscraper` que fue portado o cuyas funcionalidades se igualaron. + +Por ejemplo: + +``` +v1.0-pyv3.0.0 +``` + +Esto significa: + +* La portación para Go está en la versión **1.0**. +* Refleja las características y el comportamiento de la versión **3.0.0** de `cloudscraper` para Python. + +Este sistema de doble etiqueta ayuda a los desarrolladores a identificar fácilmente la compatibilidad con el paquete original de Python. + +## Contribuir + +¡Las contribuciones son bienvenidas! Si encuentras un error, tienes una solicitud de función o quieres mejorar la biblioteca, no dudes en abrir un issue o enviar un pull request. + +## Licencia + +Este proyecto está licenciado bajo la Licencia MIT.