Skip to content

docs: add Spanish README #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
webbrain-one wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: add Spanish README #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 281 additions & 0 deletions README.es-ES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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<library-version>-pyv<cloudscraper-python-version>
```

* `v<library-version>` se refiere a la versión de esta biblioteca Go.
* `pyv<cloudscraper-python-version>` 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.