Guía del producto y de la API
Respuesta
Qué devuelve
Toda renderización correcta devuelve el mismo objeto. Conviene conservar dos campos: documentId identifica el archivo mientras se conserve y pageCount determina lo que se factura en el mes.
Respuesta
{
"documentId": "doc_5bd26de32c324a4bb8cffad2c80edd01",
"jobId": "job_00b96f006b034258b00b650d724d0207",
"fileName": "invoice-doc_5bd26de32c324a4bb8cffad2c80edd01.pdf",
"format": "pdf",
"templateCode": "invoice",
"templateVersion": 5,
"templateVersionSource": "published",
"downloadUrl": "/api/v1/documents/doc_5bd2.../download/pdf",
"previewUrl": null,
"pageCount": 1,
"quotaRemaining": 4999,
"meteringBasis": "pdf-equivalent",
"createdAt": "2026-08-28T13:23:32+00:00"
}Una renderización es privada y su descarga requiere tu clave API. Usa el endpoint de vista previa solo cuando necesites deliberadamente un enlace temporal para un cliente.
Cabeceras de respuesta
Todas las respuestas de renderización repiten las cifras de uso en sus cabeceras para poder seguir la cuota sin otra llamada.
X-PDFgine-Pages | Número de páginas de este documento |
|---|---|
X-PDFgine-Job | Identificador del trabajo de renderización |
X-PDFgine-Quota-Remaining | Páginas restantes tras la operación |
X-PDFgine-Metering-Basis | Unidad de medición |
Campo por campo
Se devuelven los mismos campos para pdf, docx y html; solo cambia fileName.
| Campo | Qué significa |
|---|---|
documentId | El identificador del archivo generado. Las descargas, el estado y el uso compartido lo utilizan, por lo que es el valor que conviene guardar. |
downloadUrl | Relativa a la dirección de la API y obtenida con la misma clave. Es una ruta, no un enlace público. |
templateVersion | Qué versión de la plantilla generó este archivo. Consérvala para poder explicar una reimpresión meses después. |
templateVersionSource | published para una renderización de producción; draft cuando purpose era editor-test. |
pageCount | Cuántas páginas se generaron; es lo que contabiliza la cuota. |
quotaRemaining | Páginas restantes del mes actual en el momento de esta respuesta. |
meteringBasis | Qué significa una página a efectos de facturación. pdf-equivalent contabiliza una salida docx o html con el mismo número de páginas que tendría el PDF. |
previewUrl | Solo se rellena si el documento se compartió; de lo contrario, null. |
Los errores más habituales
- downloadUrl es una ruta. Pegarla en un navegador sin la dirección de la API y la clave devuelve un 404 o un 401, no el archivo.
- Guarda documentId, no la respuesta completa. Los archivos se eliminan al finalizar el plazo de conservación de tu plan y una URL guardada dejará de apuntar a un archivo.
- quotaRemaining es una instantánea de ese momento, no un contador en directo. Dos llamadas simultáneas pueden leer el mismo número.
- pageCount es la unidad de facturación, no el número de archivos. Un documento de diez páginas consume diez páginas tanto si pides pdf como docx.
- Que previewUrl sea null no significa que el uso compartido fallara; significa que esta renderización no se compartió. Compartir es una llamada independiente.