Generar un PDF desde una plantilla existente

Usa este flujo cuando tu espacio de trabajo ya tenga una plantilla publicada. Tu asistente proporciona los datos y ShipPDF genera el PDF con la revisión publicada de esa plantilla.

Antes de empezar

Conecta tu cliente con documents:create y documents:read. Agrega templates:read para que el asistente pueda descubrir plantillas y consultar sus esquemas de datos. Si proporcionas un ID de plantilla conocido y ya conoces su esquema, bastan los dos permisos de documentos.

La plantilla debe estar publicada y el espacio de trabajo necesita créditos de generación disponibles. Si primero necesitas crear una plantilla, sigue Crear una plantilla con IA.

Pedirlo al asistente

Usa ShipPDF para generar la factura INV-1042 para Acme con mi plantilla de facturas publicada. Consulta primero su esquema de datos y pídeme los valores que falten. Genera un documento, espera a que termine y dame el enlace del PDF.

Proporciona los datos reales de la factura junto con tu solicitud. Si tienes varias plantillas de facturas, incluye un ID de plantilla o un nombre de proyecto para que el asistente elija la correcta.

1. Encontrar la plantilla y consultar su esquema

El asistente llama a list_templates, opcionalmente limitado por project_id, y después a get_template_metadata con el template_id seleccionado.

Los metadatos incluyen la revisión publicada y data_schema, sin el diseño completo ni los datos de ejemplo. Úsalos para preparar los datos de generación. Las rutas de campo y los tipos de valor deben coincidir con la plantilla; una descripción como «factura para Acme» no basta para proporcionar todos los campos.

2. Generar el documento

El asistente llama a generate_document con el ID de plantilla y los datos. Este ejemplo supone que la plantilla elegida tiene un campo invoice.number; sustitúyelo por datos que coincidan con tu plantilla:

{
  "template_id": "tmpl_example",
  "data": {
    "invoice": {
      "number": "INV-1042"
    }
  },
  "idempotency_key": "invoice-INV-1042"
}

Una llamada correcta consume un crédito de generación y devuelve un document_ref y un estado inicial como queued. No devuelve un PDF terminado inmediatamente.

Usa un idempotency_key estable y no vacío para la misma generación prevista. Reintentar con esa clave devuelve el documento original sin volver a cobrar. Usa una clave nueva para un documento nuevo; reutilizar una clave no vuelve a generar el PDF con datos modificados.

3. Esperar al PDF

Llama a get_document con la referencia devuelta:

{
  "document_ref": "doc_example"
}

Consulta con una pausa entre llamadas hasta que el estado sea completed o failed. Al terminar, devuelve pdf_url. Si falla, lee failure.code y failure.message y explica qué hay que corregir antes de generar de nuevo.

La URL del PDF es un enlace firmado de corta duración. Descarga el archivo mientras el enlace sea válido. Si caduca, llama a get_document otra vez para solicitar uno nuevo. Si un documento terminado tiene pdf_url temporalmente no disponible, también puedes consultarlo de nuevo sin iniciar otra generación.

Separar la generación de los cambios de plantilla

Generar un documento proporciona datos de ejecución a una plantilla publicada. No edita ni publica la plantilla. Si el diseño necesita un cambio, sigue el flujo de creación, publica la revisión corregida y genera un documento nuevo.

Consulta Límites y errores para los reintentos, los errores de créditos y las plantillas no disponibles.