> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API del CRM | Elementos de pedido
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Esta API requiere uno de los siguientes ámbitos:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
En HubSpot, los elementos de pedido son instancias individuales de los [productos](/docs/api-reference/crm-products-v3/guide). Cuando un producto está adjunto a un negocio, se convierte en un elemento de pedido. Puedes crear elementos de pedido únicos para una cotización individual, pero no se agregarán a tu biblioteca de productos. Los endpoints de elementos de pedido permiten gestionar estos datos y sincronizarlos entre HubSpot y otros sistemas.
**Ejemplo de uso:** al crear un conjunto de [cotizaciones](/docs/api-reference/crm-quotes-v3/guide) para que los representantes de ventas las envíen a compradores potenciales, puedes usar esta API para crear elementos de pedido independientes por cotización, así como elementos de pedido que se adjuntan a productos existentes.
## Permisos necesarios
Dependiendo de los endpoints que pienses utilizar, tendrás que autorizar los siguientes permisos:
* `crm.objects.line_items.read`: proporciona acceso para recuperar datos de elementos de pedido.
* `crm.objects.line_items.write`: proporciona acceso para crear y actualizar elementos de pedido.
* `tax_rates.read`: proporciona acceso para recuperar los datos de las tasas de impuestos que hayas configurado en tu cuenta.
## Crear un elemento de pedido
Para crear un elemento de pedido, haz una solicitud `POST` a `/crm/v3/objects/line_items`. En el cuerpo de la solicitud, incluye los detalles del elemento de pedido, como su nombre, la cantidad y el precio. También puedes incluir datos adicionales en el cuerpo de la solicitud:
* Para crear un elemento de pedido basado en un producto existente (creado a través de la [API de productos](/docs/api-reference/crm-products-v3/guide) o [n HubSpot](https://knowledge.hubspot.com/es/products/create-and-manage-products)), incluye `hs_product_id` en el cuerpo de la solicitud.
* Para incluir la [tasa de impuestos](#retrieve-tax-rates) de tu elemento de pedido, incluye su ID como `hs_tax_rate_group_id` en el campo `properties` del cuerpo de la solicitud.
* También puedes asociar el elemento de pedido con negocios, cotizaciones, facturas, enlaces de pago o suscripciones, incluyendo una matriz de `associations` en el cuerpo de la solicitud. Por ejemplo, el cuerpo de la siguiente solicitud crearía un elemento de pedido llamado "New standalone line item" (Nuevo elemento de pedido independiente) que está asociado con un negocio (ID: `12345`).
```js theme={null}
{
"properties": {
"price": 10,
"quantity": 1,
"name": "New standalone line item",
"hs_tax_rate_group_id": "2148420997"
},
"associations": [
{
"to": {
"id": 12345
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 20
}
]
}
]
}
```
### Nota:
* Los elementos de pedido pertenecen a un único objeto principal. 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 del 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 los negocios también se eliminarán).
* El valor `price` especificado dentro del campo `properties` no puede ser negativo.
* La propiedad *Plazo* de los elementos de pedido (`hs_recurring_billing_period`) acepta los [formatos de período ISO-8601](https://docs.oracle.com/javase/8/docs/api/java/time/Period.html) de PnYnMnD y PnW.
## Obtener un elemento de pedido
Puedes obtener elementos de pedido de forma individual o en bloque.
* Para obtener un elemento de pedido específico, haz una solicitud `GET` a `/crm/v3/objects/line_items/{lineItemId}`, donde `lineItemId` es el ID del elemento de pedido.
* Para obtener todos los elementos de pedido, haz una solicitud `GET` a `/crm/v3/objects/line_items`.
En la URL de la solicitud, puedes incluir los siguientes parámetros:
| Parámetro | Descripción |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | Una lista separada con 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 pedido
Para actualizar un elemento de pedido, haz una solicitud `PATCH` a `/crm/v3/objects/line_items/{lineItemId}`, donde `lineItemId` es el ID del elemento de pedido.
En el cuerpo de la solicitud, incluye los valores de propiedad que quieres actualizar. No puedes actualizar asociaciones con este método. En su lugar, deberás usar la [API de asociaciones](/docs/api-reference/crm-associations-v4/guide).
Por ejemplo, el cuerpo de la solicitud puede tener un aspecto similar al siguiente:
```js theme={null}
{
"properties": {
"price": 25,
"quantity": 3,
"name": "Updated line item"
}
}
```
## Eliminar un elemento de pedido
Para eliminar un elemento de pedido, haz una solicitud `DELETE` a `/crm/v3/objects/line_items/{lineItemId}`, donde `lineItemId` es el ID del elemento de pedido.
## Propiedades de los elementos de pedido
Al gestionar los datos de los elementos de pedido, puede que quieras usar algunas de las propiedades comunes de esta tabla. Para obtener todas las propiedades de los elementos de pedido, haz una solicitud `GET` a `/crm/v3/properties/line_item`. Consulta más información sobre el uso de la [API de propiedades](/docs/api-reference/crm-properties-v3/guide).
| Nombre de la propiedad | Etiqueta en la interfaz de usuario | Descripción |
| --------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Nombre | El nombre del elemento de pedido. |
| `description` | Descripción | Descripción completa del producto |
| `hs_sku` | SKU | Identificador único del producto |
| `hs_recurring_billing_start_date` | Fecha de inicio de la facturación | Facturación recurrente de un elemento de pedido |
| `hs_recurring_billing_end_date` | Fecha de finalización de la facturación | Facturación recurrente de un elemento de pedido |
| `recurringbillingfrequency` | Frecuencia de facturación | Con qué frecuencia se factura un elemento de pedido con facturación periódica. Indica el cálculo de precios para negocios y cotizaciones. Los elementos de pedido con facturación única no están incluidos. |
| `quantity` | Cantidad | Cuántas unidades de un producto hay en este elemento de pedido |
| `price` | Precio unitario | El coste del producto |
| `amount` | Precio neto | El coste total del elemento de pedido (es decir, la cantidad multiplicada por el precio unitario). |
| `hs_line_item_currency_code` | Divisa | Código de la divisa del elemento de pedido |
## Recuperar tasas de impuestos
Puedes aplicar una tasa de impuestos a elementos de pedido individuales (por ejemplo, un impuesto sobre las ventas de MA del 6,26%). Una vez que hayas [configurado tu biblioteca de tasas de impuestos](https://knowledge.hubspot.com/es/payments/set-up-automated-tax-and-tax-rates#add-a-tax-rate-to-the-tax-library) en tu cuenta de HubSpot, puedes hacer una solicitud `GET` a `/tax-rates/v1/tax-rates` para obtener todos las tasas de impuestos, o a `/tax-rates/v1/tax-rates/{taxRateId}` para obtener una tasa de impuestos por su ID. Tu aplicación tendrá que autorizar el permiso `tax_rates.read` para realizar esta solicitud.
La respuesta tendrá el siguiente formato:
```json theme={null}
{
"name": "MA Sales tax 2025",
"percentageRate": 6.25
"label": "Sales Tax",
"active": true,
"id": "2148420997",
"createdAt": "2024-12-12T23:20:39.923Z",
"updatedAt": "2024-12-12T23:20:39.923Z"
}
```
Cada objeto de tasas de impuestos incluirá las siguientes propiedades:
| Tipo de propiedad | Descripción |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | El descriptor interno de la tasa de impuestos. |
| `percentageRate` | El valor de la tasa de impuestos, expresado en porcentaje. |
| `label` | El descriptor de la tasa de impuestos orientado al comprador, que se muestra en la cotización, factura u otros objetos padre. |
| `active` | Un booleano que indica si la tasa de impuestos puede aplicarse a una nueva cotización o factura. Puedes ajustarlo a `false` para una tasa de impuestos de un año anterior que ya no es aplicable. |
| `id` | El ID de la tasa de impuestos. |
| `createdAt` | Una marca de tiempo ISO 8601 que indica cuándo se creó la tasa de impuestos. |
| `updatedAt` | Una marca de tiempo ISO 8601 que indica cuándo se actualizó por última vez la tasa de impuestos. |
Una vez que tengas el ID de la tasa de impuestos que quieres aplicar, proporciona ese `id` para el `hs_tax_rate_group_id` dentro del campo `properties` al crear un elemento de pedido. Más información sobre la creación de elementos de pedido en la [sección anterior](#create-a-line-item).