> ## 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.

# SDK de Python

> Genera, revisa y edita Word, PowerPoint, Excel y PDF desde Python: pip install doconda.

El SDK de Python hace lo mismo que la API, con reintentos y streaming ya resueltos. Funciona en Python 3.9 o superior
(también en AWS Lambda, Cloud Run o un notebook) y su única dependencia es `httpx`.

<Tip>También en TypeScript, con los mismos métodos: [SDK de TypeScript](/es/sdk/introduction).</Tip>

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install doconda
```

## Tu primer documento

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

doconda = Doconda()  # lee la key de DOCONDA_API_KEY
doc = doconda.documents.create(format="docx", prompt="Informe de la ley de vivienda")

print(doc["status"])  # "ready"
open("informe.docx", "wb").write(doconda.documents.download(doc["id"], "docx"))
```

`create` recibe el mismo cuerpo que [`POST /documents`](/es/api-reference/introduction) como argumentos con nombre y espera a
que el documento termine. Las respuestas son diccionarios con los mismos campos que la API.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
doconda.documents.create(
    format="pptx",
    prompt="Resultados del trimestre para el comité",
    style="títulos azul oscuro, fuente Lora",
    quality="best",
)

doconda.documents.create(format="docx", content={"markdown": "# Acta\n\nAsistentes: …"})
```

## Opciones

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
doconda = Doconda(
    api_key="ak_eu_…",   # por defecto, DOCONDA_API_KEY
    max_retries=2,       # reintentos ante errores de red, 429 y 5xx
    base_url=None,       # por defecto, https://api.eu.doconda.com/v1
    http_client=None,    # tu httpx.Client (proxies, timeouts), también para descargar
    language=None,       # "es": mensajes en español; por defecto, en inglés
)
```

## Revisar y editar

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
file = doconda.files.upload("contrato.docx")  # una ruta, bytes (con filename) o un fichero abierto

revisado = doconda.documents.create(operation="review", file=file["id"])
editado = doconda.documents.create(operation="edit", file=file["id"], prompt="títulos azules y una cláusula de confidencialidad")

informe = doconda.documents.report(editado["id"])  # problemas, arreglos y cada cambio
```

## Leer un archivo a Markdown

Gratis hasta 1.000 páginas al mes; después 0,01 € cada 5 páginas ([precios](/es/guides/account#precios)). Acepta una ruta,
bytes (con `filename`), una URL pública, un `file_…` o un `doc_…`:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
texto = doconda.extract("propuesta.pdf")["markdown"]
```

## Seguir el progreso

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
for event in doconda.documents.stream(format="docx", prompt="Carta de bienvenida"):
    print(event["type"])  # document.created … document.ready
```

O sin esperar: `create_in_background(...)` responde al momento y `wait(id)` espera a que termine.

## Herramientas para tu agente

`doconda.tools()` devuelve las herramientas de Doconda (crear, subir, revisar, editar, listar, consultar, informe y datos
de un artifact). Cada una tiene `name`, `description`, `input_schema` (JSON Schema) y `run(args)`, así que valen para
cualquier modelo con llamada a funciones:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tools = doconda.tools()                    # para un servidor
tools = doconda.tools(local_files=True)    # además puede subir ficheros de este ordenador
```

Si la API responde con un error, `run` no lanza: devuelve `{"error": "<code>", "message": "<texto>", "fields": […]}`
(`fields`, solo en errores de validación) para que el modelo pueda corregirse.

Cómo conectarlas en cada plataforma: [Amazon Bedrock](/es/agents/bedrock), [Vertex AI](/es/agents/vertex),
[OpenAI](/es/agents/openai), [Claude](/es/agents/claude) y [LangChain](/es/agents/langchain).

## Webhooks

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import os

from doconda import verify_webhook

endpoint = doconda.webhooks.create("https://tu-app.com/doconda")
print(endpoint["secret"])  # sale solo esta vez: guárdalo, por ejemplo en DOCONDA_WEBHOOK_SECRET


def recibir_aviso(cuerpo: bytes, cabeceras: dict[str, str]) -> dict:
    # el cuerpo tal como llega (sin parsear el JSON) y las cabeceras del POST, de tu framework
    secret = os.environ["DOCONDA_WEBHOOK_SECRET"]
    return verify_webhook(cuerpo, cabeceras, secret)  # lanza ValueError si la firma no cuadra
```

## Errores

Una respuesta de error de la API lanza `DocondaError`, con `status`, `code`, `errors`, `request_id` y el mensaje. Los 429 y
5xx se reintentan solos antes de lanzarlo. Ver [errores](/es/guides/errors).

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

try:
    doconda.documents.create(format="docx", prompt="Memo para el equipo")
except DocondaError as e:
    print(e.status, e.code, e.errors)
```

## Referencia

| Método | Devuelve | |
| - | - | - |
| `documents.create(**body, idempotency_key=None)` | documento | Crea, revisa o edita y espera a que termine. |
| `documents.create_in_background(**body)` | documento | Responde al momento (`status: "queued"`). |
| `documents.stream(**body)` | eventos | Crea y da sus eventos en directo. |
| `documents.wait(id)` | documento | Espera a que termine. |
| `documents.get(id)` | documento | Su estado actual. |
| `documents.list(status=None)` | documentos | Todos, del más reciente al más antiguo. |
| `documents.page(limit=, cursor=, status=)` | `{data, next_cursor}` | Una sola página. |
| `documents.events(id, after=0)` | eventos | Sus eventos, retomables. |
| `documents.cancel(id)` / `delete(id)` | documento / — | Lo para / lo borra. |
| `documents.outputs(id)` | enlaces | Enlaces de descarga nuevos. |
| `documents.download(id, kind)` | `bytes` | `docx`, `pdf`, `pptx`, `xlsx`… |
| `documents.report(id)` | informe | Problemas, arreglos y cambios. |
| `documents.data(id, collection=None)` | colecciones / registros | Los datos de un artifact (como mucho, los 1.000 registros más recientes). |
| `files.upload(file, filename=None)` / `get(id)` / `delete(id)` | archivo | Ruta, `bytes` (con `filename`) o fichero abierto. |
| `extract(file, filename=None)` | `{markdown, chars, pages…}` | Cualquier archivo a Markdown. |
| `webhooks.create(url, event_types=None)` / `list()` / `delete(id)` | endpoint | Avisos firmados. |
| `tools(local_files=False)` | `list[Tool]` | Herramientas para tu agente. |
| `verify_webhook(body, headers, secret)` | evento | Comprueba la firma de un aviso. |


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