Generar un documento

Qué hace este endpoint

Una llamada convierte una plantilla y tus datos en un archivo terminado. El documento se genera mientras esperas y la respuesta incluye una dirección de descarga; no hay que consultar el estado. Para documentos largos o trabajo por lotes, el endpoint en cola hace lo mismo en segundo plano.

Envía el código de plantilla y tus datos y recibe el documento. La URL de descarga de la respuesta es relativa a la dirección base y se solicita con la misma clave API.

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "es",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

El campo format admite "pdf" o "docx". Los valores numéricos siguen funcionando para los clientes existentes: 1 es PDF y 2 es DOCX. Las respuestas devuelven el formato como número.

El propósito production consume cuota. Mientras pruebas una plantilla, envía editor-test: esa salida no consume cuota y usa la revisión del borrador sin publicar.

El ciclo completo

Esta es la respuesta a la llamada anterior y la llamada para obtener el archivo. El estado es 202: la solicitud se ha aceptado y el documento está listo.

HTTP/1.1 202 Accepted
X-PDFgine-Pages: 1
X-PDFgine-Quota-Remaining: 4999

{
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 1,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent"
}

curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

Los errores más habituales

• La renderización responde 202, no 200. Un cliente que considere un fallo cualquier código distinto de 200 notificará un éxito como error.
• purpose decide dos cosas a la vez: production usa la versión publicada y consume cuota; editor-test usa el borrador sin publicar y no consume nada. Probar con production es la forma más cara de experimentar con una plantilla.
• 422 no es un fallo del servidor. El cuerpo lista en errors todos los campos que esperaba la plantilla; la solución está en los datos enviados, no en reintentar.
• 402 significa que se ha agotado la cuota mensual de páginas. La cabecera X-PDFgine-Quota-Remaining te avisa antes de llegar a ese punto.
• downloadUrl es relativa a la dirección de la API. Guardarla como URL absoluta fallará cuando cambie la dirección; guarda documentId y construye la dirección.