Capacidades y permisos

ShipPDF ofrece a tu asistente herramientas para descubrir plantillas publicadas, generar PDF y crear plantillas reutilizables. ShipPDF aplica los permisos en cada llamada. Un mensaje puede orientar el comportamiento del asistente; los permisos y el acceso a recursos de la conexión determinan qué puede hacer.

Permisos de API y herramientas MCP

Las claves de API y las conexiones OAuth usan los mismos permisos específicos. Las herramientas cuyo permiso requerido falta se ocultan de la lista y no se pueden llamar. El acceso a recursos limita además los proyectos, plantillas y documentos que puede alcanzar una clave de API.

Permiso de API	Herramienta MCP	Qué hace
`projects:read`	`list_projects`	Lista los proyectos accesibles y sus IDs.
`templates:read`	`list_templates`	Lista las plantillas publicadas accesibles.
`templates:read`	`get_template_metadata`	Lee el nombre, la descripción, la revisión y el esquema de datos de una plantilla publicada.
`templates:read`	`get_template`	Lee los metadatos publicados y el documento completo de la plantilla.
`documents:create`	`generate_document`	Encola la generación de PDF desde una plantilla publicada; consume un crédito de generación.
`documents:read`	`get_document`	Lee el estado de generación, los detalles de fallo y la URL del PDF terminado.
`templates:write`	`get_authoring_guide`	Lee el flujo de creación, las reglas de diseño y el ejemplo completo.
`templates:write`	`describe_schema`	Lee el JSON Schema de un documento de plantilla o una definición concreta.
`templates:write`	`create_template`	Crea un borrador de plantilla en un proyecto accesible.
`templates:write`	`get_draft_template`	Lee el borrador actual, la versión de bloqueo, los problemas de validación y la URL de vista previa.
`templates:write`	`edit_template`	Aplica operaciones ordenadas a parte de un borrador.
`templates:write`	`update_template`	Cambia el nombre de una plantilla o sustituye todo su documento de borrador.
`templates:write`	`publish_template`	Publica el borrador como una revisión inmutable para futuras generaciones.
`templates:write`	`import_asset`	Importa una imagen pública PNG, JPEG o WebP a los recursos del espacio de trabajo.

Para claves de API, * concede todos los permisos dentro del acceso a recursos de la clave. webhooks:manage no tiene herramienta MCP. OAuth solo acepta los cinco permisos específicos anteriores. Consulta la referencia de la API para ver el permiso requerido por cada endpoint REST; las herramientas de creación de plantillas están disponibles mediante MCP y no mediante endpoints REST públicos equivalentes.

Leer un borrador requiere templates:write, aunque get_draft_template no lo modifica. Leer una plantilla publicada requiere templates:read.

Elegir permisos para tu flujo

Flujo	Permisos
Explorar plantillas publicadas	`templates:read`; agrega `projects:read` para explorar por proyecto.
Generar y obtener PDF con un ID de plantilla conocido	`documents:create`, `documents:read`.
Descubrir plantillas y generar PDF	`templates:read`, `documents:create`, `documents:read`.
Crear y publicar plantillas en un proyecto conocido	`templates:write`; agrega `projects:read` para descubrir proyectos.
Crear plantillas y generar PDF con ellas	`templates:write`, `documents:create`, `documents:read`; agrega permisos de lectura para el descubrimiento.

Publicar cambia la revisión que usan las generaciones futuras. Conceder acceso de creación permite al asistente editar y publicar; no hay un permiso de publicación separado. Tu cliente también puede pedir confirmación para llamadas de escritura.

Ayudar al asistente a trabajar con precisión

Proporciona el espacio de trabajo previsto, el ID del proyecto o de la plantilla si lo conoces, los datos de origen y el resultado que necesitas. Pídele que use los resultados de las herramientas para determinar los IDs y los esquemas.

Antes de generar: llamar a get_template_metadata para consultar el esquema de datos real. Respetar las rutas y los tipos de campo y pedir los valores que falten en lugar de inventarlos.
Antes de crear: llamar a get_authoring_guide y después a describe_schema para estructuras desconocidas. Proporcionan las reglas de diseño y las formas de entrada admitidas por ShipPDF.
Antes de editar: leer el borrador con get_draft_template. Usar sus IDs de nodo y su último lock_version en lugar de valores recordados.
Antes de publicar: revisar publishable y problems y comprobar la vista previa con datos de ejemplo representativos. Un esquema válido por sí solo no confirma que el diseño se vea bien.
Después de generar: consultar get_document. Informar del éxito solo cuando su estado sea completed y haya una URL de PDF disponible.

Por ejemplo:

Usa la plantilla de facturas de ShipPDF. Lee primero sus metadatos, muéstrame los datos necesarios que no he proporcionado y genera un PDF. Reutiliza la misma clave de idempotencia si hay que reintentar la solicitud y devuelve el enlace del PDF terminado.

Para crear una plantilla:

Lee la guía de creación de ShipPDF y crea un borrador de factura A4 en el proyecto proj_example. Usa los datos de la factura adjunta como datos de ejemplo. Muéstrame la vista previa y corrige los problemas indicados. Déjalo como borrador para mi revisión.

Recursos MCP

Los clientes compatibles con recursos pueden leer el mismo material de referencia sin una llamada a herramienta:

URI del recurso	Contenido	Permiso
`shippdf://recipe/authoring`	Guía de creación.	`templates:read` o `templates:write`
`shippdf://schema/template-document/{version}`	JSON Schema del documento de plantilla.	`templates:read` o `templates:write`
`shippdf://templates/{template_id}`	Documento de plantilla publicada.	`templates:read`

Usa las URI concretas que devuelve la lista de recursos del servidor; las llaves anteriores indican partes variables.

Siguiente: Generar un PDF o Crear una plantilla con IA.