Requisitos de ámbito
Requisitos de ámbito

Resumen
El proceso de creación de cotizaciones se puede dividir en los siguientes pasos:- Crear una cotización: crea una cotización con algunos detalles, como el nombre y la fecha de vencimiento. También puedes configurar la cotización para habilitar las firmas electrónicas y los pagos.
- Configurar asociaciones: asocia la cotización con otros tipos de objetos del CRM, como elementos de pedido, plantillas de cotización, un negocio, entre otros. Durante el siguiente paso, la cotización heredará los valores de propiedad de algunos de estos registros asociados, así como la configuración de la cuenta.
- Establecer el estado de la cotización: establece el estado de la cotización para que refleje que está lista para ser compartida con los compradores. Al establecer el estado de la cotización, como convertirla en un borrador editable o en una cotización publicada y accesible de forma pública, heredará ciertas propiedades de los registros de CRM asociados y de la configuración de la cuenta.
- Compartir la cotización: una vez que se ha publicado una cotización, puedes compartirla con tus compradores.
Crear una cotización
Para crear una cotización, primero debes configurar sus detalles básicos realizando una solicitudPOST a /crm/v3/objects/quotes. Luego, deberás hacer una llamada separada para asociar la cotización con otros objetos, como la plantilla de cotización, los elementos de pedido o un negocio.
Dependiendo de tu flujo de trabajo preferido, puedes crear una cotización con asociaciones a través de una solicitud POST.
| Parámetro | Tipo | Descripción |
|---|---|---|
hs_title | Cadena | El nombre de la cotización. |
hs_expiration_date | Cadena | La fecha en la que vence la cotización. |
GET a crm/v3/properties/quotes. Más información sobre la API de propiedades.
La respuesta incluirá un id, que utilizarás para seguir configurando la cotización. Puedes actualizar las propiedades de la cotización en cualquier momento realizando una solicitud PATCH a /crm/v3/objects/quotes/{quoteId}.
Propietario de la cotización
Establecer la propiedadhubspot_owner_id manualmente no es posible debido a que es una propiedad calculada, y cualquier valor será anulado. Cuando se utilizan cotizaciones, la propiedad funciona del siguiente modo:
- Si hay un negocio asociado a la cotización, la propiedad
hubspot_owner_idreflejará la propiedadhs_associated_deal_owner_id(hs_associated_deal_owner_ides una propiedad calculada). - Si no hay una cotización asociada a un negocio, la propiedad
hubspot_owner_idmostrará la propiedadhs_quote_owner_id.
Habilitar firmas electrónicas
Para habilitar las firmas electrónicas en la cotización, incluye la propiedad booleanahs_esign_enabled en el cuerpo de la solicitud con un valor de true. Ten en cuenta que no podrás agregar firmantes adicionales a través de la API, por lo que deberán agregarse en HubSpot antes de publicar la cotización. Tampoco puedes publicar una cotización con firma electrónica si has excedido tu límite mensual de firmas electrónicas.
Habilitar los pagos
Para activar los pagos en una cotización, incluye la propiedad booleanahs_payment_enabled en el cuerpo de la solicitud con un valor de true. Dependiendo del procesador de pagos que utilices y de los métodos de pago aceptados, también tendrás que establecer hs_payment_type y hs_allowed_payment_methods.
| Parámetro | Tipo | Descripción |
|---|---|---|
hs_payment_enabled | Booleano | Cuando se establece como true, permite que la cotización pueda procesar el pago utilizando los pagos de HubSpot o el procesamiento de pagos con Stripe. Por opción predeterminada es false. |
hs_payment_type | Enumeración | Determina qué procesador de pagos se va a utilizar. El valor puede ser HUBSPOT o BYO_STRIPE. |
hs_allowed_payment_methods | Enumeración | Los métodos de pago que se utilizarán (por ejemplo, tarjeta de crédito). |
hs_collect_billing_address | Booleano | Cuando se establece como true, le permite al comprador introducir su dirección de facturación durante el proceso de pago. |
hs_collect_shipping_address | Booleano | Cuando se establece como true, le permite al comprador introducir su dirección de envío durante el proceso de pago. |
hs_payment_status y hs_payment_date:
- Cuando publiques una cotización con los pagos habilitados, HubSpot establecerá automáticamente la propiedad
hs_payment_statuscomoPENDING. - Si utilizas ACH, cuando se procese el pago, HubSpot establecerá automáticamente la propiedad
hs_payment_statusaPROCESSING. - Cuando se confirme el pago, HubSpot establecerá automáticamente la propiedad
hs_payment_statuscomoPAID. - Una vez que se pague la cotización, HubSpot establecerá automáticamente
hs_payment_dateen la fecha y hora en que se confirmó el pago. - Una vez confirmado el pago, este se asocia automáticamente a la cotización. Si deseas obtener más información sobre los pagos, consulta la API de pagos.
Agregar asociaciones
Para crear una cotización completa, deberás asociarla con otros registros de CRM, como elementos de pedido, utilizando la API de asociaciones. La siguiente tabla muestra qué asociaciones de registros de CRM se requieren para que una cotización esté completa y cuáles son opcionales. Sigue leyendo para obtener más información sobre cómo buscar los ID de registros y usarlos para crear las asociaciones necesarias.| Tipo de objeto | Requerido | Descripción |
|---|---|---|
| Elementos de pedido | Sí | Los bienes o servicios que se venden a través de la cotización. Puedes crear elementos de pedido a partir de los productos de tu biblioteca de productos o crear elementos de pedido personalizados. |
| Plantilla de cotización | Sí | La plantilla que representa la cotización, además de proporcionar algunos ajustes de configuración predeterminados para la cotización, como el idioma. Cada cotización se puede asociar con una plantilla. |
| Negocio | Sí | El registro del negocio para el seguimiento de los ingresos y el ciclo de vida de las ventas. Una cotización hereda los valores del negocio asociado, incluidos el usuario responsable y la divisa. Cada cotización se puede asociar a un negocio. |
| Contacto | No | Compradores específicos a los que te estás dirigiendo en la cotización. |
| Empresa | No | Una empresa específica a la que te estás dirigiendo en la cotización. Cada cotización se puede asociar a una empresa. |
| Descuentos, tarifas e impuestos | No | Todos los descuentos, tarifas e impuestos que se apliquen al momento de pagar. Al determinar la cantidad total de la cotización, HubSpot aplica primero los descuentos, seguidos de las tarifas y luego los impuestos. Puedes usar el campo hs_sort_order para reordenar los objetos del mismo tipo. Se pueden establecer en valores o porcentajes fijos en el campo hs_type en FIXED o en PERCENT. |
Buscar ID para asociaciones
Para realizar cada asociación, primero tendrás que buscar el ID de cada objeto que quieras asociar. Para obtenerr cada ID, debes realizar una solicitudGET al endpoiny del objeto correspondiente, el cual sigue el mismo patrón en cada objeto del CRM. Al realizar cada solicitud, también puedes incluir un parámetro de consulta de properties para obtener propiedades específicas cuando sea necesario. A continuación se muestran ejemplos de solicitudes GET para cada tipo de objeto.
200 con detalles para cada tipo de objeto obtenido. Usarás el valor en el campo id para establecer asociaciones en el siguiente paso.
Crear asociaciones
Una vez tengas los ID, ahora puedes realizar llamadas a la API de asociaciones para crear las asociaciones. Para cada tipo de objeto que quieras asociar con una cotización, deberás realizar una llamada por separado haciendo una solicitudPUT utilizando la siguiente estructura de URL:
/crm/v4/objects/quotes/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}
| Parámetro | Descripción |
|---|---|
fromObjectId | El ID de la cotización. |
toObjectType | El tipo de objeto con el que se está asociando. Por ejemplo, line_items, deals y quote_template. |
toObjectId | El ID del objeto con el que asocias la cotización. |
PUT para cada tipo de objeto.
123456, las solicitudes para asociar la cotización podrían incluir lo siguiente:
- Elementos de pedido (ID:
55555,66666):/crm/v4/objects/quotes/123456/associations/default/line_items/55555/crm/v4/objects/quotes/123456/associations/default/line_items/66666
- Plantilla de cotización (ID:
987654):/crm/v4/objects/quotes/123456/associations/default/quote_template/987654 - Negocio (ID:
345345):/crm/v4/objects/quotes/123456/associations/default/deals/345345
200 con detalles sobre la asociación. Las llamadas anteriores asociarán los objetos en ambas direcciones, con cada dirección teniendo su propio ID. Por ejemplo, si asocias la cotización con una plantilla de cotización, la respuesta describirá la asociación desde ambos lados. En la respuesta del ejemplo a continuación, 286 es el ID del tipo de asociación de cotización a la plantilla de cotización, y 285 es el ID del tipo de asociación de la plantilla de cotización a cotización.
Asociar firmantes de cotizaciones
Si habilitaste la cotización para firmas electrónicas, también deberás crear una asociación entre la cotización y los contactos que están firmando mediante el uso de una etiqueta de asociación específica de cotización a contacto. En lugar de utilizar los endpoints de asociación predeterminados que se muestran arriba, deberás realizar una solicitudPUT a la siguiente URL:
/crm/v4/objects/quote/{quoteId}/associations/contact/{contactId}
En el cuerpo de la solicitud, deberás especificar associationCategory y associationTypeId, como se muestra a continuación:
Crear una cotización con asociaciones (solicitud única)
El siguiente cuerpo de solicitud creará una nueva cotización con asociaciones a una plantilla de cotización, un negocio, dos elementos de pedido y un contacto.Para que el cuerpo de la solicitud que aparece a continuación cree correctamente una cotización en la cuenta, tendrás que actualizar los ID de objeto en el campo
associations para que coincidan con los datos existentes en el CRM. Revisa la sección buscar ID para asociaciones para obtener más información.POST /crm/v3/objects/quote
| Parámetro | Tipo | Descripción |
|---|---|---|
properties | Objeto | Valores de propiedad para definir los detalles de la cotización. Las propiedades requeridas son hs_title y hs_expiration_date:
|
associations | Matriz | Los demás registros y objetos del CRM asociados a la cotización. Para que una cotización se pueda publicar, debe tener un negocio asociado y una plantilla de cotización. Los elementos de pedido asociados a una cotización deben ser distintos de los elementos de pedido asociados a la cotización del negocio (es decir, debes crear copias de los elementos de pedido). Para establecer cada asociación, incluye un objeto independiente en esta matriz con los siguientes campos:
|
Actualizar el estado de la cotización
El estado de una cotización describe qué tan avanzado está en el proceso de creación, desde la configuración inicial hasta su publicación y el acceso público. El estado de la cotización también puede reflejar el proceso de aprobación de la cotización, si las aprobaciones de cotizaciones están habilitadas para la cuenta. Al establecer el estado de una cotización, HubSpot completará automáticamente ciertas propiedades. Puedes actualizar el estado de una cotización haciendo una solicitudPATCH a /crm/v3/objects/quote/{quoteId}.
El estado de una cotización se basa en el campo hs_status. Ciertos estados de cotización permiten a los usuarios editar, publicar y usar la cotización en los flujos de trabajo de aprobación de cotizaciones. A continuación se muestran los estados de cotización disponibles.
- Sin estado: si no se proporciona ningún valor para el campo
hs_status, la cotización estará en el estado Mínimo. La cotización aparecerá en la página de índice de la herramienta cotizaciones, pero no se podrá editar directamente. Las cotizaciones en este estado todavía se pueden usar en la automatización, como la herramienta de secuencias y también están disponibles para analizar dentro de la herramienta de informes. DRAFT: permite editar la cotización en HubSpot. Este estado puede ser útil cuando la cotización no está completamente configurada o si prefieres permitir que los representantes de ventas completen el proceso de configuración de la cotización en HubSpot.APPROVAL_NOT_NEEDED: publica la cotización en una URL de acceso público (hs_quote_link) sin necesidad de aprobación.PENDING_APPROVAL: indica que la cotización está a la espera de ser aprobada antes de que pueda ser publicada.APPROVED: la cotización ha sido aprobada y ahora está publicada en una URL de acceso público (hs_quote_link).REJECTED: indica que la cotización ha sido configurada pero no ha sido aprobada para su publicación y debe editarse antes de que pueda enviarse de nuevo para su aprobación.
Propiedades establecidas por el estado de la cotización
Actualizar el estado de la cotización actualizará las siguientes propiedades:hs_quote_amount: se calcula en función de cualquier elemento de pedido asociado, impuesto, descuento y tarifa.hs_domain: se establece a partir de la plantilla de cotización asociada.hs_slug: se genera de forma aleatoria si no se proporciona un valor.hs_quote_total_preference: se establece en función de la configuración de tu cuenta. Si no has configurado este ajuste, por opción predeterminada será el valor del campo total_first_payment.hs_timezone: es la zona horaria predeterminada de tu cuenta de HubSpot.hs_locale: se establece a partir de la plantilla de cotización asociada.hs_quote_number: se establece en función de la fecha y hora actuales, a menos que se proporcione una.hs_language: se establece a partir de la plantilla de cotización asociada.hs_currency: se establece en función del negocio asociado. Si no has asociado un negocio con la cotización, esta cambiará por opción predeterminada a la divisa predeterminada de tu cuenta de HubSpot.
hs_pdf_download_link: se rellena con una URL de un PDF para la cotización.hs_locked: se establece entrue. Para modificar cualquier propiedad después de haber publicado una cotización, primero debes actualizar elhs_statusde la cotización aDRAFT,PENDING_APPROVALoREJECTED.hs_quote_link: la URL de acceso público de la cotización. Esta es una propiedad de solo lectura y no se puede configurar a través de la API después de la publicación.hs_esign_num_signers_required: si has habilitado las firmas electrónicas, muestra el número de firmas necesarias.hs_payment_status: el estado de cobro del pago, si habilitaste los pagos. Al publicar con los pagos habilitados, esta propiedad se establecerá en PENDING. Una vez que el comprador envíe el pago a través de la cotización, el estado se actualizará automáticamente. Más información sobre cómo habilitar los pagos.
Buscar cotizaciones
Puedes buscar cotizaciones individualmente o en lotes.- Para buscar una cotización individual, haz una solicitud
GETa/crm/v3/objects/quotes/{quoteID}. - Para solicitar una lista de todas las cotizaciones, envía una solicitud
GETa/crm/v3/objects/quotes.
| Parámetro | Descripción |
|---|---|
properties | Una lista separada con comas de las propiedades que se devolverán en la respuesta. Si el contacto de la cotización solicitada no tiene un valor para una propiedad, no aparecerá en la respuesta. |
propertiesWithHistory | Una lista separada con comas de las propiedades actuales y anteriores que se devolverán en la respuesta. Si la cotización solicitada no tiene un valor para una propiedad, no aparecerá en la respuesta. |
associations | Una lista separada con comas de los objetos para los que se deben obtener los ID asociados. No se devolverán en la respuesta las asociaciones especificadas que no existan. Encuentra más información sobre la API de asociaciones. |
POST a crm/v3/objects/quotes/batch/read e incluye los ID en el cuerpo de la solicitud. También puedes incluir una matriz de properties para especificar qué propiedades devolver. El endpoint por lotes no puede obtener asociaciones. Encuentra más información sobre cómo leer asociaciones en bloques con la API de asociaciones.
Permisos
Se requieren los siguientes permisos para que una aplicación cree una cotización que sea válida para publicar:crm.objects.quotes.write,crm.objects.quotes.read,crm.objects.line_items.write,crm.objects.line_items.read,crm.objects.owners.read,crm.objects.contacts.write,crm.objects.contacts.read,crm.objects.deals.write,crm.objects.deals.read,crm.objects.companies.write,crm.objects.companies.readcrm.schemas.quote.read,crm.schemas.line_items.read,crm.schemas.contacts.read,crm.schemas.deals.read,crm.schemas.companies.read