Documentación de ScraperFly
Inicio rápido: autentíquese con su clave API, obtenga HTML, habilite la renderización de JS, elija formatos de salida y use proxies premium. ScraperFly es intencionalmente directo: envíe una URL, elija los controles que necesita y maneje el HTML devuelto, texto limpio, Markdown, JSON, captura de pantalla o PDF en su aplicación.
/api/v1
Utilice parámetros de consulta GET o POST JSON. Ambas formas de solicitud devuelven el mismo resultado.
apikey encabezado
Mantenga las claves del lado del servidor y gírelas desde el panel de control siempre que sea necesario.
1 a 25 créditos
Los costos dependen del enrutamiento premium, la renderización del navegador y la salida de archivos visuales.
Costos de Créditos & Solicitudes Fallidas
Los créditos dependen de la configuración de la solicitud (proxies premium, renderización de JS, etc.) y del resultado final. En la práctica, cada solicitud cuesta entre 1 y 25 créditos.
| Premium | Renderizar | Costo en créditos |
|---|---|---|
| false | false | 1 |
| false | true | 5 |
| true | false | 10 |
| true | true | 25 |
- Comience con
premium=false,render=falsepara objetivos fáciles. - Habilite
render=truesolo para páginas con mucho JS (React/Vue/Next.js). - Utilice
countrycuando el objetivo cambie por ubicación. - Si se encuentra con páginas de desafío, intente
premium=true+render=true.
Uso Básico
Obtenga el HTML de una página objetivo. Para un uso básico, solo necesita su apikey y una url. Esto generalmente utiliza proxies estándar y cuesta 1 crédito. La respuesta es el HTML sin procesar de la página. Si necesita datos estructurados, analice el HTML en su lado (Cheerio/BeautifulSoup/etc.).
curl "https://scraperfly.com/api/v1?url=https://example.com" \
-H "apikey: YOUR_API_KEY_HERE"
// Node 18+ tiene fetch incorporado
const res = await fetch("https://scraperfly.com/api/v1?url=https://example.com", {
headers: { apikey: "YOUR_API_KEY_HERE" }
});
const html = await res.text();
console.log(html);
import requests
res = requests.get(
"https://scraperfly.com/api/v1",
params={"url": "https://example.com"},
headers={"apikey": "YOUR_API_KEY_HERE"}
)
print(res.text)
<?php
$endpoint = "https://scraperfly.com/api/v1";
$url = "https://example.com";
$ch = curl_init($endpoint . "?url=" . urlencode($url));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["apikey: YOUR_API_KEY_HERE"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$html = curl_exec($ch);
curl_close($ch);
echo $html;
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
endpoint := "https://scraperfly.com/api/v1?url=" + url.QueryEscape("https://example.com")
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("apikey", "YOUR_API_KEY_HERE")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))
}
using System.Net.Http;
var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");
var endpoint = "https://scraperfly.com/api/v1?url=https://example.com";
var html = await http.GetStringAsync(endpoint);
Console.WriteLine(html);
import java.net.http.*;
import java.net.URI;
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://scraperfly.com/api/v1?url=https://example.com"))
.header("apikey", "YOUR_API_KEY_HERE")
.GET()
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"
endpoint = URI("https://scraperfly.com/api/v1?url=https://example.com")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"
res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
http.request(req)
end
puts res.body
Parámetros de Solicitud
Utilice el punto final canónico GET /api/v1 con parámetros de consulta, o POST /api/v1 con los mismos campos en un cuerpo JSON. Comience con url + format, luego agregue opciones de proxy, renderizar, viewport o archivo solo cuando el objetivo las necesite.
Solicitud principal
| Parámetro | Tipo | Descripción |
|---|---|---|
url | requerido | URL del sitio web objetivo que desea raspar, por ejemplo, url=https://example.com. |
premium | opcional, booleano | Utiliza grupos de proxies de mayor calidad para objetivos más difíciles. Cuesta más créditos. |
country | opcional | País del proxy solicitado, por ejemplo US. Los registros de uso almacenan el país y la ciudad del proxy real. |
render | opcional, booleano | Renderización de navegador sin cabeza para páginas que requieren JavaScript. Se habilita automáticamente para screenshot y pdf. |
keep_headers | opcional, booleano | Transmita sus propios encabezados (cookies, user-agent, accept-language, etc.). |
format | opcional | Formato de salida: html, text, markdown, json, screenshot, o pdf. |
Formatos de salida
| formato | Respuesta | Cuándo usar |
|---|---|---|
html | HTML | Por defecto. Úselo cuando desee la fuente sin procesar o HTML renderizado para su propio analizador. |
text | texto plano | Úselo cuando necesite texto limpio y legible sin ruido de navegación/disposición. |
markdown | Markdown | Úselo para indicaciones de LLM, RAG, documentos, resúmenes e indexación. |
json | JSON | Úselo para metadatos, título, encabezados, enlaces, texto limpio y Markdown en una respuesta. |
screenshot | archivo de imagen | Siempre utiliza Chromium. Úselo para prueba visual, monitoreo, QA o revisión del cliente. |
pdf | archivo PDF | Siempre utiliza Chromium. Úselo para registros de página duraderos, auditorías, informes o revisión fuera de línea. |
Renderizado de navegador y viewport
Estas opciones solo importan cuando render=true, format=screenshot, o format=pdf. Si la renderización está desactivada y la salida es texto/html/markdown/json, se ignoran las opciones de viewport.
| Parámetro | Tipo / predeterminado | Descripción |
|---|---|---|
render_wait | ms, predeterminado 0 | Espera adicional después de la carga inicial de la página antes de la captura/extracción. Rango: 0..15000. No incluye el tiempo de inicio de Chromium o de navegación. |
viewport_width | número, predeterminado 1365 | Ancho del viewport del navegador. El modo CSS acepta 320..3840; el modo Windows acepta píxeles de pantalla física hasta 7680. |
viewport_height | número, predeterminado 768 | Altura del viewport del navegador. El modo CSS acepta 320..4000; el modo Windows acepta píxeles de pantalla física hasta 8000. |
pixels | css o windows | css significa que los valores del viewport son píxeles CSS del navegador. windows significa que pasa los píxeles de la configuración de pantalla de Windows y ScraperFly los convierte usando display_scale. |
display_scale | número, predeterminado 150 | Usado solo con pixels=windows. Acepta 125, 150, 200 o 1.25, 1.5, 2. |
Opciones de archivo visual
Estas opciones se aplican solo a format=screenshot y format=pdf. Las respuestas exitosas también se guardan como artefactos descargables en el registro de solicitudes.
| Parámetro | Tipo / predeterminado | Descripción |
|---|---|---|
file_type | jpg para captura de pantalla, pdf para PDF | La captura de pantalla admite jpg, jpeg, png, webp. PDF admite solo pdf. BMP no es compatible. |
download | booleano | true devuelve Content-Disposition: attachment. false devuelve una vista previa en línea cuando el cliente lo admite. |
filename | cadena | Nombre de archivo opcional. La extensión se normaliza a partir de file_type. |
Ejemplos de Postman
Pegue estos directamente en Postman como ejemplos de URL o referencias de cuerpo de solicitud. Los parámetros de consulta GET y el cuerpo JSON de POST utilizan los mismos nombres de opción.
Markdown de una página simple
Utilice una URL GET simple cuando desee una verificación rápida de Postman para una salida de Markdown limpia.
https://scraperfly.com/api/v1?url=https://example.com&format=markdown
PDF con viewport de tamaño Windows
Utilice controles de viewport cuando un archivo visual deba coincidir con un tamaño de pantalla de escritorio real.
https://scraperfly.com/api/v1?url=https://example.com&format=pdf&premium=true&render_wait=10000&viewport_width=2560&viewport_height=1600&pixels=windows&display_scale=150&file_type=pdf&download=true
Cuerpo JSON de POST con las mismas opciones
Cambie a POST cuando la solicitud tenga muchas opciones y un cuerpo JSON sea más fácil de revisar o almacenar.
POST https://scraperfly.com/api/v1
apikey: YOUR_API_KEY_HERE
content-type: application/json
{
"url": "https://example.com",
"format": "screenshot",
"premium": true,
"render_wait": 10000,
"viewport_width": 1280,
"viewport_height": 720,
"pixels": "css",
"file_type": "jpg",
"download": true
}
Ejemplo Avanzado (Premium + Render + Encabezados + País)
Utilice esta configuración cuando un sitio bloquee el tráfico estándar. Habilita el enrutamiento de proxy premium, ejecuta un navegador sin cabeza, mantiene encabezados seleccionados y solicita un proxy específico del país. Si una página aún falla, intente nuevamente con retroceso exponencial, reduzca la concurrencia o pruebe otro país.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE" \
-H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36" \
-H "Cookie: SESSIONID=27382738"
const params = new URLSearchParams({
url: "https://example.com",
premium: "true",
render: "true",
keep_headers: "true",
country: "US"
});
const res = await fetch("https://scraperfly.com/api/v1?" + params.toString(), {
headers: {
apikey: "YOUR_API_KEY_HERE",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36",
"Cookie": "SESSIONID=27382738"
}
});
const html = await res.text();
console.log(html);
import requests
params = {
"url": "https://example.com",
"premium": "true",
"render": "true",
"keep_headers": "true",
"country": "US"
}
headers = {
"apikey": "YOUR_API_KEY_HERE",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36",
"Cookie": "SESSIONID=27382738"
}
res = requests.get("https://scraperfly.com/api/v1", params=params, headers=headers, timeout=30)
print(res.text)
<?php
$endpoint = "https://scraperfly.com/api/v1";
$params = http_build_query([
"url" => "https://example.com",
"premium" => "true",
"render" => "true",
"keep_headers" => "true",
"country" => "US",
]);
$ch = curl_init($endpoint . "?" . $params);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"apikey: YOUR_API_KEY_HERE",
"User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36",
"Cookie: SESSIONID=27382738",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$html = curl_exec($ch);
curl_close($ch);
echo $html;
package main
import (
"fmt"
"io"
"net/http"
"net/url"
"time"
)
func main() {
q := url.Values{}
q.Set("url", "https://example.com")
q.Set("premium", "true")
q.Set("render", "true")
q.Set("keep_headers", "true")
q.Set("country", "US")
endpoint := "https://scraperfly.com/api/v1?" + q.Encode()
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("apikey", "YOUR_API_KEY_HERE")
req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36")
req.Header.Set("Cookie", "SESSIONID=27382738")
client := &http.Client{ Timeout: 30 * time.Second }
resp, err := client.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))
}
using System.Net.Http;
using System.Net.Http.Headers;
var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");
http.DefaultRequestHeaders.Add("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36");
http.DefaultRequestHeaders.Add("Cookie", "SESSIONID=27382738");
var endpoint = "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US";
var html = await http.GetStringAsync(endpoint);
Console.WriteLine(html);
import java.net.http.*;
import java.net.URI;
HttpClient client = HttpClient.newBuilder()
.followRedirects(HttpClient.Redirect.NORMAL)
.build();
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US"))
.header("apikey", "YOUR_API_KEY_HERE")
.header("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36")
.header("Cookie", "SESSIONID=27382738")
.GET()
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"
endpoint = URI("https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"
req["User-Agent"] = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/120 Safari/537.36"
req["Cookie"] = "SESSIONID=27382738"
res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
http.read_timeout = 30
http.request(req)
end
puts res.body
Renderización de JS (Ejemplo Rápido)
Para páginas con mucho JavaScript, establezca render=true. Use esto cuando el HTML fuente no contenga los datos y la página necesite ejecución del navegador primero.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
Autenticación & Créditos Restantes
ScraperFly utiliza claves API para autorización. Recomendado: envíe su clave a través del encabezado apikey. El punto final /status devuelve sus créditos restantes e información de la cuenta.
curl "https://scraperfly.com/api/v1/status" \
-H "apikey: YOUR_API_KEY_HERE"
const res = await fetch("https://scraperfly.com/api/v1/status", {
headers: { apikey: "YOUR_API_KEY_HERE" }
});
const data = await res.json();
console.log(data);
import requests
res = requests.get("https://scraperfly.com/api/v1/status", headers={"apikey": "YOUR_API_KEY_HERE"})
print(res.json())
<?php
$ch = curl_init("https://scraperfly.com/api/v1/status");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["apikey: YOUR_API_KEY_HERE"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$out = curl_exec($ch);
curl_close($ch);
echo $out;
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://scraperfly.com/api/v1/status", nil)
req.Header.Set("apikey", "YOUR_API_KEY_HERE")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(string(b))
}
using System.Net.Http;
var http = new HttpClient();
http.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY_HERE");
var json = await http.GetStringAsync("https://scraperfly.com/api/v1/status");
Console.WriteLine(json);
import java.net.http.*;
import java.net.URI;
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://scraperfly.com/api/v1/status"))
.header("apikey", "YOUR_API_KEY_HERE")
.GET()
.build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
require "net/http"
require "uri"
endpoint = URI("https://scraperfly.com/api/v1/status")
req = Net::HTTP::Get.new(endpoint)
req["apikey"] = "YOUR_API_KEY_HERE"
res = Net::HTTP.start(endpoint.host, endpoint.port, use_ssl: endpoint.scheme == "https") do |http|
http.request(req)
end
puts res.body
Manejo de Errores
Los errores se devuelven como JSON con una forma estable. Siempre inspeccione el estado HTTP + error.code para decidir si volver a intentar.
{
"error": {
"code": "validation_error",
"status": 422,
"context": [
{
"url": {
"type": "invalid_url",
"message": "missing url"
}
}
]
}
}
Reintentar en red/429/temporal 5xx. No reintentar en URL inválida o clave API inválida.
Códigos de Error Comunes
| HTTP | Tipo | Significado |
|---|---|---|
| 400 | missing_url | No se proporcionó un parámetro url válido. |
| 400 | invalid_url | Valor inválido en url. |
| 401 | missing_api_key | No se suministró clave API. |
| 403 | invalid_api_key | La clave API es inválida o está deshabilitada. |
| 403 | forbidden | No hay suficientes créditos o no hay acceso a la función. |
| 429 | rate_limited | Demasiadas solicitudes concurrentes. Reduzca la velocidad o actualice. |
| 429 | usage_limit_reached | Límite de plan/mensual alcanzado. |
| 500 | internal_error | Error del servidor. Vuelva a intentar con retroceso. |
Casos de Uso Comunes
Mantenga los patrones de producción comunes en un bloque tabulado: comience simple, luego agregue enrutamiento, renderización, encabezados o retroceso solo cuando el objetivo demuestre que los necesita.
1) Proxies Premium
Habilite premium=true para objetivos más difíciles. Agregue country cuando la respuesta cambie por mercado o ubicación.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE"
2) Encabezados Personalizados (User-Agent / Cookies)
Utilice keep_headers=true cuando el contexto del objetivo sea importante y necesite pasar encabezados de solicitud seleccionados.
curl "https://scraperfly.com/api/v1?url=https://example.com&keep_headers=true" \
-H "apikey: YOUR_API_KEY_HERE" \
-H "User-Agent: Mozilla/5.0" \
-H "Accept-Language: en-US,en;q=0.9" \
-H "Cookie: SESSIONID=27382738"
3) Renderización de JS
Para SPA, Next.js y páginas construidas en el navegador, establezca render=true para que ScraperFly espere la salida de JavaScript antes de extraer la respuesta.
curl "https://scraperfly.com/api/v1?url=https://quotes.toscrape.com/js&render=true" \
-H "apikey: YOUR_API_KEY_HERE"
4) Anti-bot & Páginas de Desafío
Si recibe contenido de desafío o bloqueado, combine enrutamiento premium, renderización de navegador, encabezados permitidos realistas, menor concurrencia y retroceso de reintento.
curl "https://scraperfly.com/api/v1?url=https://example.com&premium=true&render=true&keep_headers=true&country=US" \
-H "apikey: YOUR_API_KEY_HERE" \
-H "User-Agent: Mozilla/5.0" \
-H "Accept-Language: en-US,en;q=0.9"