Conceptos

ShipPDF genera PDF terminados a partir de plantillas reutilizables. Esta página define los términos centrales y cómo se relacionan, y termina con un glosario para consulta rápida.

Espacios de trabajo y proyectos

Todo lo que creas vive en un espacio de trabajo, la cuenta de tu equipo y el límite para la facturación, los miembros y las claves de API. Dentro de un espacio de trabajo, las plantillas se agrupan en proyectos para que el trabajo relacionado quede junto, como un proyecto por cliente o por tipo de documento.

Plantillas

Una plantilla es el diseño reutilizable en el corazón de ShipPDF. Contiene el diseño de página (cómo se ve) y un esquema de datos (los campos que espera que se llenen). Diseñas una plantilla una vez y luego generas muchos PDF a partir de ella. El diseño permanece fijo mientras los datos cambian en cada PDF.

Borradores, problemas y publicación

Mientras la editas, una plantilla es un borrador. ShipPDF revisa el borrador en busca de problemas, como un campo faltante o un diseño roto, que le impedirían producir un PDF limpio. Cuando el borrador está listo, lo publicas, lo que lo congela como una revisión inmutable (mostrada como una versión, v1, v2, y así sucesivamente). Solo las revisiones publicadas pueden generar PDF, así que lo que entregas siempre está completo. Editar de nuevo inicia un borrador nuevo sobre la última revisión publicada.

Documentos y créditos

Un documento es un PDF generado. Generas un documento a partir de una plantilla publicada más los datos de ese resultado en concreto, y cada uno consume un crédito del saldo de tu espacio de trabajo.

La generación es asíncrona. Un documento nuevo empieza como queued, pasa a processing y termina en completed o failed. Un documento completado lleva un pdf_url de corta duración para descargar el archivo, y uno fallido no consume ningún crédito.

Los reintentos son seguros con una clave de idempotencia, un valor que adjuntas a una solicitud para que repetirla cuente como la misma solicitud y no como una nueva. Reutiliza la clave en un reintento y ShipPDF reproduce el documento original en lugar de consumir otro crédito.

Vinculación de datos

El enlace entre una plantilla y un documento es la vinculación de datos. El JSON que envías se compara con el esquema de datos de la plantilla, y cada campo cae en su lugar dentro del diseño. El esquema es el contrato, así que una vez que conoces el esquema de una plantilla sabes exactamente qué datos enviar para llenarla.

Formas de generar

Una vez publicada una plantilla, puedes generar documentos de tres formas, todas con el mismo resultado:

• Un formulario dentro de ShipPDF, para algo rápido y puntual sin escribir código.
• La API REST, para que tu propio software genere a escala. Consulta el inicio rápido y la referencia de la API.
• Un asistente de IA mediante MCP, donde pides en lenguaje natural y el asistente llama a ShipPDF para hacer el trabajo. Consulta la referencia de MCP.

Claves, permisos y MCP

El acceso programático usa una clave de API del espacio de trabajo, un secreto con el formato sk_live_.... Cada clave lleva permisos, que deciden qué puede hacer, como leer plantillas o generar documentos. Una clave solo tiene el acceso que le concedes.

MCP, el Model Context Protocol, es el estándar abierto que permite a un asistente de IA conectarse a una herramienta externa. ShipPDF expone un endpoint MCP, así que un asistente como Claude o ChatGPT puede descubrir tus plantillas y generar PDF a través de ShipPDF, con las mismas claves y permisos que la API.

Glosario