> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-docs-stripe-projects-agent-guidance.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Procesar
> Convierte documentos — PDF, Word, Excel, PowerPoint y más — en markdown limpio, contenido por página, bloques de diseño y JSON estructurado
Procesar convierte documentos en datos limpios y listos para LLM. Sube un archivo a
[`/parse`](/es/api-reference/endpoint/parse) — o apunta [`/scrape`](/es/features/scrape)
a la URL de un documento público — y obtén markdown, contenido por página, bloques de
diseño tipados o JSON estructurado.
* **Con reconocimiento del diseño**: encabezados, párrafos, tablas y fórmulas organizados en orden de lectura
* **Incluye documentos escaneados**: extracción de texto nativo con OCR como alternativa para páginas que solo contienen imágenes
* **Estructura basada en el documento**: bloques de diseño tipados con cuadros delimitadores y enlaces a rangos de caracteres en el markdown (PDF)
* **Cualquier formato habitual**: PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML
* Compatible con **retención de datos cero**
## Inicio rápido
```python Python theme={null}
from firecrawl import Firecrawl
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
doc = firecrawl.parse("./report.pdf")
print(doc.markdown)
```
```javascript Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.parse({
data: fs.readFileSync("./report.pdf"),
filename: "report.pdf",
});
console.log(doc.markdown);
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@./report.pdf' \
-F 'options={"formats":["markdown"]};type=application/json'
```
¿Tienes una **URL pública de un documento** en lugar de un archivo? [`/scrape`](/es/features/scrape)
detecta el tipo de archivo y lo procesa de forma idéntica — mismas opciones, misma salida:
`firecrawl.scrape("https://example.com/report.pdf")`.
## Respuesta
Los SDK devuelven el objeto de documento directamente. cURL devuelve la carga útil en JSON.
```json theme={null}
{
"success": true,
"data": {
"markdown": "# Annual Report\n\n...",
"metadata": {
"title": "Annual Report",
"numPages": 42,
"totalPages": 42,
"sourceFile": "report.pdf"
}
}
}
```
`numPages` es el número de páginas realmente procesadas; `totalPages` es el
número real de páginas del documento. Coinciden a menos que `maxPages` haya truncado el resultado; p. ej., procesar
un PDF de 100 páginas con `maxPages: 10` devuelve `numPages: 10` y `totalPages: 100`, por lo que
`totalPages > numPages` indica que la salida se truncó. `totalPages` se omite
cuando no se puede determinar el número de páginas.
Además del markdown del documento, tres salidas cubren los casos en los que una sola
cadena de markdown no es suficiente: [markdown por página](#per-page-markdown-pdf) y
[bloques de diseño](#layout-blocks-pdf) para documentos PDF, y
[JSON estructurado](#structured-json-output) para todos los formatos.
## Markdown físico por página (PDF)
Establece `pages: true` en el [parser de PDF](#pdf-options) y el documento también
incluye un array `pages` con el markdown de cada página física, útil cuando
necesitas saber de qué página proviene el contenido o procesar las páginas de forma independiente.
Sin costo adicional.
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
doc = firecrawl.parse(
"./report.pdf",
options=ScrapeOptions(parsers=[{"type": "pdf", "pages": True}]),
)
for page in doc.pages:
print(page.page_number, page.markdown[:80])
```
```js Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.parse(
{ data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
{ parsers: [{ type: "pdf", pages: true }] },
);
for (const page of doc.pages) {
console.log(page.pageNumber, page.markdown.slice(0, 80));
}
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@./report.pdf' \
-F 'options={"parsers":[{"type":"pdf","pages":true}]};type=application/json'
```
```json theme={null}
"pages": [
{ "pageNumber": 1, "markdown": "# Annual Report\n\n..." },
{ "pageNumber": 2, "markdown": "..." }
]
```
## Bloques de diseño (PDF)
Establece `blocks: true` en el [parser de PDF](#pdf-options) y el documento también
incluye un array `blocks`: para cada página, los bloques de diseño tipados que detectó
el motor de procesamiento, con geometría y procedencia. Es la contraparte estructurada
del markdown: úsala para la fundamentación de citas, superposiciones de resaltado
o auditar el contenido de un documento. Sin costo adicional.
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
doc = firecrawl.parse(
"./report.pdf",
options=ScrapeOptions(parsers=[{"type": "pdf", "blocks": True}]),
)
for page in doc.blocks:
for block in page.items:
print(page.page_number, block.type, block.bbox)
```
```js Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await firecrawl.parse(
{ data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
{ parsers: [{ type: "pdf", blocks: true }] },
);
for (const page of doc.blocks) {
for (const block of page.items) {
console.log(page.pageNumber, block.type, block.bbox);
}
}
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@./report.pdf' \
-F 'options={"parsers":[{"type":"pdf","blocks":true}]};type=application/json'
```
```json theme={null}
"blocks": [
{
"pageNumber": 1,
"width": 1700,
"height": 2200,
"status": "ok",
"items": [
{
"id": "p1.b0",
"type": "title",
"label": "doc_title",
"bbox": [0.118, 0.054, 0.882, 0.092],
"content": "# Annual Report",
"markdownSpan": [0, 15],
"readingOrder": 0,
"source": "native_text",
"confidence": { "layout": 0.97, "ocr": null }
}
]
}
]
```
### Campos de bloque
| Campo | Descripción |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Se mantiene estable dentro de una respuesta: `p.b`. |
| `type` | Tipo de bloque: `title`, `section_header`, `text`, `table`, `formula`, `figure`, `caption`, `page_number`, `page_header`, `page_footer`. Pueden aparecer nuevos tipos con el tiempo. |
| `label` | Etiqueta sin procesar del modelo de diseño, transmitida directamente para garantizar la compatibilidad futura. |
| `bbox` | `[x0, y0, x1, y1]` normalizado entre 0 y 1 con respecto a la página. Multiplíquelo por `width`/`height` para obtener coordenadas en píxeles. `null` cuando no se conocen las dimensiones de la página. |
| `content` | El fragmento de markdown aportado por este bloque. |
| `markdownSpan` | Desplazamientos de caracteres `[start, end)` en el `markdown` del documento que abarcan el fragmento de este bloque. `null` cuando el posprocesamiento reescribió el fragmento. |
| `readingOrder` | Posición en el orden de lectura detectado. |
| `source` | Ruta del pipeline que generó el bloque (p. ej., `native_text`, `layout_ocr`, `tsr`, `formula_model`). |
| `confidence` | Puntuación de detección de `layout` (0–1) y nivel de confianza del texto de `ocr` cuando la fuente lo proporciona; `null` en caso contrario; nunca un valor agregado inventado. |
### Fundamentación: de una respuesta a la página
`markdownSpan` vincula cada bloque con la subcadena exacta del markdown que
generó. Esto hace que la fundamentación de las citas sea una búsqueda, no una inferencia: busca el
texto citado en el markdown, encuentra el bloque cuyo intervalo cubre ese desplazamiento
y tendrás el número de página y el cuadro delimitador, sin pedirle nunca
coordenadas a un modelo de lenguaje.
```python Python theme={null}
def ground(doc, quote: str):
start = doc["markdown"].find(quote)
for page in doc["blocks"]:
for block in page["items"]:
span = block["markdownSpan"]
if span and span[0] <= start < span[1]:
return page["pageNumber"], block["bbox"]
```
```js Node theme={null}
function ground(doc, quote) {
const start = doc.markdown.indexOf(quote);
for (const page of doc.blocks) {
for (const block of page.items) {
const span = block.markdownSpan;
if (span && span[0] <= start && start < span[1]) {
return { pageNumber: page.pageNumber, bbox: block.bbox };
}
}
}
}
```
## Salida JSON estructurada
Proporciona un JSON schema o un prompt para extraer datos estructurados directamente del documento:
```python Python theme={null}
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
from pydantic import BaseModel
firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
class Invoice(BaseModel):
vendor: str
total: float
doc = firecrawl.parse(
"./invoice.pdf",
options=ScrapeOptions(formats=[{
"type": "json",
"schema": Invoice.model_json_schema(),
}]),
)
print(doc.json)
```
```js Node theme={null}
import { Firecrawl } from "firecrawl";
import fs from "node:fs";
import { z } from "zod";
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const schema = z.object({
vendor: z.string(),
total: z.number(),
});
const doc = await firecrawl.parse(
{ data: fs.readFileSync("./invoice.pdf"), filename: "invoice.pdf" },
{ formats: [{ type: "json", schema }] },
);
console.log(doc.json);
```
```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/parse \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@./invoice.pdf' \
-F 'options={"formats":[{"type":"json","schema":{"type":"object","properties":{"total":{"type":"number"},"vendor":{"type":"string"}}}}]};type=application/json'
```
## Opciones de PDF
Todo el comportamiento relacionado con PDF se controla mediante la opción `parsers`, tanto en `/parse` como en
`/scrape`:
```json theme={null}
{
"parsers": [
{
"type": "pdf",
"mode": "auto",
"maxPages": 100,
"pages": true,
"blocks": true
}
]
}
```
| Propiedad | Tipo | Predeterminado | Descripción |
| ---------- | --------------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
| `type` | `"pdf"` | *(obligatorio)* | Tipo de parser. |
| `mode` | `"fast" \| "auto" \| "ocr"` | `"auto"` | Estrategia de procesamiento; consulta más abajo. |
| `maxPages` | `integer` | — | Limita el número de páginas que se procesarán. |
| `pages` | `boolean` | `false` | También devuelve [Markdown por página](#per-page-markdown-pdf). Sin costo adicional. |
| `blocks` | `boolean` | `false` | También devuelve [bloques de diseño](#layout-blocks-pdf) con cuadros delimitadores. Sin costo adicional. |
Al pasar `parsers: []`, se omite por completo el procesamiento y se devuelve el PDF en base64
(1 crédito fijo).
### Modos de procesamiento
| Modo | Descripción |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | Primero intenta extraer el texto rápidamente y recurre al OCR cuando una página lo necesita. Es el modo predeterminado. |
| `fast` | Solo extracción basada en texto (texto incrustado). Es la opción más rápida, pero falla en páginas escaneadas o que solo contienen imágenes, en vez de devolver un resultado vacío sin avisar. |
| `ocr` | Fuerza el OCR en todas las páginas. Úsalo para documentos escaneados o cuando `auto` clasifique incorrectamente una página. |
## Formatos compatibles
**Extensiones:** `.html`, `.htm`, `.xhtml`, `.pdf`, `.docx`, `.doc`, `.docm`, `.odt`, `.ods`, `.odp`, `.rtf`, `.xlsx`, `.xls`, `.xlsm`, `.xlsb`, `.pptx`, `.ppt`, `.pptm`, `.epub`, `.csv`.
Consulta [Document Parsing](/es/features/document-parsing) para saber cómo se
convierte cada formato.
## Referencia de la solicitud
La solicitud es `multipart/form-data` con una parte `file` obligatoria y una
parte JSON `options` opcional. `options` acepta un subconjunto de las opciones de scraping:
* `formats`: array de formatos de salida. El valor predeterminado es `["markdown"]`. Admitidos: `markdown`, `html`, `rawHtml`, `links`, `images`, `resumen` y `json` (con un schema o prompt).
* `onlyMainContent`: Solo devuelve el contenido principal del documento. El valor predeterminado es `true`.
* `includeTags` / `excludeTags`: Inclusión o exclusión por etiqueta (entradas HTML).
* `redactPII`: Redacta la información de identificación personal del markdown devuelto.
* `timeout`: Tiempo de espera de la solicitud en milisegundos. El valor predeterminado es `30000`; el máximo, `300000`.
* `parsers`: Opciones del parser de archivos — consulta las [opciones de PDF](#pdf-options).
`/parse` no admite opciones exclusivas del navegador como `actions`, `waitFor`, `location`, `mobile` o seguimiento de cambios.
**¿Usas Firecrawl a través de MCP?** Usa `firecrawl_parse` para archivos locales. El MCP local puede leer el archivo directamente cuando está configurado con `FIRECRAWL_API_URL`. El MCP remoto alojado primero devuelve un comando de carga de corta duración y luego procesa el `uploadRef` devuelto. Las URL de documentos públicos deben seguir usando `/scrape`.
## Consideraciones
* El tamaño máximo de archivo es de **50 MB** por solicitud.
* El procesamiento de PDF se factura a **1 crédito por página**; las opciones `pages` y `blocks` no generan ningún costo adicional.
* Procesar archivos PDF muy grandes o escaneados en modo `ocr` puede tardar más; aumenta `timeout` o usa `maxPages` para limitar el procesamiento.
* Para lotes de archivos, llama a `/parse` por archivo en paralelo; no existe una variante de carga por lote.
> ¿Eres un agente de IA que necesita una API key de Firecrawl? Consulta [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver las instrucciones de incorporación automatizada.