Autenticación

Cada solicitud a la API REST de ShipPDF necesita una clave de API del espacio de trabajo. Envíala en el encabezado Authorization para acceder a los proyectos, plantillas y documentos que permiten sus permisos.

Authorization: Bearer spdf_xxx

Crea una clave de API

Abre tu espacio de trabajo de ShipPDF.

Espacio de trabajo de ShipPDF con la lista de plantillas y la navegación lateral — Empieza en el espacio de trabajo que usará tu integración.

Abre Miembros y claves desde la barra lateral.

Página de miembros y claves antes de crear una clave de API — Gestiona los miembros del espacio de trabajo y las claves de API desde Miembros y claves.

Haz clic en Crear clave para abrir el diálogo Crear clave de API.

Diálogo para crear una clave de API con nombre, permisos, acceso a recursos y caducidad — Asigna a la clave un nombre que identifique tu integración.

Para el inicio rápido, selecciona documents:create y documents:read para generar un documento y consultar cuándo está listo su PDF. Elige el acceso a recursos y la caducidad que necesita tu integración, y haz clic en Crear clave.

Configuración de clave con documents:create y documents:read seleccionados, acceso a todo el espacio de trabajo y caducidad de 30 días — Este ejemplo usa ambos permisos de documentos, acceso a todo el espacio de trabajo y una caducidad de 30 días.

Copia la nueva clave y guárdala de forma segura. Aparecerá en la lista de claves de API del espacio de trabajo.

Clave de API creada en la lista del espacio de trabajo con el secreto oculto — La clave creada aparece en la lista con su secreto oculto.

Trata la clave como una contraseña. Guárdala en las variables de entorno o en el almacén de secretos de tu servidor, y mantenla fuera del código del navegador y del control de versiones.

Autentica una solicitud

La URL base de la API REST es https://api.shippdf.com/v1. Incluye tu clave como token bearer en cada solicitud:

Authorization: Bearer spdf_xxx

Por ejemplo, consulta un documento con una clave que tenga el permiso documents:read. Sustituye la clave y el ID de documento del ejemplo por tus propios valores:

export SHIPPDF_API_TOKEN="spdf_xxx"

curl https://api.shippdf.com/v1/documents/doc_a1b2c3 \
  -H "Authorization: Bearer $SHIPPDF_API_TOKEN"

Usa un documento del espacio de trabajo al que pertenece la clave.

Abre Solicitudes para encontrar un documento generado. Si la lista está vacía, genera primero un documento de ejemplo.

Página de solicitudes vacía en el espacio de trabajo de ShipPDF — Si la lista de solicitudes está vacía, debes generar un documento antes de consultarlo.

Elige una plantilla publicada y sigue el inicio rápido para generar un documento. Un borrador debe publicarse antes de usarse con la API.

Plantilla Start here publicada con la revisión v1 y la acción de generar — La plantilla Start here está publicada como revisión v1 y lista para generar documentos.

Cuando la generación termine correctamente, selecciona la solicitud para consultar su respuesta. Usa Copiar ID del documento para obtener el ID que necesita la solicitud autenticada del ejemplo anterior.

Solicitud de documento de API completada con su respuesta, ID de documento y acción de descargar el PDF — Una solicitud completada muestra el estado del documento y la URL del PDF.

Elige los permisos

Los permisos controlan qué operaciones puede realizar una clave. Elige los que necesita tu integración:

Permiso	Acceso	Herramientas MCP
`projects:read`	Listar proyectos.	`list_projects`
`templates:read`	Listar y consultar plantillas y sus metadatos.	`list_templates`, `get_template`, `get_template_metadata`
`templates:write`	Crear plantillas, consultar borradores, editarlos, publicarlos e importar imágenes mediante MCP. Actualmente ningún endpoint REST requiere este permiso.	`get_authoring_guide`, `describe_schema`, `create_template`, `get_draft_template`, `edit_template`, `update_template`, `publish_template`, `import_asset`
`documents:create`	Generar un documento a partir de una plantilla publicada.	`generate_document`
`documents:read`	Consultar un documento generado, incluido su estado y la URL del PDF.	`get_document`
`webhooks:manage`	Reservado para gestionar webhooks. Actualmente ningún endpoint REST ni herramienta MCP requiere este permiso.	Ninguna actualmente.
`*`	Acceso completo a los endpoints REST y las herramientas MCP dentro del acceso a recursos de la clave.	Todas las herramientas.

La referencia de la API indica el permiso que necesita cada endpoint REST. La referencia de permisos de MCP enumera los permisos que necesitan sus herramientas.

Para recibir una notificación cuando termine la generación de un documento, incluye webhook_url al generarlo con documents:create; no necesitas webhooks:manage.

Resuelve errores de autenticación

401: Clave ausente o no válida

La API devuelve 401 si la clave falta, tiene un formato incorrecto, ha caducado o se ha revocado. Comprueba que la solicitud incluya el encabezado Authorization con Bearer seguido de tu clave. Si la clave ha caducado o se ha revocado, crea otra y actualiza tu integración.

{
  "errors": {
    "detail": "A valid API token is required"
  }
}

403: Falta un permiso

La API devuelve 403 si la clave no tiene el permiso que necesita el endpoint. Consulta ese endpoint en la referencia de la API y usa una clave con el permiso correspondiente. Por ejemplo, generar un documento necesita documents:create; consultarlo necesita documents:read.

{
  "errors": {
    "detail": "API token does not have the required scope"
  }
}

Próximos pasos

Genera tu primer PDF con el inicio rápido.
Explora los endpoints en la referencia de la API.
Usa una clave de API del espacio de trabajo para conectar un asistente de IA mediante MCP.