Integración con HubSpot
Genera cotizaciones, facturas, propuestas y otros PDF desde contactos, empresas y negocios de HubSpot. Instala la app, conecta un espacio de trabajo de ShipPDF y agrega Generate PDF document with ShipPDF a una vista de registros. La tarjeta te permite elegir una plantilla publicada, asignar propiedades del CRM, reutilizar asignaciones guardadas y abrir o descargar el PDF terminado.
La integración genera PDF cuando lo pides desde la tarjeta del registro. No adjunta el PDF al registro de HubSpot ni se ejecuta automáticamente cuando un negocio cambia de etapa.
Antes de empezar
Necesitas:
- Un espacio de trabajo de ShipPDF con acceso a la API, créditos de generación y una plantilla publicada.
- Permisos de propietario o administrador del espacio de trabajo de ShipPDF para autorizar la conexión.
- Una cuenta de HubSpot donde puedas instalar la app. Agregar la tarjeta a una vista compartida necesita permisos de Super Admin o Customize record page layout.
Diseña la plantilla según los datos que quieras usar. Agrega campos de texto, número y fecha para las propiedades del registro, y una colección para las partidas del negocio. La tarjeta obtiene los campos de la versión publicada, así que publica los cambios antes de usarlos en HubSpot. Consulta Crea tu plantilla y Esquema de datos y datos predeterminados.
El ejemplo usa la plantilla Quotation en un negocio llamado Booking Portal Proposal. Algunos campos aún empiezan por invoice, como invoice.customer.customerName. El nombre visible de una plantilla no cambia las rutas de sus campos. Tu tarjeta muestra las rutas definidas en tu propia plantilla.
Instala y conecta ShipPDF
1. Empieza la instalación desde ShipPDF
Abre tu espacio de trabajo de ShipPDF, selecciona Integraciones y elige HubSpot. Haz clic en Instalar en HubSpot.
2. Elige la cuenta de HubSpot
Inicia sesión en HubSpot si te lo pide. Selecciona la cuenta que quieras conectar y haz clic en Choose Account.
3. Revisa los permisos de HubSpot
Revisa el acceso que pide la app y elige Connect app cuando quieras continuar. El ejemplo pide acceso a contactos, empresas, negocios, partidas e información de identidad de la cuenta.
4. Autoriza un espacio de trabajo de ShipPDF
Después del paso de HubSpot, inicia sesión en ShipPDF si hace falta. En Conectar HubSpot con ShipPDF, comprueba los datos de la cuenta y elige el espacio de trabajo que contiene tus plantillas. Haz clic en Autorizar el espacio de trabajo de ShipPDF.
La cuenta comparte esta conexión. Quienes tengan acceso a la tarjeta de ShipPDF en HubSpot podrán ver las plantillas publicadas del espacio de trabajo conectado, generar PDF con sus créditos y descargar los PDF generados desde la tarjeta. No necesitan una cuenta individual de ShipPDF. No tienes que crear ni pegar una clave de API durante la configuración.
Una cuenta de HubSpot puede tener una sola conexión activa con un espacio de trabajo de ShipPDF. Para cambiarla a otro, desconéctala primero del espacio de trabajo actual.
5. Vuelve a HubSpot
Cuando aparezca ShipPDF está conectado, elige Volver a HubSpot. Después, agrega la tarjeta a las vistas de registros donde la usará tu equipo.
Agrega la tarjeta de ShipPDF a una vista de registros
Instalar la app y agregar su tarjeta a una vista son pasos distintos. Configura cada tipo de objeto que necesite tu equipo, como contactos y negocios.
1. Abre la personalización de registros
En la configuración de HubSpot, abre Data Management → Objects. Selecciona el tipo de objeto y abre Record Customization. Entra en Default view o en la vista del equipo correspondiente.
Para el ejemplo del negocio, selecciona Deals y abre su Default view.
2. Busca ShipPDF en la biblioteca de tarjetas
En el editor de diseño, usa el control + de la columna central para agregar una tarjeta. Abre Card library, busca ShipPDF y haz clic en Add card en Generate PDF document with ShipPDF.
3. Guarda el diseño
Coloca la tarjeta donde tu equipo pueda encontrarla y elige Save and exit. Abre un registro que use esa vista.
HubSpot explica la configuración de vistas en Personalizar registros y Crear tarjetas para mostrar datos en registros.
Elige una plantilla y asigna campos
Abre un contacto, empresa o negocio y busca Generate PDF document with ShipPDF. Selecciona Project y Template. Elige New mapping para configurar una asignación nueva o selecciona una Saved mapping existente.
Para cada campo de la plantilla, elige una propiedad del registro actual, una propiedad de un contacto o empresa asociados, Enter a value o Leave empty.
| Origen | Comportamiento |
|---|---|
| Propiedad del registro actual | Lee el valor de esa propiedad del contacto, empresa o negocio abierto. |
| Propiedad de Contact o Company | Lee una propiedad de un registro asociado. Elige el registro si hay varios candidatos. |
| Enter a value | Usa un valor fijo. Para una lista o colección, introduce un arreglo JSON que coincida con el esquema de la plantilla. |
| Leave empty | Omite el campo de la petición y permite que se apliquen los valores predeterminados de la plantilla. |
| Deal line items | Disponible para colecciones en negocios. Convierte cada partida asociada en una fila. |
Los valores ausentes del CRM también se omiten. Revisa los datos predeterminados de la plantilla: dejar un campo de cliente vacío puede hacer que aparezca un nombre o dirección de ejemplo en el PDF si sigue configurado como valor predeterminado.
Los valores asignados deben coincidir con los tipos de campo de la plantilla. Los números deben ser numéricos y los valores booleanos deben ser true o false. Las fechas, listas desplegables y propiedades de selección múltiple pueden mostrar valores almacenados en lugar de las etiquetas con formato que ves en otras partes de HubSpot. Comprueba su compatibilidad antes de generar. Los campos calculados de la plantilla no son entradas editables en la tarjeta.
Usa una propiedad personalizada existente
La tarjeta empieza con propiedades comunes del registro. Si falta la que necesitas:
- Expande Custom properties.
- En Property belongs to, elige This record, Associated contact o Associated company.
- Escribe el nombre interno de la propiedad existente, como
invoice_number, en HubSpot property. - Elige Add property y selecciónala en el selector de origen del campo de la plantilla.
Add property no crea una propiedad en HubSpot. Hace que una propiedad existente esté disponible para esta asignación. Usa su nombre interno, no su etiqueta visible. Si no se pueden obtener las propiedades del registro, corrige la causa y usa Retry properties.
Incluye partidas del negocio
Para una colección como invoice.lineItems, elige Deal line items. En Each line item, asigna sus campos secundarios a las propiedades de las partidas. Por ejemplo, asigna la descripción a Description, la cantidad a Quantity y el precio unitario a Unit price. Usa los campos reales de tu plantilla.
Expande Custom line item properties para agregar el nombre interno de una propiedad existente de las partidas. Después de cambiar los productos del negocio, usa Refresh line items y revisa la cantidad de partidas obtenidas antes de generar.
Un negocio vacío produce una colección de partidas vacía. Si no se pueden obtener todas las partidas, se bloquea la generación en lugar de enviar una lista incompleta. Para colecciones introducidas manualmente con Enter a value, usa JSON, no un editor interactivo de filas.
Guarda y reutiliza asignaciones
Escribe un Mapping name claro, como Cotización de cliente, y elige Save mapping. Las asignaciones se comparten entre registros del mismo tipo de objeto en la cuenta conectada de HubSpot, para ese espacio de trabajo y esa plantilla.
En otro registro, elige el proyecto, la plantilla y la asignación guardada. La tarjeta lee los valores actuales de ese registro y sus partidas. Si hay varios contactos o empresas asociados, elige el que quieras usar para ese documento. El registro asociado seleccionado no se guarda como un cliente fijo para futuros registros.
Ten en cuenta estas diferencias:
- Save mapping actualiza las reglas compartidas de una asignación guardada. Generate PDF no guarda los cambios automáticamente.
- Para crear una versión independiente, cambia Mapping name y elige Save as new cuando hayas abierto una asignación existente.
- Los valores de Enter a value y un nombre de archivo escrito de forma explícita son partes fijas de una asignación guardada. Revísalos antes de reutilizarlos.
- Reload saved mapping vuelve a obtener la configuración guardada. Guarda primero los cambios que quieras conservar.
- Si otra persona cambia la misma asignación, vuelve a obtenerla y revisa las reglas actuales antes de guardar.
- Después de actualizar una plantilla, revisa los campos y guarda la asignación para la nueva versión publicada antes de generar.
Quienes tengan permisos de propietario o administrador pueden abrir Integraciones → HubSpot en ShipPDF para ver los detalles de las asignaciones o eliminarlas. Crea y edita las reglas de campos en la tarjeta de HubSpot. Eliminar una asignación no elimina su plantilla ni los PDF generados anteriormente.
Genera y descarga el PDF
Revisa los valores asignados y escribe un PDF filename (optional) si lo necesitas. Elige Generate PDF. Cada PDF nuevo usa un crédito de generación de ShipPDF. La tarjeta muestra el progreso y se actualiza cuando el documento está listo.
Cuando aparezca Your PDF is ready, elige Open PDF para verlo o descargarlo, o Copy PDF link para copiar su URL temporal. Si hace falta, usa Refresh PDF link para obtener un enlace nuevo del mismo documento, en lugar de generar otro PDF.
El PDF no se adjunta automáticamente al registro de HubSpot. Descarga el archivo para conservar una copia. Las URL de ShipPDF caducan, así que copiar el enlace no equivale a guardar el archivo de forma permanente.
Si no se pudo confirmar el resultado y aparece Retry generation, usa esa acción para repetir la misma petición. Si se detienen las actualizaciones, usa Check PDF status. Comprueba si el documento existente terminó antes de empezar otra generación.
Gestiona o desconecta la conexión
Abre Integraciones → HubSpot en el espacio de trabajo conectado de ShipPDF. Quienes tengan permisos de propietario o administrador pueden desconectar la cuenta de HubSpot ahí o revocar la clave de API de la tarjeta en Claves de API. Esto impide que la tarjeta use las plantillas y los créditos del espacio de trabajo. La desconexión no elimina los documentos ya generados.
Solución de problemas
| Problema | Qué revisar |
|---|---|
| No aparece la tarjeta de ShipPDF | Confirma la instalación, agrega la tarjeta a la vista del objeto correcto y guarda el diseño. |
| No hay un espacio de trabajo disponible | Inicia sesión con permisos de propietario o administrador del espacio de trabajo que quieras autorizar. |
| La cuenta ya está vinculada a otro espacio | Desconéctala del espacio de trabajo actual antes de elegir otro. |
| No se puede usar una plantilla | Publícala en el espacio de trabajo conectado y elige el proyecto correcto. |
| Falta una propiedad | Agrega el nombre interno de la propiedad existente en Custom properties o Custom line item properties. |
| No aparece un valor asociado | Elige el contacto o empresa correctos y comprueba el valor de su propiedad. |
| El PDF contiene datos de ejemplo | Asigna el campo de forma explícita o elimina el valor predeterminado que no quieres usar. |
| Los valores no coinciden con la plantilla | Revisa números, booleanos, formatos de fecha y arreglos JSON según el esquema publicado. |
| Se actualizó la plantilla | Revisa y guarda la asignación para la versión publicada actual. |
| El espacio de trabajo no tiene créditos | Revisa la facturación y el saldo de créditos del espacio conectado en ShipPDF. |
| Caducó el enlace del PDF | Usa Refresh PDF link para el documento terminado. |
Para el diseño y las tablas largas, consulta Páginas y contenido que supera una página. Para la presentación de números y fechas, consulta Vínculos y formato de campos de datos.