` | ninguno | Lista de permitidos y lista de bloqueados con expresiones regulares, máximo 50 cada una. La lista de bloqueados se aplica en segundo lugar. |
| `sameDomainOnly`, `respectRobots` | `boolean` | `true`, ninguno | Permanece en el dominio semilla y respeta las reglas robots del sitio. |
### Lookup
Búsqueda web por categorías, con renderizado automático opcional de los primeros resultados. Referencia del endpoint: [Lookup](/es/docs/v2-lookup).
```java
LookupResult search = client.v2.lookup("best static site generators",
LookupOptions.builder()
.category("web") // web, news, images, scholar, patents, maps
.numResults(10)
.country("us")
.timeFilter("month") // hour, day, week, month, year
.perceiveTop(3) // renderiza automáticamente los 3 primeros resultados
.build());
search.results().forEach(hit -> {
System.out.println(hit.position() + " " + hit.title() + " " + hit.url());
if (hit.perceive() != null) System.out.println(" quality " + hit.perceive().renderQuality());
});
```
Con `perceiveTop` por encima de 0 (de 0 a 10, por defecto 0), las URL de los N primeros resultados se renderizan mediante perceive y cada resultado lleva su `PerceiveResult` completo en línea en `hit.perceive()`. `numResults` va de 1 a 100 y su valor por defecto es 10; `page` va de 1 a 10.
### Distill
Extracción estructurada guiada por schema a través de una o varias páginas. Referencia del endpoint: [Distill](/es/docs/v2-distill).
```java
DistillResult extraction = client.v2.distill(
DistillOptions.builder(Map.of("products", "list of product names with their listed price"))
.urls(List.of("https://example.com/catalog"))
.cssSchema(CssSchema.builder(".product-card", List.of(
CssField.builder("name", "text").selector("h3").build(),
CssField.builder("price", "text").selector(".price").build()))
.targetField("products")
.build())
.build());
extraction.results().forEach(item ->
System.out.println(item.data() + " via " + item.extractionTier()));
```
El `cssSchema` opcional ejecuta primero una pasada CSS gratuita; solo los campos que no puede resolver escalan al nivel del LLM, e `item.extractionTier()` informa de qué ruta produjo el registro (`css`, `llm`, `mixed` o `none`). También puedes descubrir las URL primero en lugar de enumerarlas:
```java
client.v2.distill(
DistillOptions.builder(Map.of("title", "page title", "summary", "one-line summary"))
.discoverFrom(new DistillDiscoverFrom("https://example.com", "sitemap", 10))
.build());
```
Debe estar establecido exactamente uno de `urls` (máximo 50) y `discoverFrom`, y la factoría del builder exige `schema`. Ambas reglas se comprueban en el cliente y lanzan `IllegalArgumentException` antes de que salga ninguna solicitud.
### Ingest
Convierte un sitio entero, o un conjunto de documentos subidos, en JSONL troceado y listo para RAG mediante un único pipeline. Ingest siempre es asíncrono. Referencia del endpoint: [Ingest](/es/docs/v2-ingest).
```java
// Desde un sitio
IngestJob job = client.v2.ingest(IngestOptions.builder()
.mode("sitemap") // "urls" (por defecto), "sitemap", "crawl"
.url("https://docs.example.com")
.maxPages(100)
.chunk(new IngestChunkOptions(512, 1)) // maxWords, sentenceOverlap
.webhookUrl("https://my.app/hooks/enconvert")
.build());
// O desde archivos subidos
IngestJob fileJob = client.v2.ingestFiles(
List.of(new FileInput(Files.readAllBytes(Path.of("handbook.pdf")), "handbook.pdf"),
new FileInput(Files.readAllBytes(Path.of("notes.docx")), "notes.docx")),
IngestFilesOptions.builder().chunk(new IngestChunkOptions(512, 1)).build());
// Sondea hasta obtener el JSONL
IngestJob status = client.v2.getIngestJob(job.jobId());
if ("completed".equals(status.status())) {
System.out.println(status.outputUrl() + " (" + status.totalChunks() + " chunks)");
}
client.v2.listIngestJobs(V2ListOptions.builder().limit(20).build());
client.v2.cancelIngestJob(job.jobId()); // idempotente
```
`ingestFiles` acepta PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT y MD, además de formatos ofimáticos heredados y ODF. El troceado usa por defecto 512 palabras (de 32 a 4000) con 1 frase de solapamiento (de 0 a 10). `mode` es `urls` por defecto, lo que exige una lista `urls` no vacía y prohíbe `url`; cualquier otro modo exige una `url` semilla y prohíbe `urls`. El SDK impone ese emparejamiento antes de enviar.
Los webhooks de finalización se firman con HMAC. Obtén el secreto y los nombres de encabezado que necesitas para verificar una entrega, rótalo cuando se filtre y vuelve a disparar una entrega que tu endpoint se perdió:
```java
WebhookSecret secret = client.v2.getWebhookSecret();
System.out.println(secret.signatureHeader() + " " + secret.signatureScheme());
client.v2.rotateWebhookSecret(); // las firmas antiguas dejan de verificarse de inmediato
WebhookRetryResult retry = client.v2.retryIngestWebhook(job.jobId());
System.out.println(retry.delivered() + " after " + retry.attempts() + " attempts");
```
### Watch
Monitorización recurrente de cambios en una URL, con notificación por correo electrónico y webhook. Referencia del endpoint: [Watch](/es/docs/v2-watch).
```java
Watcher watcher = client.v2.createWatcher("https://example.com/pricing",
WatchCreateOptions.builder()
.frequencyMinutes(60) // de 60 a 43200, mínimo de una hora
.diffMode("auto") // auto, text, structured, tables, metadata
.webhookUrl("https://my.app/hooks/changes")
.notifyEmail(true)
.build());
WatcherSnapshotList history = client.v2.getWatcherSnapshots(watcher.watcherId(),
SnapshotListOptions.builder().limit(10).build());
history.snapshots().forEach(s ->
System.out.println(s.checkedAt() + " changed=" + s.hasChanges()
+ " similarity=" + s.similarity()));
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().status("paused").build());
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().webhookUrl("").build());
client.v2.deleteWatcher(watcher.watcherId()); // borrado lógico, idempotente
```
`listWatchers()` y `getWatcher(watcherId)` los leen de vuelta. `updateWatcher` requiere al menos un campo y lanza `IllegalArgumentException` en caso contrario. Una cadena vacía explícita en `webhookUrl` borra el webhook, mientras que dejarlo nulo significa "sin cambios". `deleteWatcher` es un borrado lógico: devuelve el watcher marcado como eliminado con estado `deleted`, y a partir de ahí un watcher eliminado se lee como `404`.
Los diffs de snapshot contienen contenido de página no confiable. WatcherSnapshot.changes() es texto en crudo tomado de la página monitorizada. Escápalo antes de renderizarlo en un panel, un correo electrónico o un mensaje de chat.
---
## Opciones de PDF
`PdfOptions` es compartido por `convertUrlToPdf`, `convertWebsiteToPdf`, `convertDocument`, `convertToPdf` y `PerceiveOptions.pdfOptions`.
```java
client.convertUrlToPdf("https://internal.example.com/report",
UrlToPdfOptions.builder()
.pdfOptions(PdfOptions.builder()
.pageSize("A4")
.orientation("landscape")
.margins(new PdfMargins(10.0, 10.0, 15.0, 15.0))
.scale(0.9)
.header(new PdfHeaderFooter("Quarterly Report", 15.0))
.footer(new PdfHeaderFooter("Confidential", 12.0))
.build())
.auth(new HttpBasicAuth("user", "pass"))
.cookies(List.of(BrowserCookie.builder("session", "abc123").domain("internal.example.com").build()))
.headers(Map.of("X-Tenant", "acme"))
.saveTo("report.pdf")
.build());
```
| Campo | Tipo | Descripción |
|-------|------|-------------|
| `pageSize` | `String` | `"A4"`, `"A3"`, `"Letter"`, `"Legal"` y similares. |
| `pageWidth`, `pageHeight` | `double` | Dimensiones personalizadas. Establecidas juntas, prevalecen sobre `pageSize`. |
| `orientation` | `String` | `"portrait"` o `"landscape"`. |
| `margins` | `PdfMargins` | Record de `top`, `bottom`, `left`, `right`. Cualquier campo nulo se omite. |
| `scale` | `double` | Escala de renderizado, por ejemplo `0.9` para el 90 por ciento. |
| `grayscale` | `boolean` | Posprocesa el PDF a escala de grises. |
| `header`, `footer` | `PdfHeaderFooter` | Record de `content` (máximo 2000 caracteres) y `height`. |
`BrowserCookie` necesita un nombre y un valor, más `domain` o `url`; cuando se establece `domain` sin `path`, la API asigna `/` a `path` por defecto. No combines `auth` con un encabezado `Authorization` explícito, porque la API rechaza el conflicto.
---
## Manejo de errores
Toda excepción del SDK extiende `EnconvertException`, que a su vez extiende `RuntimeException`, así que nada obliga a una cláusula `throws` en tus puntos de llamada. Captura primero las subclases específicas.
```java
try {
client.convertUrlToPdf("https://example.com");
} catch (AuthenticationException e) {
System.err.println("Invalid or missing API key");
} catch (QuotaException e) {
System.err.println("Request refused with 402: " + e.getMessage());
} catch (RateLimitException e) {
System.err.println("Too many requests, back off and retry");
} catch (ApiException e) {
System.err.println("API error [" + e.getStatusCode() + "]: " + e.getMessage());
}
```
| Clase | Se lanza en | Código de estado |
|-------|-------------|------------------|
| `AuthenticationException` | Clave de API ausente, inválida o sin permiso | `401`, `403` |
| `QuotaException` | HTTP 402 | `402` |
| `RateLimitException` | Demasiadas solicitudes | `429` |
| `ApiException` | Cualquier otra respuesta 4xx o 5xx | el código real |
| `EnconvertException` | Clase base, también lanzada ante un fallo de transporte, una solicitud interrumpida o un archivo de entrada ilegible | ninguno |
La validación del lado del cliente (un par de conversión no admitido, un schema de distill ausente, una actualización de watcher vacía, un número incorrecto de salidas para `perceiveDirect`) lanza `IllegalArgumentException` antes de realizar ninguna solicitud. El mapa de mensajes de las respuestas del servidor está en la referencia de [Códigos de error](/es/docs/error-codes).
---
## Recuperación de timeouts
Los renderizados de URL largos y las conversiones de documentos grandes pueden sobrevivir al timeout del proxy inverso incluso cuando la conversión en sí acaba teniendo éxito. El SDK lo gestiona de forma transparente:
1. Antes de cada solicitud de URL individual o de subida de archivo, el SDK genera un UUID y lo envía como `job_id`.
2. Si la solicitud vuelve con 5xx, el SDK pasa a sondear `GET /v1/convert/status/{jobId}` cada 3 segundos.
3. Ante `success` devuelve el resultado. Ante `failed` lanza `ApiException` con el mensaje de error del servidor.
4. El plazo de sondeo es de 5 minutos. Pasado ese punto lanza `ApiException(504, "Conversion timed out")`.
No escribes ningún código para esto. Si una respuesta correcta omite `job_id`, el SDK rellena el id que generó, de modo que `result.jobId()` siempre se puede usar con `getJobStatus`.
Los envíos de lotes de sitios web quedan excluidos a propósito. convertWebsiteToPdf y convertWebsiteToScreenshot no tienen una fila por job que sondear, así que un 5xx ahí significa que falló el propio envío y se expone directamente. Los endpoints V2 tampoco usan sondeo de jobs; sus flujos asíncronos pasan por getPerceiveBatch y getIngestJob.
---
## Configuración
```java
Enconvert client = Enconvert.builder(System.getenv("ENCONVERT_API_KEY"))
.baseUrl("https://api.enconvert.com")
.timeout(Duration.ofSeconds(300))
.build();
```
Hay tres constructores disponibles como atajo: `new Enconvert(apiKey)`, `new Enconvert(apiKey, baseUrl)` y `new Enconvert(apiKey, baseUrl, timeout)`.
| Opción | Tipo | Por defecto | Descripción |
|--------|------|-------------|-------------|
| `apiKey` | `String` | obligatorio | Clave de API privada. Un valor nulo o vacío lanza `IllegalArgumentException`. |
| `baseUrl` | `String` | `https://api.enconvert.com` | URL base de la API. Las barras finales se eliminan. |
| `timeout` | `Duration` | 300 segundos | Se aplica tanto como timeout de conexión como timeout por solicitud. |
La clave viaja en el encabezado `X-API-Key`. Las URL de descarga prefirmadas se obtienen sin ella, ya que vienen firmadas. Los tipos de clave se tratan en [Autenticación](/es/docs/authentication); crea y gestiona claves en el [panel de control](/es/dashboard).
Nunca incrustes la clave de API en el código. Léela desde una variable de entorno o desde tu gestor de secretos. El SDK es solo del lado del servidor: una clave privada no debe viajar dentro de un artefacto de escritorio o móvil que un usuario pueda desempaquetar.
---
## Forma del resultado
Toda conversión de un solo archivo o de una sola URL devuelve el mismo record:
```java
public record ConversionResult(
String presignedUrl,
String objectKey,
String filename,
Long fileSize,
Double conversionTimeSeconds,
String jobId) {}
```
La URL prefirmada tiene un tiempo limitado. Pasa `saveTo` (o descarga la URL tú mismo) y guarda los bytes en tu propio bucket si necesitas que le sobrevivan.
Los demás records de respuesta que tocarás con más frecuencia:
| Record | Accesores principales |
|--------|-----------------------|
| `JobStatus` | `status()` (`processing`, `success`, `failed`), `presignedUrl()`, `objectKey()`, `error()` |
| `BatchStatus` | `status()`, `total()`, `completed()`, `failed()`, `inProgress()`, `zipDownloadUrl()`, `items()` |
| `PerceiveResult` | `operationId()`, `renderQuality()`, `statusCode()`, `deductions()`, `outputs()`, `structured()`, `cacheHit()`, `warnings()` |
| `V2OutputArtifact` | `url()`, `objectKey()`, `sizeBytes()`, `contentType()`, `expiresIn()` |
| `PerceiveDirectResult` | `content()`, `contentType()`, `filename()`, `renderQuality()`, `contentHash()` |
| `IngestJob` | `jobId()`, `status()`, `pagesProcessed()`, `totalChunks()`, `outputUrl()`, `webhookDelivered()` |
| `Watcher` | `watcherId()`, `status()`, `frequencyMinutes()`, `checksCount()`, `nextCheckAt()`, `lastChangeAt()` |
Los campos cuya forma define tu propia solicitud (`structured`, `data`, `trackFields`, los `changes` del snapshot) se exponen como `JsonObject` de Gson y pasan intactos. Las enumeraciones con valores de cadena siguen siendo `String` en lugar de convertirse en constantes `enum` de Java, así que un valor más reciente de la API nunca rompe la deserialización en una build más antigua del SDK. `com.enconvert.model.v2.V2Enums` contiene cada valor aceptado como una constante a prueba de erratas.
---
## Código fuente e incidencias
- **Maven Central:** `com.enconvert:enconvert-sdk:0.0.1`
- **GitHub:** [conversionapi/java-sdk](https://github.com/conversionapi/java-sdk)
- **Licencia:** MIT
- **Otros clientes:** [todos los SDK](/es/docs/sdks) · [referencia de endpoints](/es/docs/endpoints-overview) · [precios](/es/pricing)
---
## Preguntas frecuentes
### ¿Cómo convierto archivos en Java con una dependencia de Maven?
Añade `com.enconvert:enconvert-sdk:0.0.1` a tu `pom.xml` o `build.gradle`, construye un cliente con `new Enconvert(System.getenv("ENCONVERT_API_KEY"))` y llama a un método tipado como `convertUrlToPdf`, `convertImage`, `convertDocument` o `convertToPdf`. Pasa `saveTo` en el builder de opciones para escribir la salida directamente en disco en lugar de gestionar tú la URL prefirmada.
### ¿Cómo convierto una URL a PDF en Java?
Llama a `client.convertUrlToPdf(url, UrlToPdfOptions.builder().saveTo("page.pdf").build())`. Establece `singlePage(false)` para paginar usando `pdfOptions.pageSize` en lugar de producir una única página continua, y pasa `auth`, `cookies` o `headers` para una página tras un inicio de sesión.
### ¿Cómo convierto DOCX a PDF en Java?
Llama a `client.convertDocument(Path.of("report.docx"), ConvertDocumentOptions.builder().saveTo("report.pdf").build())`. El formato de salida es `pdf` por defecto, así que solo estableces `outputFormat` cuando quieres otra cosa, por ejemplo `yaml` a partir de una entrada `.json`. Para formatos sin un par propio, como EPUB o RTF, usa `convertToPdf`.
### ¿Cómo convierto HEIC a WebP en Java?
Llama a `client.convertImage(Path.of("photo.heic"), ConvertImageOptions.builder("webp").saveTo("photo.webp").build())`. El formato de entrada procede de la extensión del archivo y el formato de salida es el argumento obligatorio del builder. `jpeg`, `png`, `svg`, `heic` y `webp` se convierten todos entre sí, y `pdf` se rasteriza a `jpeg`. En este cliente no hay un método de compresión in situ.
### ¿Cómo extraigo una página web a Markdown limpio desde Java?
Dos caminos. `client.convertUrlToMarkdown(url, ...)` devuelve Markdown con sabor GitHub y frontmatter YAML como archivo descargable. `client.v2.perceive(url, PerceiveOptions.builder().outputs(List.of("markdown")).build())` devuelve el mismo contenido como un artefacto listo para agentes, con una puntuación `renderQuality`, opciones de extracción y control de caché. Usa perceive cuando una mala lectura tenga que ser detectable en lugar de silenciosa.
### ¿Qué es renderQuality y por qué toda lectura tiene una?
`renderQuality` es una puntuación de 0.0 a 1.0 adjunta a cada renderizado V2. Una puntuación alta significa que la página se renderizó limpiamente; una baja significa que algo se interpuso, como un desafío antibots, un muro de cookies, una pantalla de inicio de sesión, una página de error HTTP o el armazón vacío de una SPA. El contenido se sigue devolviendo, con `warnings()` y `deductions()` rellenos, para que tu pipeline pueda descartar o reintentar la lectura en lugar de alimentar un modelo con una página de desafío como si fuera el artículo.
### ¿Cómo convierto un sitio de documentación en fragmentos listos para RAG en Java?
Llama a `client.v2.ingest(IngestOptions.builder().mode("sitemap").url("https://docs.example.com").maxPages(100).chunk(new IngestChunkOptions(512, 1)).build())`. El job es asíncrono, así que sondea `getIngestJob(jobId)` hasta que el estado sea `completed` y lee `outputUrl()` para obtener el JSONL, o bien establece `webhookUrl` y verifica la firma HMAC con el secreto de `getWebhookSecret()`. Para documentos locales en lugar de un sitio, usa `ingestFiles`.
### ¿Cómo gestiona el SDK las conversiones que superan el timeout del proxy?
Antes de cada solicitud de URL individual o de subida de archivo genera un UUID y lo envía como `job_id`. Si la solicitud devuelve 5xx, sondea `GET /v1/convert/status/{jobId}` cada 3 segundos hasta que el job informe de `success` o `failed`, con un plazo de 5 minutos tras el cual lanza `ApiException(504, "Conversion timed out")`. Los envíos de lotes de sitios completos quedan excluidos, porque no tienen una fila por job que sondear.
### ¿Qué versión de Java requiere el SDK y qué arrastra consigo?
Java 17 o posterior. HTTP pasa por el `java.net.http.HttpClient` del JDK, y Gson es el único artefacto de terceros en el classpath. Las respuestas son records de Java, así que un `switch` moderno o un pattern match sobre ellas funciona como cabe esperar. El cliente es seguro entre hilos: mantén una instancia y compártela.