TL;DR
- La API de una sola página actual de Firecrawl es
POST https://api.firecrawl.dev/v2/scrape, autenticada con una clave API Bearer. - El array
formatsdetermina si la respuesta contiene Markdown, HTML, enlaces, capturas de pantalla, JSON estructurado u otros artefactos soportados. - Dominar el endpoint de raspado de Firecrawl significa validar el sobre de respuesta y la semántica de la página, no simplemente recibir un
200HTTP. - Usa
onlyMainContent, controles de caché, tiempo de espera, ubicación y acciones limitadas de manera deliberada; la interacción compleja pertenece al endpoint Interact de Firecrawl. - Compara las API de raspado gestionadas en precisión de página utilizable, diagnósticos, latencia y modelo de facturación contra tu propio conjunto objetivo.
Lo que Hace el Endpoint de Raspado de Firecrawl
El endpoint de raspado de Firecrawl convierte una URL conocida en una o más representaciones de página solicitadas. Firecrawl maneja la obtención y el renderizado del navegador en su infraestructura, y luego devuelve los artefactos seleccionados a través de formats. Es la operación adecuada de Firecrawl cuando ya conoces la URL de la página; el descubrimiento del sitio pertenece a una operación de rastreo, mientras que el comportamiento de navegador de varios pasos pertenece cada vez más a Interact.
La documentación actual del endpoint de raspado de Firecrawl documenta url como requerido y la autenticación Bearer como obligatoria. La más amplia introducción a Firecrawl v2 confirma la URL base https://api.firecrawl.dev y el manejo de estados HTTP convencionales.
Un endpoint gestionado elimina operaciones de navegador, proxy y renderizado de tu aplicación, pero no sabe lo que hace que un registro sea correcto para tu negocio. La aplicación aún necesita reglas de aceptación, identidad estable, políticas de retención y límites de reintentos. La misma división se aplica al evaluar Nstdata Crawl o una flota de navegadores interna.
Mapa de Solicitudes del Endpoint de Raspado de Firecrawl
La solicitud más pequeña contiene url; las solicitudes de producción normalmente solo añaden los controles que afectan la salida deseada.
| Campo | Qué cambia | Regla de decisión |
|---|---|---|
url | Página objetivo | Usa una URL HTTP(S) pública o autorizada |
formats | Artefactos devueltos | Solicita solo las salidas que usa el consumidor |
onlyMainContent | Reducción de contenido innecesario | Habilita para texto similar a artículos; prueba en páginas de la app |
waitFor | Retraso adicional de la página | Usa solo cuando un elemento o solicitud conocido necesita tiempo |
timeout | Ventana máxima de procesamiento | Mantén acotado; reintenta trabajo asíncrono o rediseña trabajo lento |
location | Contexto geográfico/idioma | Usa cuando la salida localizada sea parte de la aceptación |
storeInCache | Si Firecrawl puede almacenar la página | Desactiva cuando la retención o frescura lo requiera |
actions | Acciones simples de la página antes de la captura | Mantén deterministas; usa Interact para flujos complejos |
La referencia actual lista un tiempo de espera predeterminado de 60 segundos y un rango permitido de 1,000 a 300,000 milisegundos. Estos límites son sensibles a cambios, así que confírmalos antes de publicar validación del lado del cliente. Firecrawl también documenta controles de solo caché y reducción de retención; trátalos como elecciones de gobernanza de datos, no como interruptores de rendimiento.
Autenticación sin Filtrar la Clave API
Firecrawl espera Authorization: Bearer <token>. Coloca el token en un gestor de secretos o variable de entorno y nunca lo escribas en el código fuente, registros, capturas de pantalla, o en un archivo .env comprometido.
Los ejemplos a continuación usan $FIRECRAWL_API_KEY. Están verificadas según el esquema contra la documentación de primera parte actual, pero no pueden ejecutarse aquí sin una credencial de Firecrawl de propiedad del usuario. Ejecútalas contra una URL de prueba autorizada en tu entorno y captura la respuesta antes de adoptar el esquema.
Tutorial Detallado: Dominando las Llamadas del Endpoint de Raspado de Firecrawl
La progresión a continuación comienza con Markdown, luego añade salida estructurada y verificaciones operativas.
Método 1: Solicitar Markdown Limpio
Paso 1: Envía la solicitud más pequeña útil
curl --fail-with-body --silent --show-error \ --request POST 'https://api.firecrawl.dev/v2/scrape' \ --header "Authorization: Bearer $FIRECRAWL_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com/", "formats": ["markdown"], "onlyMainContent": true, "timeout": 60000 }'
--fail-with-body preserva el cuerpo del error del servidor mientras devuelve un estado de shell fallido para errores HTTP. No asumas que el éxito del comando prueba la corrección del contenido.
Paso 2: Valida el sobre de respuesta
Una respuesta exitosa de Firecrawl incluye un indicador de éxito de nivel superior y un objeto de datos. Verifica ambos antes de leer el artefacto:
const response = await fetch('https://api.firecrawl.dev/v2/scrape', { method: 'POST', headers: { Authorization: `Bearer ${process.env.FIRECRAWL_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://example.com/', formats: ['markdown'], onlyMainContent: true }) }); const payload = await response.json(); if (!response.ok || payload.success !== true) { throw new Error(payload.error ?? `Firecrawl falló con ${response.status}`); } const markdown = payload.data?.markdown; if (typeof markdown !== 'string' || markdown.trim().length < 80) { throw new Error('Firecrawl no devolvió un Markdown aceptable'); }
Una verificación de aceptación también debe buscar marcadores específicos del objetivo: un título, identificador del producto, fecha, encabezado de tabla u otro campo que demuestre que se devolvió la página prevista. Esto captura páginas de consentimiento, errores suaves y contenido que se renderizó pero no alcanzó el estado requerido.
Prueba una Alternativa de Scraping en ProducciónCompara Firecrawl con Nstdata Crawl en tus URLs reales, formatos y verificaciones de aceptación. Explora Nstdata Crawl |
Markdown
JSON
{
"title": "...", "url": "..." } Captura de Pantalla
|
Método 2: Solicitar JSON Estructurado
Paso 1: Definir un esquema estrecho
La extracción estructurada funciona mejor cuando el esquema describe solo los campos necesarios y sus tipos. Requiere un identificador de fuente estable cuando la página proporciona uno. Evita pedir a un modelo que infiera valores que no existen en la página.
{ "url": "https://example.com/product/123", "formats": [ { "type": "json", "prompt": "Extrae el registro de producto visible. Devuelve null para campos opcionales ausentes.", "schema": { "type": "object", "properties": { "name": {"type": "string"}, "sku": {"type": ["string", "null"]}, "availability": {"type": ["string", "null"]} }, "required": ["name"] } } ] }
Paso 2: Validar la semántica después de la validación del esquema
El cumplimiento del esquema prueba la forma, no la verdad. Rechaza un nombre genérico, normaliza el espacio en blanco, mapea la disponibilidad a un vocabulario aprobado y compara la URL de origen o SKU con la entrada del trabajo. Almacena el artefacto en bruto o un hash de contenido cuando los requisitos de auditoría lo permiten, para que un operador pueda explicar cómo se produjo el registro aceptado.
Método 3: Capturar una Captura de Pantalla o HTML para Diagnóstico
Markdown es eficiente para el uso de texto en etapas posteriores, pero puede ocultar por qué una extracción falló. Solicita una captura de pantalla cuando el estado visual importa y HTML cuando la estructura del DOM importa. No solicites grandes artefactos en cada trabajo recurrente a menos que tengan un propósito explícito de depuración, cumplimiento o archivo.
El punto final de Firecrawl admite acciones como esperar, hacer clic, escribir, desplazarse, capturas de pantalla y ejecución de JavaScript. La documentación actual recomienda el punto final Interact por separado para interacciones complejas. Mantén las acciones cortas y deterministas; los flujos de trabajo autenticados requieren permiso explícito y un manejo cuidadoso de secretos.
Caché, Frescura y Retención de Datos
El comportamiento de caché cambia tanto la frescura como el manejo de datos. Una respuesta en caché puede reducir la latencia, pero puede ser inaceptable para trabajos de inventario, política o monitoreo que requieren una observación actual. Por el contrario, storeInCache: false puede ser apropiado donde la página no debería ser retenida por el proveedor.
Registra la política de frescura solicitada con cada trabajo. Si un flujo de trabajo compara cambios, persiste el tiempo de colección y el hash de contenido; no trates la antigüedad del caché del proveedor como el tiempo de publicación de la página de origen. El artículo oficial de Firecrawl sobre uso de la API de extracción cubre formatos y ejemplos, pero la aceptación en producción sigue siendo específica de la aplicación.
Manejo de Errores, Límites de Tasa y Reintentos
Reintenta solo fallas que probablemente sean transitorias. Firecrawl documenta 429 para límites de tasa o concurrencia; honra cualquier orientación de reintento, limita los intentos y añade retroceso exponencial con jitter. Reintenta fallas selectas de 5xx, interrupciones de red y tiempos de espera, pero no vuelvas a intentar repetidamente URLs no válidas, fallas de autenticación o errores de esquema.
Haz que las escrituras en etapas posteriores sean idempotentes. Una clave de trabajo puede combinar URL normalizada, conjunto de formato solicitado, ventana de frescura y versión del esquema de extracción. Registra la clave del trabajo, estado HTTP, identificador de solicitud o extracción de Firecrawl cuando se devuelvan, tiempo transcurrido, tamaños de artefactos y resultado de validación. Nunca registres el token Bearer o encabezados de solicitud sensibles.
Si un equipo se mueve más tarde de la recuperación gestionada a enrutamiento de proxy directo, revisa cómo las sesiones de proxy rotativas afectan los reintentos y la consistencia de la página antes de cambiar el colector.
El público repositorio Firecrawl OpenAPI es útil para detectar cambios en el esquema, pero verifica la documentación desplegada v2 antes de generar clientes porque las revisiones del repositorio y de la API alojada pueden diferir.
Cuando Firecrawl Scrape No Es La Operación Correcta
Usa /scrape para una página conocida. Usa Firecrawl crawl cuando necesites descubrimiento limitado a través de enlaces internos, capacidades de lote para una lista conocida de muchas URLs, e Interact cuando el flujo de trabajo necesite un estado de navegador sostenido o varias acciones complejas. Una API de datos oficial sigue siendo preferible cuando expone los registros requeridos con permiso claro e identificadores estables.
Para la selección de proveedores, compare el resultado operativo completo. Nstdata Crawl se puede probar contra el mismo conjunto de URL y el arnés de aceptación. Nstdata Crawl está posicionado para la extracción de páginas y el rastreo de sitios limitados con múltiples artefactos y operaciones de tareas; la idoneidad depende de la representación exacta, requisitos geográficos, diagnósticos y de almacenamiento.
- Flujos de trabajo de páginas y sitios: la extracción de páginas síncrona o asíncrona se sitúa junto a la presentación de rastreo limitado y la consulta.
- Opciones de artefactos: Markdown, HTML, datos en bruto, enlaces, capturas de pantalla y PDFs sirven a diferentes consumidores y necesidades de depuración.
- Visibilidad de tareas: los ID de tareas y las verificaciones de estado respaldan páginas lentas y operaciones repetibles.
- Límite de selección: los equipos aún deben evaluar la tasa de páginas utilizables, latencia, completitud y costo por registro aceptado.
La guía sobre la extracción web versus el rastreo ayuda a elegir la operación, mientras que el resumen de herramientas de proxy explica cuándo un API gestionada es preferible a rutas de menor nivel.
Conclusión: Trata la Extracción como una Etapa de un Contrato de Datos
Dominar el endpoint de extracción de Firecrawl requiere más que elegir formats. Una integración confiable protege la clave API, limita el tiempo y las acciones, valida el sobre de respuesta, aplica pruebas de aceptación específicas para el objetivo y almacena los registros de manera idempotente.
Comience con cinco URL autorizadas representativas: una página estática, una página JavaScript, una redirección, un fallo esperado y una página sensible a la localidad. Mida la salida utilizable en lugar del éxito HTTP. Si el enrutamiento geográfico y las operaciones de proxy centralizadas se convierten más tarde en el cuello de botella, evalúe Nstdata Proxy Manager como la capa de control de red relacionada.
Experimente Nstdata — Comience su Prueba Gratuita Hoy
Preguntas Frecuentes
P: ¿Cuál es la URL del endpoint de extracción de Firecrawl?
El endpoint de página única actual de Firecrawl v2 es POST https://api.firecrawl.dev/v2/scrape. Envíe una clave API Bearer y un cuerpo JSON que contenga al menos url.
P: ¿Cuál es la diferencia entre la extracción y el rastreo de Firecrawl?
La extracción de Firecrawl procesa una URL conocida, mientras que el rastreo descubre y procesa múltiples páginas desde una URL inicial dentro de límites configurados. Elija en función de si el descubrimiento de URL es parte del trabajo.
P: ¿Qué formato de Firecrawl debería solicitar?
Solicite Markdown para texto e ingestión de LLM, HTML para procesamiento consciente del DOM, JSON para un registro definido y capturas de pantalla para evidencia visual. Solicite solo artefactos que un consumidor posterior o un proceso de diagnóstico utilice.
P: ¿Un HTTP 200 significa que la extracción de Firecrawl fue exitosa?
HTTP 200 por sí solo no prueba que los datos de página previstos sean utilizables. Verifique el campo de éxito de Firecrawl, el artefacto requerido, los metadatos de la página y los marcadores de contenido específicos del objetivo.
P: ¿Cómo debería manejar los errores 429 de Firecrawl?
Maneje las respuestas 429 de Firecrawl con retroceso exponencial limitado y jitter, respete la guía de reintento del servidor cuando se proporcione y reduzca la tasa de envío o concurrencia. Mantenga las escrituras idempotentes para que un reintento no pueda duplicar registros.
P: ¿Puede Firecrawl extraer páginas que requieren interacción?
Firecrawl admite acciones simples en solicitudes de extracción, pero su documentación actual dirige interacciones complejas del navegador al endpoint Interact. Utilice la interacción autenticada solo con autorización explícita y manejo seguro de cookies.
P: ¿Está Firecrawl facturado por solicitud?
Firecrawl utiliza un modelo de servicio basado en créditos cuya consumo varía según la operación y el formato. Consulte la documentación oficial actual de precios y facturación en lugar de incrustar un precio numérico cambiante en la lógica de la aplicación.
