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

# Referencia

> Clases, métodos y opciones de markpdf-cpp.

\#Referencia

## `markpdf::Client`

```cpp theme={null}
#include <markpdf/client.hpp>

markpdf::ClientOptions opts;
opts.apiKey = "YOUR_API_KEY";                  // or MARKPDF_API_KEY environment variable if omitted
opts.baseUrl = "https://api.markpdf.tech";  // optional, production default
opts.timeoutMs = 300000;                     // default 300000 (5 min)
opts.maxRetries = 2;                         // reintentos en 429/5xx

markpdf::Client client(opts);
// or, for the simple case:
markpdf::Client client2("YOUR_API_KEY");
```

<ParamField body="apiKey" type="std::string" required>
  Su clave API. Si se omite, el constructor lee `MARKPDF_API_KEY` del entorno; arroja `std::runtime_error` en construcción si ninguno de los dos existe.
</ParamField>

<ParamField body="baseUrl" type="std::string" default="https://api.markpdf.tech">
  URL base de API.
</ParamField>

<ParamField body="timeoutMs" type="long" default="300000">
  Tiempo de espera por solicitud en milisegundos (`CURLOPT_TIMEOUT_MS`).
</ParamField>

<ParamField body="maxRetries" type="int" default="2">
  Reintentos automáticos con retroceso exponencial en `429` y `5xx`.
</ParamField>

`markpdf::Client` no se puede copiar pero sí se puede mover. Es seguro compartir una instancia entre subprocesos para llamadas de solo lectura (`getJob`, `pdfIndex`); para conversiones simultáneas, cada hilo reutiliza su propio `curl easy handle` internamente a través de un grupo.

## `ConvertOptions`

Estructura compartida por `convertFile`, `convertFromUrl` y `convertStream`, con la misma asignación 1:1 a los [parámetros de consulta de API](/docs/public/es/api/parameters):

```cpp theme={null}
struct ConvertOptions {
    std::string filename;
    InputFormat inputFormat = InputFormat::Auto;
    Mode mode = Mode::Fast;
    Engine engine = Engine::Auto;
    bool clean = true;
    bool imageOcr = false;
    bool hybridOcr = false;
    ResponseFormat responseFormat = ResponseFormat::Markdown;
    std::optional<std::string> pages;
    std::optional<std::string> outputUrl;
    OutputEncoding outputEncoding = OutputEncoding::Identity;
    std::optional<std::string> outputHeadUrl;
    bool autoPoll = true;
};
```

Las enumeraciones (`InputFormat`, `Mode`, `Engine`, `ResponseFormat`, `OutputEncoding`) se serializan con los mismos valores de cadena documentados por API; consulte [Parámetros](/docs/public/es/api/parameters).

## Métodos

### `convertFile`

```cpp theme={null}
Result<ConversionResult, MarkpdfError>
Client::convertFile(const std::string& path, const ConvertOptions& opts = {});
```

Cargue un archivo local en `POST /convert/raw`.

<ParamField body="opts.autoPoll" type="bool" default="true">
  Si el servidor responde `202`, el cliente bloquea el hilo actual y sondea desde `GET /jobs/{id}` hasta `completed`/`failed`. Con `autoPoll = false`, `convertFile` devuelve un error de tipo `JobQueued` con `jobId` para sondeo manual. Consulte [Transmisión y asíncrono](/docs/public/es/sdks/cpp/streaming-and-async).
</ParamField>

### `convertFromUrl`

```cpp theme={null}
Result<ConversionResult, MarkpdfError>
Client::convertFromUrl(const std::string& url, const ConvertOptions& opts = {});
```

Llama a `POST /convert/from-url`.

### `convertStream`

```cpp theme={null}
void Client::convertStream(
    const std::string& pathOrUrl,
    StreamSource source,                     // StreamSource::File o StreamSource::Url
    const std::function<void(std::string_view chunk)>& onChunk,
    const StreamOptions& opts = {}
);
```

Invoca `onChunk` sincrónicamente para cada fragmento recibido de `POST /convert/stream` (o `/convert/stream-from-url`). No hay valor de retorno: la devolución de llamada se ejecuta en el mismo hilo que llama a `convertStream`, mientras la solicitud HTTP aún está en progreso. Consulte [Transmisión y asíncrono](/docs/public/es/sdks/cpp/streaming-and-async).

```cpp theme={null}
struct StreamOptions {
    std::string filename;
    InputFormat inputFormat = InputFormat::Auto;
    bool clean = true;
    bool slim = true;
    StreamSlimStrategy strategy = StreamSlimStrategy::Sampled;
};
```

### `pdfIndex`

```cpp theme={null}
Result<PdfSpine, MarkpdfError>
Client::pdfIndex(const std::string& url, const std::string& filename = "");
```

Llama a `POST /pdf/index`.

### `getJob`

```cpp theme={null}
Result<JobStatus, MarkpdfError>
Client::getJob(const std::string& jobId);
```

Consulta manualmente `GET /jobs/{id}`.

## Tipos de devolución

### `ConversionResult`

```cpp theme={null}
struct Timings {
    int convertMs, cleanMs, totalWorkerMs, uploadMs, totalRequestMs;
};

struct ConversionResult {
    std::string markdown;
    std::string filename;
    std::string inputFormat;
    std::string engine;
    long sizeBytes;
    long markdownBytes;
    long tokenSavedEstimate;
    Timings timings;
};
```

### `PdfSpine`

```cpp theme={null}
struct Section { int page; int level; std::string text; };
struct PageInfo { int page; int chars; std::string firstLine; };

struct PdfSpine {
    int pageCount;
    long inputBytes;
    std::vector<Section> sections;
    std::vector<std::string> repeatedHeadersFooters;
    std::vector<PageInfo> pages;
    bool pagesTruncated;
    long estimatedTokensFull;
    long estimatedTokensSpineOnly;
};
```

### `JobStatus`

```cpp theme={null}
enum class JobState { Queued, Processing, Completed, Failed };

struct JobStatus {
    std::string jobId;
    JobState status;
    std::optional<std::string> body;   // presente si status == Completed
    std::optional<std::string> error;  // presente si status == Failed
};
```

## `Result<T, E>`

`markpdf::Result<T, E>` es un contenedor liviano como `std::expected` (compatible con C++17):

```cpp theme={null}
auto result = client.convertFile("report.pdf");
if (result) {
    use(result.value());   // o *result
} else {
    handle(result.error()); // MarkpdfError
}
```

Consulte [Manejo de errores](/docs/public/es/sdks/cpp/error-handling) para obtener detalles de `MarkpdfError`.