Crear una plantilla con IA
Pide a tu asistente que convierta la descripción de un documento en una plantilla reutilizable de ShipPDF. El asistente crea un borrador, define los campos de datos y ajusta el diseño mediante MCP. Una vez publicada, la plantilla puede generar PDF con distintos datos mediante MCP o la API REST.
Antes de empezar
Conecta tu cliente con templates:write. Proporciona un ID de proyecto o concede projects:read para que el asistente pueda encontrar un proyecto. Agrega templates:read si quieres que consulte plantillas publicadas como referencia.
Para generar un PDF después de publicar, concede también documents:create y documents:read y asegúrate de que el espacio de trabajo tenga créditos de generación.
Describir el documento
Proporciona el tamaño del papel, la orientación, las secciones de contenido, la identidad de marca, los campos dinámicos y datos representativos. Indica si quieres un borrador para revisión o una plantilla publicada.
Crea una plantilla de factura A4 vertical en el proyecto proj_example. Incluye un logotipo, dirección de facturación, número de factura, fecha, tabla de artículos, subtotal, impuestos y total. Lee primero la guía de creación de ShipPDF. Define el esquema de datos y usa mi factura de ejemplo como datos de muestra. Dame una vista previa y déjala como borrador para revisión.
1. Leer la guía de creación
El asistente debe llamar a get_authoring_guide antes de crear un documento. Devuelve el flujo, las reglas de diseño admitidas y un ejemplo completo. Usa describe_schema para ver la forma exacta de un documento o una definición concreta.
La creación admite entradas abreviadas: los nodos necesitan su type, más children para los contenedores, y los ajustes omitidos reciben los valores predeterminados del editor. Los tamaños necesitan unidades explícitas, como pt, mm o in. Usa rutas de datos completas como invoice.items.description al vincular campos.
2. Crear o retomar un borrador
Usa create_template con project_id, name y document. Para retomar una plantilla existente, usa get_draft_template con su template_id.
La respuesta incluye:
| Campo | Cómo usarlo |
|---|---|
template_id | Identifica la plantilla en llamadas posteriores. |
lock_version | Pasa el último valor al editar o sustituir el borrador. |
pages | Comprueba el tamaño de página, los márgenes y el área de contenido. |
publishable | true indica que pasó la comprobación de publicación; false indica problemas pendientes; null indica que no se pudo ejecutar la comprobación. |
problems | Resuelve los problemas indicados, incluidos los nodos y las ubicaciones afectados cuando se proporcionan. |
mcp_preview_url | Abre el borrador guardado con datos de ejemplo para revisarlo visualmente. |
Un borrador puede guardarse con problemas de publicación. Guardarlo no lo hace disponible para generar documentos.
3. Editar y revisar la vista previa
Usa edit_template para cambiar parte de un borrador. Acepta una lista ordenada de operaciones:
| Operación | Propósito |
|---|---|
add | Agregar un nodo bajo un padre. |
update | Cambiar los campos o ajustes de un nodo. |
move | Mover un nodo a un padre y una posición. |
remove | Eliminar un nodo. |
set_data_schema | Sustituir el esquema de datos de la plantilla. |
set_sample_data | Sustituir los datos de ejemplo usados en la vista previa. |
Lee los IDs de nodo existentes del borrador y pasa el último lock_version. Las operaciones se aplican todas o ninguna: si una falla, no se guarda ninguna. Usa update_template cuando sea más sencillo sustituir todo el documento del borrador o cambiar su nombre.
Si otra edición cambia el borrador primero, ShipPDF devuelve un lock_version_conflict con el borrador actual. Revísalo, vuelve a aplicar los cambios previstos y reintenta con la versión devuelta.
Abre mcp_preview_url para revisar el diseño guardado. El enlace dura unos 15 minutos; llama a get_draft_template para obtener otro. Si tu cliente tiene herramientas de navegador, pídele que revise la vista previa mediante su flujo habitual de permisos de navegador. Si no, abre el enlace y describe los cambios que quieres.
La vista previa usa datos de ejemplo y no consume créditos de generación. Ayuda a revisar el diseño, pero no verifica la paginación final del PDF. Prueba el PDF terminado con datos representativos, incluidas tablas y textos largos.
Comprobar la precisión con Claude in Chrome o ChatGPT in Chrome
Da acceso al navegador a tu asistente para que pueda abrir la vista previa, recorrer el documento y revisar el diseño visible mientras crea la plantilla. Esto ayuda a detectar texto recortado, elementos superpuestos, espaciado incorrecto y datos ausentes o mal vinculados que la validación del esquema por sí sola puede no revelar.
- Claude in Chrome: instala y activa la extensión y permite que Claude interactúe con la vista previa de ShipPDF. Sigue la guía de configuración de Claude in Chrome.
- ChatGPT in Chrome: conecta la extensión de navegador de ChatGPT a la aplicación de escritorio, selecciona Chrome mediante una mención
@y permite el acceso al sitio de la vista previa. Sigue la guía de la extensión de navegador de ChatGPT.
Mantén disponible la conexión MCP de ShipPDF en la misma conversación. MCP proporciona las herramientas de creación; la extensión de navegador permite al asistente ver el resultado. Pídele que siga este ciclo de revisión:
- Abrir el último
mcp_preview_urly comparar el diseño y los valores mostrados con tus requisitos y datos de ejemplo. - Comprobar la alineación, los márgenes, la tipografía, las imágenes, las columnas de tablas y los textos largos. Usar los controles de inspección de la vista previa para identificar los nodos afectados.
- Corregir los problemas con
edit_template, recargar la vista previa y comprobar los cambios guardados. Repetir con datos representativos, incluidas tablas largas y campos opcionales. - Después de publicar, generar un PDF de prueba y revisar el archivo terminado para comprobar los saltos de página, el desbordamiento y la precisión de los datos. Cada nueva generación de prueba consume un crédito.
Por ejemplo:
Usa MCP de ShipPDF para crear la plantilla y Chrome para revisarla visualmente. Abre la vista previa del borrador, compárala con mi referencia y los datos de ejemplo, corrige los errores de diseño o vinculación y comprueba la vista previa de nuevo. Deja el borrador para mi revisión antes de publicar.
Si no hay acceso al navegador, abre la vista previa y comparte capturas o describe los problemas. La revisión visual ayuda a encontrar errores; verifica también los valores del PDF final con los datos de origen.
Agregar imágenes
Usa import_asset con una URL pública PNG, JPEG o WebP de hasta 10 MB. Devuelve un asset_id. Referencia esa imagen con un imageSource de tipo asset, usando el ID devuelto como assetId. Las URL privadas y de loopback están bloqueadas.
4. Publicar la plantilla
Después de resolver los problems del borrador y revisar su diseño, llama a publish_template. Rechaza los borradores con problemas de publicación pendientes y crea una revisión inmutable si tiene éxito.
Publicar cambia lo que producen las generaciones futuras de esta plantilla. Las ediciones posteriores del borrador no afectan a esa revisión hasta que publiques de nuevo. Si pediste un borrador para revisión, indica al asistente que se detenga antes de publicar.
5. Generar un PDF
Usa el ID de la plantilla publicada con generate_document y después consulta get_document. Sigue Generar un PDF desde una plantilla existente para ver el flujo completo, incluidos los reintentos seguros y los enlaces de descarga.
Consulta Límites y errores para los problemas de validación y los conflictos de edición.