> ## Documentation Index
> Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API do CRM | Itens de linha

> **[Run in Postman](https://app.getpostman.com/run-collection/c6e6832eb67946d66554)**

> **Requisitos de escopo**

No HubSpot, os itens de linha são instâncias individuais de [produtos](https://br.developers.hubspot.com/docs/api-reference/crm-products-v3/guide.md). Quando um produto é anexado a um negócio, ele se torna um item de linha. Você pode criar itens de linha exclusivos para um orçamento individual, mas eles não serão adicionados à biblioteca de produtos. Os pontos de extremidade dos itens de linha permitem gerenciar esses dados e sincronizá-los entre o HubSpot e outros sistemas.

**Exemplo de caso de uso:** ao criar um conjunto de [orçamentos](https://br.developers.hubspot.com/docs/api-reference/crm-quotes-v3/guide.md) para os representantes de vendas enviarem aos compradores em potencial, você pode usar essa API para criar itens de linha independentes por orçamento, bem como itens de linha anexados a produtos existentes.

## Requisitos do escopo

Com base nos endpoints que você planeja usar, você precisará autorizar os seguintes escopos:

* `crm.objects.line_items.read`: fornece acesso para recuperar dados de itens de linha.
* `crm.objects.line_items.write`: fornece acesso para criar e atualizar itens de linha.
* `tax_rates.read`: fornece acesso para recuperar as taxas de impostos que você configurou em sua conta.

## Criar um item de linha

Para criar um item de linha, faça uma solicitação `POST` para `/crm/v3/objects/line_items`. No corpo do post, inclua os detalhes do item de linha, como nome, quantidade e preço. Você também pode incluir dados adicionais no corpo da solicitação:

* Para criar um item de linha com base em um produto existente (criado por meio da [API de produtos](https://br.developers.hubspot.com/docs/api-reference/crm-products-v3/guide.md) ou [no HubSpot](https://knowledge.hubspot.com/pt/products/create-and-manage-products)), inclua `hs_product_id` no corpo do post.
* Para incluir a [taxa de imposto](#retrieve-tax-rates) para o seu item de linha, inclua seu ID como `hs_tax_rate_group_id` dentro do `properties` campo do corpo da solicitação.
* Você também pode associar o item de linha a negócios, orçamentos, faturas, links de pagamento ou assinaturas, incluindo uma matriz de `associations` no corpo da solicitação post. Por exemplo, o corpo do post abaixo criaria um item de linha chamado "Novo item de linha independente", associado a um negócio (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
        }
      ]
    }
  ]
}
```

> [!WARNING]
>
> ### Observação:
>
> * Os itens de linha pertencem a um único objeto principal. Ao associar objetos, os itens de linha devem ser individuais para cada objeto. Por exemplo, se estiver criando um negócio e um orçamento, você deverá criar um conjunto de itens de linha para o negócio e outro conjunto para o orçamento. Isso ajudará a otimizar os dados do CRM em todos os objetos e evitará a perda inesperada de dados se for necessário modificar os itens de linha (por exemplo, excluir um orçamento excluirá os itens de linha dele e, se esses itens de linha estiverem associados a um negócio, os itens de linha do negócio também serão excluídos).
> * O `price` especificado no campo `properties` não pode ser negativo.
> * A propriedade *Prazo* dos itens de linha (`hs_recurring_billing_period`) aceita os [formatos de período ISO-8601](https://docs.oracle.com/javase/8/docs/api/java/time/Period.html) de PnYnMnD e PnW.

## Recuperar um item de linha

Você pode recuperar itens de linha individualmente ou em massa.

* Para recuperar um item de linha específico, faça uma solicitação `GET` para `/crm/v3/objects/line_items/{lineItemId}`, onde `lineItemId` é o ID do item de linha.
* Para recuperar todos os itens de linha, faça uma solicitação `GET` para `/crm/v3/objects/line_items`.

No URL de solicitação, você pode incluir os seguintes parâmetros:

| Parâmetro | Descrição |
| - | - |
| `properties` | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se alguma das propriedades especificadas não estiver presente nos objetos solicitados, ela será ignorada. |
| `propertiesWithHistory` | Uma lista separada por vírgulas das propriedades a serem retornadas, junto com seu histórico de valores anteriores. Se alguma das propriedades especificadas não estiver presente nos objetos solicitados, ela será ignorada. |

## Criar um item de linha

Para atualizar um item de linha, faça uma solicitação `PATCH` para `/crm/v3/objects/line_items/{lineItemId}`, onde `lineItemId` é o ID do item de linha.

No corpo do post, inclua os valores de propriedade que você deseja atualizar. Você não pode atualizar associações com esse método. Em vez disso, você precisará usar a [API de associações](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md).

Por exemplo, o corpo da sua solicitação pode ser parecido com o seguinte:

```js theme={null}
{
  "properties": {
    "price": 25,
    "quantity": 3,
    "name": "Updated line item"
  }
}
```

## Excluir um item de linha

Para excluir um item de linha, faça uma solicitação `DELETE` para `/crm/v3/objects/line_items/{lineItemId}`, onde `lineItemId` é o ID do item de linha.

## Propriedades de item de linha

Ao gerenciar os dados do item de linha, convém usar algumas das propriedades comuns da tabela abaixo. Para obter todas as propriedades de item de linha, faça uma solicitação `GET` para `/crm/v3/properties/line_item`. Saiba mais sobre como usar a [API de propriedades](https://br.developers.hubspot.com/docs/api-reference/crm-properties-v3/guide.md).

| Nome da propriedade | Rótulo na UI | Descrição |
| - | - | - |
| `name` | Nome | O nome do item de linha. |
| `description` | Descrição | A descrição completa do produto |
| `hs_sku` | SKU | Identificador exclusivo do produto |
| `hs_recurring_billing_start_date` | Data de início da cobrança | Data de início de cobrança recorrente para um item de linha |
| `hs_recurring_billing_end_date` | Data final de cobrança | Data final de cobrança recorrente para um item de linha |
| `recurringbillingfrequency` | Frequência de cobrança | Com que frequência um item de linha com cobrança recorrente é cobrado. Informa o cálculo de preços para negócios e orçamentos. Itens de linha com cobrança única não estão incluídos. |
| `quantity` | Quantidade | Quantas unidades de um produto estão incluídas nesse item de linha |
| `price` | Preço unitário | O custo do produto |
| `amount` | Preço líquido | O custo total do item de linha (ou seja, a quantidade vezes o preço unitário). |
| `hs_line_item_currency_code` | Moeda | Código da moeda do item de linha |

## Recuperar taxas de impostos

Você pode aplicar uma taxa de imposto a itens de linha individuais (por exemplo, um imposto sobre vendas MA de 6,26%). Uma vez que você [configurar sua biblioteca de taxas de impostos](https://knowledge.hubspot.com/pt/payments/set-up-automated-tax-and-tax-rates#add-a-tax-rate-to-the-tax-library) na sua conta HubSpot, você pode então fazer um `GET` pedido para `/tax-rates/v1/tax-rates` para buscar todas as taxas de impostos, ou `/tax-rates/v1/tax-rates/{taxRateId}` para buscar uma taxa de imposto por seu ID. Seu aplicativo precisará autorizar o `tax_rates.read` escopo para fazer esta solicitação.

A resposta resultante será semelhante à seguinte:

```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 taxa de imposto incluirá as seguintes propriedades:

| Nome da propriedade | Descrição |
| - | - |
| `name` | O descritor interno para a taxa de imposto. |
| `percentageRate` | O valor da taxa de imposto, expresso em porcentagem. |
| `label` | O descritor da taxa de imposto voltado para o comprador, mostrado na cotação, fatura ou outros objetos principais. |
| `active` | Um booleano que indica se a taxa de imposto pode ser aplicada a uma nova cotação ou fatura. Você pode definir isso para `false` para uma taxa de imposto do ano anterior que não é mais aplicável. |
| `id` | A identificação da taxa de imposto. |
| `createdAt` | Um registro de data e hora ISO 8601 indicando quando a taxa de imposto foi criada. |
| `updatedAt` | Um registro de data e hora ISO 8601 indicando quando a taxa de imposto foi atualizada pela última vez. |

Depois de ter a identificação da taxa de imposto que deseja aplicar, forneça-a `id` para o `hs_tax_rate_group_id` dentro do campo `properties` ao criar um item de linha. Saiba mais sobre como criar itens de linha na [seção acima](#create-a-line-item).