Inteligencia web V2

EnConvert V2 es una capa de inteligencia web que se sitúa junto a la API de conversión V1: seis endpoints que perciben, descubren, buscan, extraen, ingieren y monitorizan la web. Comparten un mismo pipeline de renderizado con Chrome headless, tus claves de API existentes y la misma lista de endpoints permitidos que V1 — y se miden con sus propios contadores de cuota, de modo que una llamada V2 nunca toca ni una sola conversión V1.

Aquí tienes la llamada útil más pequeña. Envía una URL a /v2/perceive y recibe Markdown limpio y los metadatos estructurados de la página:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"]
  }'

La respuesta incluye una URL de descarga prefirmada para el Markdown y el bloque estructurado en línea:

{
    "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "completed",
    "url_final": "https://example.com/pricing",
    "render_quality": 0.93,
    "outputs": {
        "markdown": {
            "url": "https://spaces.example.com/...signed...",
            "size_bytes": 8421,
            "expires_in": 900
        }
    },
    "structured": {
        "metadata": {"title": "Pricing"}
    }
}

Esa es la forma que comparte cada endpoint V2: envías JSON y recibes un resultado en línea o una URL firmada de corta vida hacia un artefacto. Los seis endpoints se diferencian en lo que hacen con el renderizado, no en cómo accedes a ellos.

Los seis endpoints

Cada endpoint condensa toda una pila de herramientas separadas en una sola llamada contra api.enconvert.com.

Si has usado Firecrawl, el mapeo es directo: /v2/lookup responde a /search, /v2/distill responde a /extract y /v2/ingest responde a /crawl.

Cómo se relaciona V2 con V1

V2 es puramente aditivo. Los endpoints de conversión V1 — html-to-pdf, url-to-pdf, conversiones de imágenes, conversiones de documentos — no cambian y no se ven afectados por nada de esto. No migras a V2; lo añades junto a V1 cuando lo necesitas.

Las dos mitades comparten las partes que importan para la integración:

• Misma autenticación. Una clave privada sk_live_ en la cabecera X-API-Key, o una clave pública pk_ canjeada por un token bearer JWT, funciona de forma idéntica en V1 y V2. Consulta la guía de autenticación para el flujo completo, incluido el bloqueo de dominio y la renovación de tokens.
• Misma allowlist de claves. Cada clave de API lleva una lista de endpoints permitidos. Una ruta V2 que no esté en la lista de la clave se rechaza con 403, exactamente igual que una ruta V1.

Lo que no comparten es el medidor. Los endpoints V2 se facturan con sus propios contadores, totalmente separados del conversions_used de V1:

Una llamada V2 nunca decrementa conversions_used, y los planes de conversión solo de V1 incluyen cero cuota V2 — un plan que incluye V2 es lo que lleva estos contadores. Dos endpoints se controlan mediante un límite de plan en lugar de un contador por operación: /v2/discover es solo HTTP y no almacena nada, así que depende de un flag de plan discover_enabled; /v2/watch está acotado por max_watchers — el tope de cuántos watchers activos mantiene un proyecto a la vez — junto con la cadencia mínima de comprobación horaria. Las asignaciones por nivel para cada contador y límite están en la página de precios.

Decisiones de diseño compartidas en V2

Los seis endpoints están construidos sobre las mismas primitivas, así que una decisión que aprendes una vez vale para todos.

Un renderizado a través de un singleton compartido. Cada endpoint que necesita un navegador real — perceive, el autopercibido de lookup, distill, ingest, watch — renderiza a través del mismo singleton de Chrome headless y el mismo pipeline de captura que hay detrás de el endpoint url-to-pdf de V1. Se descartan los banners de cookies, se desplaza la página para activar el contenido perezoso y se da tiempo a las imágenes para cargar. Discover es la excepción deliberada: nunca toca el navegador en absoluto.

URLs de descarga prefirmadas. Los artefactos binarios y de texto (Markdown, HTML, capturas de pantalla, PDFs, el JSONL de ingest) se suben al almacenamiento y se devuelven como una URL prefirmada — un enlace firmado y de corta vida al almacenamiento de objetos que no necesita autenticación aparte para descargarse. Cada URL firmada expira tras 15 minutos (expires_in: 900). Vuelve a consultar la operación o el job para acuñar un conjunto nuevo; volver a firmar no renderiza nada de nuevo y no cuesta cuota.

Protección SSRF en cada URL. Antes de cualquier fetch o renderizado, cada URL se examina — el esquema, las credenciales incrustadas, los hostnames bloqueados y la IP resuelta. Una URL que resuelve a una dirección privada, de loopback, link-local o de metadatos de la nube se rechaza con 400. Esto se aplica por igual a las semillas, los enlaces crawleados, los objetivos de distill y los objetivos de watch.

Puntuación de calidad de renderizado. Cada renderizado lleva una puntuación render_quality de 0.0 a 1.0. Una puntuación baja señala una página que parece bloqueada por una protección anti-bot u oculta tras un muro de login, de modo que puedes distinguir una captura real de una página de desafío. Watch va más allá: un renderizado por debajo del umbral de calidad 0.4 se registra solo para auditoría y nunca se convierte en una línea base de diff, así que un bloqueo puntual no dispara una falsa alerta de cambio.

Sin credenciales donde importa. Perceive y distill aceptan auth, cookies y headers personalizadas para páginas tras un login. Ingest y watch deliberadamente no — sus jobs son duraderos y recurrentes, así que nunca se persiste nada secreto en disco para una reanudación o una nueva comprobación. ¿Necesitas credenciales para una página en un conjunto de ingest? Renderízala a través de el endpoint perceive en su lugar.

Manejo honesto de "reservado, aún no disponible". Cuando un parámetro es aceptado por el esquema pero todavía no está conectado, V2 te lo dice en lugar de ignorarlo en silencio. Los parámetros proxy_url, geolocation y action_chain de perceive devuelven 422 hoy; sus nombres de extracción prices, contacts y technologies aterrizan en warnings y se descartan. Siempre sabes qué perilla no está lista.

Beta. V2 está en beta. Fija tu integración a los nombres de campo y códigos de estado documentados, lee warnings en cada respuesta y espera que los campos de respuesta ganen forma — aunque no se rompan — antes de que V2 salga de beta. Pueden aparecer campos nuevos; los documentados no cambiarán de significado en silencio.

Qué viene a continuación

Para ser claros, V2 no está terminado. Tres capacidades están en la hoja de ruta y aún no disponibles — no construyas contra ellas:

• Automatización del navegador — un par /v2/pilot y /v2/conduct para interacción multipaso (clic, escritura, navegación) en lugar del renderizado de un solo disparo que hacen los endpoints actuales. Las formas de petición y respuesta no están definidas, así que no se documentan aquí.
• Feedback de extracción — un endpoint para corregir un resultado de distill y retroalimentar la corrección en futuras extracciones. Nombrado, no lanzado.

Cuando lleguen tendrán sus propias páginas de referencia, igual que los seis endpoints de arriba. Hasta entonces, los seis actuales son toda la superficie — todo lo que leas aquí sobre pilot, conduct o feedback es una nota de hoja de ruta, no un contrato.

Inicio rápido

Elige el endpoint adecuado según la forma del trabajo:

• Renderizar una página → empieza por el endpoint perceive.
• Mapear las URLs de un sitio → empieza por el endpoint discover.
• Buscar en la web → empieza por el endpoint lookup.
• Extraer campos estructurados → empieza por el endpoint distill.
• Construir un corpus RAG → empieza por el endpoint ingest.
• Monitorizar cambios → empieza por el endpoint watch.

Si aún no has hecho una primera llamada, la guía de inicio rápido recorre cómo obtener una clave y ejecutar una petición de principio a fin. Cada página de endpoint abre con su propia llamada curl útil más pequeña, así que puedes pegar una y tener una respuesta real de vuelta en menos de un minuto.