> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doconda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convertir ficheros

> Pasa cualquier fichero a otro formato sin IA: a Markdown para tu modelo, de Markdown a Word, de PDF a Word, cualquier cosa a PDF.

> [!NOTE]
>
> Da por hecho que has completado el [quickstart](https://docs.doconda.com/es/quickstart.md).

`POST /v1/convert` pasa un fichero a otro formato sin IA, en una sola llamada. Esta guía cubre qué formatos se
convierten en cuáles, cómo leer el resultado, cuánto cuesta y las cuatro formas de pasar el fichero.

## Convierte un fichero

Envía el fichero y el formato de destino en `to`. Doconda responde con el texto convertido o con un enlace al fichero
convertido.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from doconda import Doconda

doconda = Doconda()  # lee DOCONDA_API_KEY

result = doconda.convert({"url": "https://ejemplo.com/contrato.pdf"}, "md")
print(result["text"][:60], result["pages"])
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { Doconda } from "@doconda/sdk"

const doconda = new Doconda() // lee DOCONDA_API_KEY

const result = await doconda.convert({ url: "https://ejemplo.com/contrato.pdf" }, "md")
console.log(result.text?.slice(0, 60), result.pages)
```

La respuesta es una `conversion`:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "object": "conversion",
  "id": "doc_01JAB3H8K2M7V6X5T1R0NPQ4ZW",
  "from": "pdf",
  "to": "md",
  "text": "# Contrato de arrendamiento\n\nEn Madrid, a…",
  "output": null,
  "pages": 7,
  "expires_at": null
}
```

`pages` cuenta las páginas (PDF, Word), diapositivas (PowerPoint) u hojas (Excel) del fichero que enviaste.

## Qué se convierte en qué

| Envías | `to` |
| - | - |
| Word (`.docx`, `.doc`), `.odt`, Markdown, TXT, HTML | `docx`, `pdf`, `md`, `txt`, `html`, `odt`, `rtf` |
| Excel (`.xlsx`, `.xls`), CSV | `xlsx`, `csv`, `pdf`, `md`, `txt` |
| PowerPoint (`.pptx`, `.ppt`) | `pptx`, `pdf`, `md`, `txt` |
| PDF | `docx`, `md`, `txt` |
| Imágenes (PNG, JPEG) | `pdf`, `md` |

Cualquier otra pareja se rechaza con `400 conversion_not_supported`, y el mensaje dice a qué formatos puede pasar ese
fichero. Un fichero que no se puede convertir falla con `422` y su código de error (`convert_failed` si no hay otro más
concreto).

## Lee el resultado

Dónde llega el resultado depende de `to`:

* **`md`, `txt`, `html` y `csv`** vuelven en `text`, y `output` es `null`. Doconda borra el resultado en cuanto
  responde, así que después `GET /convert/{id}` devuelve `404 not_found`.
* **`docx`, `pdf`, `odt`, `rtf`, `xlsx` y `pptx`** vuelven en `output`, y `text` es `null`. `output.url` es un enlace
  de descarga que vale 5 minutos. El fichero se borra 15 minutos después de hacerse (`expires_at`); hasta entonces,
  `GET /convert/{id}` te da un enlace nuevo.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from pathlib import Path
import httpx

result = doconda.convert("notas.md", "docx")
Path("notas.docx").write_bytes(httpx.get(result["output"]["url"]).content)
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { writeFile } from "node:fs/promises"

const result = await doconda.convert("notas.md", "docx")
await writeFile("notas.docx", new Uint8Array(await (await fetch(result.output!.url)).arrayBuffer()))
```

Cómo se lee cada formato:

* **Word**: títulos, listas, tablas, imágenes y notas al pie. Las formas, los cuadros de texto y los gráficos no pasan a
  Markdown, HTML ni RTF.
* **PowerPoint**: una sección por diapositiva (separadas por `---`), el título como `##`, las viñetas con su nivel, las
  tablas, las imágenes por su texto alternativo y las notas del orador como cita.
* **Excel**: una tabla por hoja visible, con los valores que muestran las celdas (fórmulas calculadas). A CSV, solo la
  primera hoja.
* **PDF**: títulos, párrafos, listas y tablas reconstruidos a partir de la página; fuera las cabeceras y pies repetidos
  y los números de página.
* **PDF escaneados e imágenes**: se leen con OCR.
* **A PDF**: los documentos llevan las mismas fuentes que usa Doconda en todo (Calibri como Carlito, Cambria como
  Caladea…).

## Espera una conversión larga

Una llamada espera hasta 120 s. Un PDF escaneado largo puede tardar minutos: entonces la llamada responde `202` con
`{ "object": "conversion", "id", "status" }`, donde `status` es `queued` o `running`. Llama a `GET /convert/{id}` en los
15 minutos siguientes para recoger el resultado; también responde `202` mientras sigue convirtiendo.

El `convert()` de los SDK lo hace por ti: pregunta cada 2 s y devuelve la conversión terminada.

## Precio

Las 1000 primeras conversiones de cada mes natural (UTC) son gratis para cada organización. Después, cada una cuesta
0,01 € del saldo, tenga las páginas que tenga ([precios](https://docs.doconda.com/es/guides/account.md#precios)).

* Las conversiones fallidas no se cobran ni cuentan para las 1000 gratis.
* Pasadas las gratis y sin saldo, la llamada se rechaza con `402 insufficient_balance`.
* Una conversión no sale en la lista de documentos y no manda webhooks.
* Las conversiones cuentan para el límite de 120 documentos por minuto de cada organización; por encima,
  `429 rate_limited`.

## Cuatro formas de pasar un fichero

`file` admite aquí las mismas cuatro formas que `file` y `sources` en `POST /documents`:

| Cómo | Ejemplo |
| - | - |
| Un documento que ya hizo Doconda, por su ID | `"doc_01JAB3…"` (Doconda usa su Word, PowerPoint o Excel, o su PDF si solo tiene eso) |
| Un fichero subido | `"file_01JAB3…"` |
| Una URL pública (`http` o `https`) | `{ "url": "https://…/informe.docx" }` |
| Sus bytes en base64 | `{ "data": "UEsDBBQ…", "filename": "informe.docx" }` |

También puedes enviar `multipart/form-data`, con el campo `to` antes del campo `file`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://api.eu.doconda.com/v1/convert \
  -H "Authorization: Bearer $DOCONDA_API_KEY" \
  -F to=pdf \
  -F file=@informe.docx
```

Ten en cuenta:

* Los ficheros tienen un máximo de 20 MB.
* Las URL tienen que apuntar a direcciones públicas; las privadas y locales se rechazan.
* Un fichero enviado por URL, base64 o multipart se borra 15 minutos después de la llamada.

## Desde el SDK

`doconda.convert(file, to)` acepta un ID `file_…` o `doc_…`, una URL, una ruta local o bytes con su `filename`, y
devuelve la conversión terminada.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
text = doconda.convert("file_01JAB3…", "md")["text"]
url = doconda.convert("https://ejemplo.com/notas.md", "docx")["output"]["url"]
pdf = doconda.convert(b"# Notas\n\nPrimer punto.", "pdf", filename="notas.md")
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
const { text } = await doconda.convert("file_01JAB3…", "md")
const { output } = await doconda.convert("https://ejemplo.com/notas.md", "docx")
const pdf = await doconda.convert(new TextEncoder().encode("# Notas\n\nPrimer punto."), "pdf", { filename: "notas.md" })
```

Si pasas bytes sin `filename`, el SDK lanza un error antes de llamar a la API, porque la extensión le dice a Doconda el
formato. Los agentes tienen la misma operación con la herramienta `convert_file` del [servidor MCP](https://docs.doconda.com/es/agents/mcp.md).

## Siguientes pasos

> **[Crea un documento](https://docs.doconda.com/es/guides/create.md)**
>
> Haz un Word, PowerPoint, Excel o PDF nuevo desde una frase o desde tu Markdown.

> **[Edita un fichero](https://docs.doconda.com/es/guides/edit.md)**
>
> Cambia parte de un fichero y deja el resto como estaba.

> **[Referencia de la API](https://docs.doconda.com/es/api-reference/introduction.md)**
>
> Todos los parámetros de `POST /convert` y `GET /convert/{id}`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.