API Documentation

Callbacks de Webhook y Notificaciones de Trabajos de Conversión#

EnConvert te avisa cuando los trabajos de conversión asíncronos y por lotes finalizan a través de tres mecanismos independientes: sondeo de GET /v1/convert/batch/{batch_id}, callbacks de webhook mediante el parámetro callback_url, y notificaciones por correo mediante notification_email. Los tres se pueden combinar en una misma solicitud, y los archivos terminados se recuperan mediante las URL de descarga incluidas en la respuesta de estado del lote. Esta página documenta los payloads de callback, los requisitos de entrega y las restricciones por plan de cada método.

Solo claves privadas: Las notificaciones de trabajos y el sondeo del estado del lote solo están disponibles al autenticarse con una clave de API privada (X-API-Key: sk_...). Las claves públicas no admiten procesamiento asíncrono ni por lotes.

Resumen#

Método Parámetro / Endpoint Descripción
Polling GET /v1/convert/batch/{batch_id} Sondea el estado en tiempo real, los recuentos de progreso y las URL de descarga.
Email notification_email Envía un correo de finalización con el estado del trabajo y un enlace al panel.
Webhook callback_url Envía una solicitud POST con los resultados del trabajo a tu servidor.

Los tres métodos funcionan tanto para trabajos asíncronos de una sola URL como para trabajos por lotes de múltiples URL en los endpoints url-to-pdf, url-to-screenshot, website-to-pdf y website-to-screenshot.

Sondeo del estado del lote#

La forma recomendada de hacer seguimiento del progreso de un trabajo. Sondea el endpoint de estado del lote con el batch_id devuelto en la respuesta inicial 202.

GET /v1/convert/batch/{batch_id}
X-API-Key: sk_your_private_key

Respuesta#

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total": 3,
    "completed": 1,
    "failed": 0,
    "in_progress": 2,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        }
    ]
}

Valores de estado#

Estado Significado
processing Al menos una URL todavía se está convirtiendo.
completed Todas las URL se convirtieron correctamente.
partial Todas las URL terminaron, pero algunas fallaron.
failed Todas las URL fallaron.

En modo ZIP (output_mode: "zip"), se proporciona un zip_download_url para el archivo completo cuando finaliza. En modo individual, cada elemento tiene su propio download_url.

Para conocer todos los detalles del esquema de respuesta, consulta Procesamiento por lotes.

Notificaciones por correo electrónico#

Incluye el parámetro notification_email en tu solicitud para recibir un correo cuando el trabajo finalice. Si omites este parámetro, el correo se envía de forma predeterminada a la dirección de correo del propietario del proyecto.

Ejemplo#

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "notification_email": "[email protected]"
  }'

Respuesta (HTTP 202 Accepted)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 1,
    "output_format": "individual"
}

Contenido del correo#

El correo de finalización incluye:

  • Encabezado de estado con un banner de color (verde para éxito, rojo para fallo)
  • Job ID y Batch ID (si forma parte de un lote)
  • Texto de estado (éxito o fallo)
  • Texto fijo que indica a los usuarios que descarguen los archivos desde su panel
  • Tabla de tareas (solo trabajos por lotes en modo ZIP) con las columnas: #, URL (truncada a 50 caracteres), estado y nombre del archivo de salida

En modo individual (incluidos los lotes individuales de múltiples URL), cada correo por URL contiene únicamente el job ID y el estado -- sin tabla de tareas. En modo ZIP, el único correo del lote incluye la tabla de tareas completa con todas las URL y sus estados.

Comportamiento predeterminado: Si no incluyes notification_email en tu solicitud, el correo de finalización se envía automáticamente a la dirección de correo del propietario del proyecto. Para suprimir por completo las notificaciones por correo, este valor predeterminado no se puede deshabilitar actualmente.

Callbacks por webhook#

Incluye el parámetro callback_url en tu solicitud para recibir un POST de webhook cuando el trabajo finalice. Requiere un plan con acceso a webhooks.

Ejemplo#

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

Respuesta (HTTP 202 Accepted)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 1,
    "output_format": "individual"
}

Payload del callback en modo de URL única / individual#

En modo individual, se envía un POST separado por cada URL a medida que finaliza:

{
    "job_id": "12345",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/example_20260405_123456789.pdf",
    "filename": "example_20260405_123456789.pdf",
    "file_size": 184320
}

Para una conversión fallida:

{
    "job_id": "12345",
    "status": "failed",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000"
}

Payload del callback en modo ZIP#

En modo ZIP, se envía un único POST cuando el lote completo finaliza:

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/batch_20260405_123456789.zip",
    "filename": "batch_20260405_123456789.zip",
    "file_size": 456789,
    "total_tasks": 3,
    "successful_tasks": 2,
    "failed_tasks": 1,
    "tasks": [
        {"url": "https://example.com/page-1", "status": "success", "filename": "page1.pdf"},
        {"url": "https://example.com/page-2", "status": "success", "filename": "page2.pdf"},
        {"url": "https://invalid-url.example", "status": "failed", "error": "Page load timeout"}
    ]
}
Comportamiento de notificación individual vs ZIP: En modo individual, recibes N POST de webhook separados (uno por URL) y N correos separados. En modo ZIP, recibes un POST de webhook y un correo para todo el lote. Diseña tu manejador de webhooks en consecuencia.

Uso conjunto de varios métodos de notificación#

Puedes combinar polling, email y webhook en la misma solicitud. Los tres funcionan de forma independiente.

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://example.com/page-1",
      "https://example.com/page-2"
    ],
    "notification_email": "[email protected]",
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

Tras enviar la solicitud, puedes: 1. Sondear GET /v1/convert/batch/{batch_id} para conocer el progreso en tiempo real 2. Recibir un POST de webhook en tu URL de callback cuando cada conversión termine 3. Recibir un correo en la dirección especificada cuando cada conversión termine

Parámetros de notificación#

Parámetro Tipo Obligatorio Predeterminado Descripción Restricción por plan
notification_email string No Correo del propietario del proyecto Dirección de correo que recibe las notificaciones de finalización del trabajo. --
callback_url string No -- URL que recibe un POST de webhook al finalizar. Requiere acceso a webhooks

Requisitos de entrega de webhooks#

Requisito Detalle
Método EnConvert envía una solicitud POST con Content-Type: application/json.
Tiempo de espera Tu endpoint debe responder en 30 segundos.
Códigos de éxito Los HTTP 200, 201, 202 o 204 se consideran entrega exitosa.
Reintentos No hay reintentos en caso de fallo. Si la entrega del webhook falla (respuesta sin éxito o tiempo de espera agotado), los resultados siguen disponibles mediante el sondeo del estado del lote.
Autenticación No se envían encabezados de autenticación. Valida el batch_id con tus registros si es necesario.

Restricciones por plan de suscripción#

Función Founding Indie Studio Enterprise
Modo asíncrono No Sí Sí Sí
Sondeo del estado del lote No Sí Sí Sí
Notificaciones por correo No Sí Sí Sí
Callbacks por webhook (callback_url) No No Sí Sí
Nota: Las notificaciones por correo no tienen una restricción de función independiente -- están disponibles para cualquier usuario de clave de API privada con acceso asíncrono. El parámetro notification_email no requiere una función de plan específica. Los callbacks por webhook (callback_url) requieren la función has_webhook, que está disponible en los planes Studio y superiores.

Pruebas de webhooks#

Durante el desarrollo, usa webhook.site para generar una URL de callback temporal con fines de prueba:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "callback_url": "https://webhook.site/your-unique-id"
  }'

Visita tu panel de webhook.site para inspeccionar el payload exacto del callback una vez que el trabajo finalice.

Preguntas frecuentes#

¿Cómo recibo un callback de webhook cuando finaliza un trabajo de conversión de archivos?#

Incluye el parámetro callback_url en tu solicitud con una clave de API privada. EnConvert envía un POST con Content-Type: application/json a esa URL cuando el trabajo finaliza. Los callbacks de webhook requieren un plan con acceso a webhooks (Studio, Production o Enterprise).

¿EnConvert reintenta las entregas de webhook fallidas?#

No. Tu endpoint debe responder en 30 segundos con HTTP 200, 201, 202 o 204. Si la entrega falla, los resultados siguen disponibles mediante el sondeo del estado del lote en GET /v1/convert/batch/{batch_id}.

¿Puedo usar notificaciones por correo, webhook y polling juntos?#

Sí. notification_email, callback_url y el sondeo de estado funcionan de forma independiente y se pueden combinar en la misma solicitud. Si se omite notification_email, el correo de finalización se envía por defecto a la dirección del propietario del proyecto.

¿Por qué recibo un webhook por cada URL en lugar de uno para todo el lote?#

En modo individual recibes N POST de webhook separados (uno por URL) y N correos separados. Para recibir un único webhook y un único correo para todo el lote, usa el modo ZIP, que envía un solo POST con total_tasks, successful_tasks, failed_tasks y un array tasks.

¿Cómo puedo probar los callbacks de webhook durante el desarrollo?#

Usa webhook.site para generar una URL temporal y pásala como callback_url en tu solicitud. El panel de webhook.site muestra el payload JSON exacto que EnConvert entrega cuando el trabajo finaliza.

← File Ingestion Batch Processing →