Elementos de línea

En HubSpot, los elementos de línea son instancias individuales de los productos. Cuando un producto está adjunto a un negocio, se convierte en elemento de línea. Puedes crear elementos de línea únicos para una cotización individual, pero no se agregarán a tu biblioteca de productos. Los puntos de terminación de elementos de línea permiten administrar estos datos y sincronizarlos entre HubSpot y otros sistemas.

Ejemplo de uso: al crear un conjunto de cotizaciones para que los representantes de ventas las envíen a compradores potenciales, puedes usar esta API para crear elementos de línea independientes por cotización, así como elementos de línea que se adjuntan a productos existentes.

Crear un elemento de línea

Para crear un elemento de línea, haz una solicitud POST en /crm/v3/objects/line_items. En el cuerpo de la publicación, incluye los detalles del elemento de línea, como el nombre, la cantidad y el precio.

Para crear un elemento de línea basado en un producto existente (creado a través de la API de productos o en HubSpot), incluye hs_product_id en el cuerpo de la publicación. 

También puedes asociar el elemento de pedido con negocios, cotizaciones, facturas, enlaces de pago o suscripciones, al incluir una matriz de asociaciones en el cuerpo de la publicación. Por ejemplo, el siguiente cuerpo de publicación crearía un elemento de pedido llamado "Nuevo elemento de pedido independiente" que está asociado con un negocio (ID: 12345).

// POST request to https://api.hubapi.com/crm/v3/objects/line_item { "properties": { "price": 10, "quantity": 1, "name": "New standalone line item" }, "associations": [ { "to": { "id": 12345 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 20 } ]

Nota:

  • Los elementos de pedido pertenecen a un único objeto matriz. Si se asocian objetos, los elementos de pedido deben ser individuales para cada objeto. Por ejemplo, si estás creando un negocio y una cotización, debes crear un conjunto de elementos de pedido para el negocio y otro conjunto para la cotización. Esto ayudará a agilizar los datos de CRM en todos los objetos y evitará la pérdida inesperada de datos cuando se necesite modificar los elementos de pedido (por ejemplo, eliminar una cotización eliminará los elementos de pedido de la cotización, y si esos elementos de pedido están asociados con un negocio, los elementos de pedido de os negocios también se eliminarán).
  • El precio especificado dentro del campo de propiedades no puede ser negativo.
  • La propiedad Correo electrónico de los elementos de pedido (hs_recurring_billing_period) acepta los formatos de período ISO-8601 de PnYnMnD y PnW.

Recuperar un elemento de línea

Puedes recuperar elementos de línea individualmente o en masa.

  • Para recuperar un elemento de línea específico, realiza una solicitud GET en /crm/v3/objects/line_items/{lineItemId}, donde lineItemId es el ID del elemento de línea.
  • Para recuperar todos los elementos de línea, haz una solicitud GET en /crm/v3/objects/line_items
En la URL de la solicitud, puedes incluir los siguientes parámetros:
Use this table to describe parameters / fields
ParameterDescription
propiedades

Una lista separada por comas de las propiedades que se devolverán en la respuesta. Si alguna de las propiedades especificadas no está presente en los objetos solicitados, se ignorará.

propertiesWithHistory

Una lista separada por comas de las propiedades que se devolverán junto con su historial de valores anteriores. Si alguna de las propiedades especificadas no está presente en los objetos solicitados, se ignorará.

Actualizar un elemento de línea

Para actualizar un elemento de línea, realiza una solicitud PATCH en /crm/v3/objects/line_items/{lineItemId}, donde lineItemId es el ID del elemento de línea.

En el cuerpo de la publicación, incluye los valores de propiedad que deseas actualizar. No puedes actualizar asociaciones a través de este método. En su lugar, deberás usar la API de asociaciones.

Por ejemplo, el cuerpo de tu solicitud puede tener un aspecto similar al siguiente:

// PATCH request to https://api.hubapi.com/crm/v3/objects/line_item/{lineItemId} { "properties": { "price": 25, "quantity": 3, "name": "Updated line item" }

Eliminar un elemento de pedido

Para eliminar un elemento de línea, realiza una solicitud DELETE en /crm/v3/objects/line_items/{lineItemId}, donde lineItemId es el ID del elemento de línea.

Propiedades del elemento de línea

Al administrar los datos de los elementos de pedido, es posible que desee utilizar algunas de las propiedades comunes de la siguiente tabla. Para obtener todas las propiedades de los elementos de pedido, haz una solicitud GET a /crm/v3/properties/line_item. Más información sobre el uso de la API de propiedades.

Nombre de la propiedad Etiqueta en la interfaz de usuario Descripción
name Nombre El nombre del elemento de pedido.
descripción Descripción Descripción completa del producto
hs_sku SKU Identificador único del producto
hs_billing_period_start_date Fecha de inicio de facturación Fecha de inicio de un período de facturación fijo.
hs_billing_period_end_date Fecha de finalización de facturación Fecha de finalización de un período de facturación fijo.
recurringbillingfrequency Frecuencia de facturación Con qué frecuencia se factura un elemento de pedido con facturación periódica. Informa el cálculo de precios para negocios y cotizaciones. Los elementos de pedido con facturación única no están incluidas.
quantity
Cantidad Cuántas unidades de un producto hay en este elemento de pedido
price
Precio unitario El costo del producto
amount Precio neto El costo total del elemento de pedido (es decir, la cantidad multiplicada por el precio unitario).
currency Moneda Código de moneda para el elemento de pedido.

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.