# Referencia de la API de renderizado

Representa puntos finales API, encabezados de autenticación y campos de solicitud.

## Autenticación
Envíe un encabezado `ApiKey` para una clave de proyecto con `template:render`. Esta no es una sesión de navegador.

## POST /v1/pdf/render
| Campo JSON | Significado |
| --- | --- |
| `template_id` | UUID de plantilla requerido, no un slug |
| `version` | Número de versión; omitido selecciona la versión actual de la plantilla |
| `variant` | Nombre de variante opcional |
| `parameters` | Objeto de entrada que coincide con la plantilla |

El objetivo debe estar publicado. El renderizado utiliza contenido comprometido, no ediciones del navegador no guardadas. La aceptación es HTTP 202 con `render_id`, `status: queued` y `status_url`, no con bytes PDF ni con una garantía de éxito.

## GET /v1/renders/{render_id}
Utilice la misma clave. La respuesta incluye `render_id`, `status` y campos de resultados opcionales como `error_message`, `duration_ms` y `download_url`. El procesamiento es `pending`; Los estados terminales son `success`, `failed` y `quota_exceeded`.

Inmediatamente después de una respuesta 202, el punto final de estado puede devolver brevemente **404** mientras el flujo de trabajo crea su fila de historial. Vuelva a intentar ese ID de renderizado recién aceptado con un breve retraso y una fecha límite limitada. Es necesario investigar un 404 persistente, una identificación desconocida o una discrepancia entre un proyecto y una clave; no vuelva a enviar POST solo porque la primera búsqueda de estado arrojó 404.

## GET /v1/renders/{render_id}/download
Utilice una clave de proyecto adecuada. La salida exitosa devuelve bytes PDF mientras estén disponibles. No es una URL pública permanente.

## Errores y reintentos
La autenticación, la propiedad y las versiones faltantes o no publicadas pueden fallar antes de su aceptación. Los fallos de procesamiento posteriores aparecen a través del estado. Corrija las solicitudes/permisos 4xx antes de volver a intentarlo y no asuma el soporte público de idempotencia POST.

## Respuesta de error
Los errores utilizan `code`, `description` y `details` opcional. Lea el código para decidir qué arreglar; un renderizado aceptado puede fallar más tarde e informar `error_message` a través del estado.

```json
{"code":"PDF_TEMPLATE_VERSION_NOT_PUBLISHED","description":"template version is not published","details":[]}
```

Una respuesta de estado exitosa puede incluir:

```json
{"render_id":"<render-uuid>","status":"success","duration_ms":1200,"download_url":"/v1/renders/<render-uuid>/download"}
```

Una falla de procesamiento es un resultado de estado, por ejemplo:

```json
{"render_id":"<render-uuid>","status":"failed","error_message":"Failed to compile template"}
```

## Alcance
Esta referencia cubre los puntos finales de renderizado públicos, no todos los API de administración de solo sesión utilizados por la aplicación. Encuesta con retrasos y plazo acotado; conservar el ID de renderizado después de la aceptación.