> ## 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 | Orçamentos export const ScopesList = ({scopes = [], description = "Esta API requer um dos seguintes escopos:"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; Use a API de orçamentos para criar, gerenciar e recuperar orçamentos de vendas para compartilhar informações de preços com potenciais compradores. Uma vez configurado, um orçamento pode ser compartilhado com um comprador em um URL especificado ou por meio de um PDF. Os usuários também podem [gerenciar orçamentos no HubSpot](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes-legacy#manage-quotes) para adicionar detalhes, atualizar associações e muito mais. Se você configurou os [pagamentos do HubSpot](https://knowledge.hubspot.com/pt/payment-processing/set-up-payments) ou o [processamento de pagamentos do Stripe](https://knowledge.hubspot.com/pt/payment-processing/connect-your-stripe-account-as-a-payment-processor-in-hubspot), poderá configurar um orçamento para ser pago por meio desta API. Saiba mais sobre [orçamentos a pagar](https://br.developers.hubspot.com/docs/api-reference/crm-quotes-v3/guide#enable-payments). example-quote-api **Exemplo de caso de uso:** você precisa criar uma proposta de contrato para um cliente que está interessado em comprar um dos seus pacotes anuais de serviços de auditoria de SEO. Saiba como criar um orçamento por meio da API e configurar suas várias propriedades, associações, estados e muito mais. ## Visão geral O processo de criação de orçamentos pode ser dividido nas seguintes etapas: 1. **Criar um orçamento:** crie um orçamento com alguns detalhes, como nome e data de validade. Você também pode configurar o orçamento para [habilitar assinaturas eletrônicas](https://br.developers.hubspot.com/docs/api-reference/crm-quotes-v3/guide#enable-e-signatures) e [pagamentos](https://br.developers.hubspot.com/docs/api-reference/crm-quotes-v3/guide#enable-payments)[](https://knowledge.hubspot.com/pt/quotes/use-e-signatures-with-quotes). 2. **Configurar associações**: associe o orçamento a outros tipos de objetos do CRM, como itens de linha, um modelo de orçamento, um negócio e muito mais. Durante a próxima etapa, o orçamento herdará os valores de propriedade de alguns desses registros associados, bem como das configurações da conta. 3. **Definir o estado do orçamento:** defina o estado do orçamento para refletir sua disponibilidade para ser compartilhada com os compradores. Ao definir o estado do orçamento, como torná-lo um rascunho editável ou um orçamento totalmente publicado e acessível ao público, ele [herdará certas propriedades](#properties-set-by-quote-state) de seus registros de CRM e das configurações de conta associados. 4. **Compartilhar o orçamento:** assim que um orçamento for publicado, você pode compartilhá-lo com os seus compradores. ## Criar um orçamento Para criar um orçamento, configure primeiro seus detalhes básicos, fazendo uma solicitação `POST` para `/crm/v3/objects/quotes`. Posteriormente, você fará uma chamada separada para associar o orçamento a outros objetos, como o modelo de orçamento, itens de linha ou um negócio. Dependendo do seu fluxo de trabalho preferido, você pode [criar um orçamento com associações por meio de uma solicitação POST](#create-a-quote-with-associations-single-request). No corpo do post, inclua as seguintes propriedades exigidas para configurar seus detalhes básicos. ```json theme={null} { "properties": { "hs_title": "CustomerName - annual SEO audit", "hs_expiration_date": "2023-12-10" } } ``` | Parâmetro | Tipo | Descrição | | -------------------- | ------ | --------------------------------- | | `hs_title` | String | O nome do orçamento. | | `hs_expiration_date` | String | A data em que o orçamento expira. | As propriedades acima são apenas as mínimas necessárias para iniciar um orçamento, mas [outras propriedades](https://br.developers.hubspot.com/docs/api-reference/crm-quotes-v3/guide#adding-associations) são necessárias para publicar um orçamento. Para ver todas as propriedades de orçamento disponíveis, faça uma solicitação `GET` para `crm/v3/properties/quotes`. Saiba mais sobre a [API de propriedades](/docs/api-reference/crm-properties-v3/guide). A resposta incluirá um `id`, que você usará para continuar a configurar o orçamento. Você pode atualizar as propriedades do orçamento a qualquer momento, fazendo uma solicitação `PATCH` para `/crm/v3/objects/quotes/{quoteId}`. ### Proprietário do orçamento Definir a propriedade `hubspot_owner_id` manualmente não é possível porque é uma propriedade calculada, e quaisquer valores serão substituídos. Ao usar aspas, a propriedade funciona da seguinte maneira: * Se um [negócio está associado à cotação](#adding-associations), a propriedade `hubspot_owner_id` refletirá a propriedade `hs_associated_deal_owner_id` (`hs_associated_deal_owner_id` é uma propriedade calculada). * Se um negócio não estiver associado à cotação, a propriedade `hubspot_owner_id` refletirá a propriedade `hs_quote_owner_id`. ### Habilitar assinaturas eletrônicas Para habilitar as assinaturas eletrônicas no orçamento, inclua a propriedade booleana `hs_esign_enabled` no corpo da solicitação com um valor `true`. Observe que você não poderá adicionar contrassignatários por meio da API; portanto, eles precisarão ser adicionados ao HubSpot antes de publicar o orçamento. Você também não pode publicar um orçamento com a assinatura eletrônica habilitada se tiver [excedido o limite mensal de assinaturas eletrônicas](https://knowledge.hubspot.com/pt/quotes/use-e-signatures-with-quotes#monitor-e-signature-usage). ```json theme={null} { "properties": { "hs_title": "CustomerName - annual SEO audit", "hs_expiration_date": "2023-12-10", "hs_esign_enabled": "true" } } ``` Posteriormente, você precisará associar o orçamento aos signatários. Embora os contatos que assinem o orçamento existam como contatos no HubSpot, eles são armazenados como um tipo de associação separado dos contatos. Saiba mais sobre como [associar orçamentos a signatários do orçamento](#associating-quote-signers). ### Habilitar pagamentos Para ativar os pagamentos em um orçamento, inclua a propriedade booleana `hs_payment_enabled` no corpo da solicitação com um valor `true`. Dependendo do seu processador de pagamentos e dos métodos de pagamento aceitos, você também terá que definir `hs_payment_type` e `hs_allowed_payment_methods`. ### Observação: A conta HubSpot deve ter [Pagamentos HubSpot](https://knowledge.hubspot.com/pt/payment-processing/set-up-payments) ou [Processamento de pagamentos com Stripe](https://knowledge.hubspot.com/pt/payment-processing/connect-your-stripe-account-as-a-payment-processor-in-hubspot) antes de usar esse recurso. | Parâmetro | Tipo | Descrição | | ----------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hs_payment_enabled` | Booleano | Quando definido como `true`, permite que o orçamento receba pagamentos usando os pagamentos da HubSpot ou o processamento de pagamentos do Stripe. O padrão é `false`. | | `hs_payment_type` | Enumeração | Determina qual processador de pagamentos usar. O valor pode ser `HUBSPOT` ou `BYO_STRIPE`. | | `hs_allowed_payment_methods` | Enumeração | Os métodos de pagamento a serem usados (por exemplo, cartão de crédito). | | `hs_collect_billing_address` | Booleano | Quando definido como `true`, permite que o comprador insira o seu endereço de envio ao finalizar a compra. | | `hs_collect_shipping_address` | Booleano | Quando definido como `true`, permite que o comprador insira seu endereço de entrega ao finalizar a compra. | Por exemplo, para criar um orçamento e habilitar os pagamentos da HubSpot via cartão de crédito/débito ou ACH, sua solicitação seria: ```json theme={null} { "properties": { "hs_title": "CustomerName - annual SEO audit", "hs_expiration_date": "2023-12-10", "hs_payment_enabled": "true", "hs_payment_type": "HUBSPOT", "hs_allowed_payment_methods": "CREDIT_OR_DEBIT_CARD;ACH" } } ``` Para acompanhar o pagamento, a HubSpot atualizará automaticamente as propriedades `hs_payment_status` e `hs_payment_date`: * Quando você publica um orçamento com os pagamentos habilitados, a HubSpot define automaticamente a propriedade `hs_payment_status` como `PENDING`. * Se você usar ACH, quando o pagamento for processado, a HubSpot definirá automaticamente a propriedade `hs_payment_status` para `PROCESSING`. * Quando o pagamento for confirmado, a HubSpot definirá automaticamente a propriedade `hs_payment_status` como `PAID`. * Quando o orçamento for pago, a HubSpot definirá automaticamente `hs_payment_date` para a data e hora em que o pagamento foi confirmado. * Uma vez confirmado, o pagamento será associado automaticamente ao orçamento. Se quiser obter mais informações sobre o pagamento, consulte a [API de pagamentos](/docs/api-reference/crm-commerce-payments-v3/guide). ## Adição de associações Para criar um orçamento completo, você precisará associá-lo a outros registros do CRM, como itens de linha, usando a [API de associações](/docs/api-reference/crm-associations-v4/guide). A tabela abaixo mostra quais associações de registro do CRM são necessárias para um orçamento completo e quais são opcionais. Continue lendo para saber mais sobre como recuperar IDs e usá-los para criar as associações necessárias. \| Tipo de objeto | Obrigatório | Descrição | \| --- | --- | --- | --- | \| [Itens de linha](https://br.developers.hubspot.com/docs/api-reference/crm-line-items-v3/guide) | Sim | Os bens e/ou serviços que estão sendo vendidos por meio do orçamento. Você pode criar itens de linha de [produtos da sua biblioteca de produtos](https://br.developers.hubspot.com/docs/api-reference/crm-products-v3/guide) ou criar itens de linha personalizados independentes. | \| [Modelo de orçamento](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes-legacy) | Sim | O modelo que renderiza o orçamento, juntamente com o fornecimento de algumas definições de configuração padrão para o orçamento, como o idioma. Cada orçamento pode ser associado a um modelo. | \| [Negócio](/docs/api-reference/crm-deals-v3/guide) | Sim | O registro de negócio para acompanhar a receita e o ciclo de vida das vendas. Um orçamento herda valores do negócio associado, incluindo o proprietário e a moeda. Cada orçamento pode ser associado a um negócio. | \| [Contato](/docs/api-reference/crm-contacts-v3/guide) | Não | Compradores específicos que você está atendendo no orçamento. | \| [Empresa](/docs/api-reference/crm-companies-v3/guide) | Não | Uma empresa específica que você está atendendo no orçamento. Cada orçamento pode ser associado a uma empresa. | \| [Descontos](/docs/api-reference/crm-discounts-v3/guide), [taxas](/docs/api-reference/crm-fees-v3/guide) e [impostos](/docs/api-reference/crm-taxes-v3/guide) | Não | Quaisquer descontos, taxas e impostos a serem aplicados no checkout. Ao determinar o valor total do orçamento, o HubSpot primeiro aplica descontos, seguido de taxas e impostos. Você pode usar o campo `hs_sort_order` para reordenar objetos do mesmo tipo. Pode ser definido como valores fixos ou porcentagens, definindo `hs_type` como `FIXED` ou `PERCENT` | . | ### Recuperação de IDs para associações Para fazer cada associação, primeiro você precisará recuperar o ID de cada objeto que deseja associar. Para recuperar cada ID, faça uma solicitação `GET` para o pontos de extremidade do objeto relevante, que segue o mesmo padrão em cada objeto do CRM. Ao fazer cada solicitação, você também pode incluir um parâmetro de consulta de `properties` para retornar propriedades específicas quando necessário. Veja exemplos de solicitações `GET` para cada tipo de objeto. ```text hubl.txt theme={null} GET request for line items /crm/v3/objects/line_items?properties=name GET request for quote templates /crm/v3/objects/quote_template?properties=hs_name GET request for deals /crm/v3/objects/deals?properties=dealname GET request for contacts /crm/v3/objects/contacts?properties=email GET request for companies /crm/v3/objects/companies?properties=name GET request for discounts crm/v3/objects/discounts?properties=hs_type,hs_value GET request for fees crm/v3/objects/fees?properties=hs_type,hs_value GET request for taxes crm/v3/objects/taxes?properties=hs_type,hs_value ``` ```bash example.sh theme={null} #GET request for line items curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/line_items?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for quote templates curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/quote_templates?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for deals curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/deals?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for contacts curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/contacts?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for companies curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/companies?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for discounts curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/discounts?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for fees curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/fees?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for taxes curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/taxes?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' ``` Cada chamada bem-sucedida retornará uma resposta `200` com detalhes para cada tipo de objeto buscado. Você usará o valor no campo `id` para definir associações na próxima etapa. ```json theme={null} { "results": [ { "id": "235425923863", "properties": { "hs_createdate": "2023-06-12T16:27:32.794Z", "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z", "hs_name": "Default Basic", "hs_object_id": "235425923863" }, "createdAt": "2023-06-12T16:27:32.794Z", "updatedAt": "2023-06-12T16:27:32.794Z", "archived": false }, { "id": "235425923864", "properties": { "hs_createdate": "2023-06-12T16:27:32.794Z", "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z", "hs_name": "Default Modern", "hs_object_id": "235425923864" }, "createdAt": "2023-06-12T16:27:32.794Z", "updatedAt": "2023-06-12T16:27:32.794Z", "archived": false }, { "id": "235425923865", "properties": { "hs_createdate": "2023-06-12T16:27:32.794Z", "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z", "hs_name": "Default Original", "hs_object_id": "235425923865" }, "createdAt": "2023-06-12T16:27:32.794Z", "updatedAt": "2023-06-12T16:27:32.794Z", "archived": false } ] } ``` ### Criação de associações Com os IDs recuperados, agora você pode fazer chamadas para a [API de associações](/docs/api-reference/crm-associations-v4/guide) para criar associações. Para cada tipo de objeto que você deseja associar a um orçamento, será necessário realizar uma chamada separada, fazendo uma solicitação `PUT` com a estrutura de URL abaixo: `/crm/v4/objects/quotes/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}` | Parâmetro | Descrição | | -------------- | --------------------------------------------------------------------------------------------------------------- | | `fromObjectId` | O ID do orçamento. | | `toObjectType` | O tipo de objeto ao qual você está fazendo a associação. Por exemplo, `line_items`, `deals` e `quote_template`. | | `toObjectId` | O ID do objeto ao qual você está associando o orçamento. | Veja exemplos de solicitações `PUT` para cada tipo de objeto. ```text hubl.txt theme={null} PUT request to associate a line item /crm/v4/objects/quotes/{quoteId}/associations/default/line_items/{lineItemId} PUT request to associate a quote template /crm/v4/objects/quotes/{quoteId}/associations/default/quote_template/{quoteTemplateId} PUT request to associate a deal /crm/v4/objects/quotes/{quoteId}/associations/default/deals/{dealId} PUT request to associate contacts /crm/v4/objects/quotes/{quoteId}/associations/default/contacts/{contactId} PUT request to associate companies /crm/v4/objects/quotes/{quoteId}/associations/default/companies/{companyId} PUT request to associate discounts /crm/v4/objects/quotes/{quoteId}/associations/default/discounts/{discountId} PUT request to associate fees /crm/v4/objects/quotes/{quoteId}/associations/default/fees/{feeId} PUT request to associate taxes /crm/v4/objects/quotes/{quoteId}/associations/default/taxes/{taxId} ``` ```bash example.sh theme={null} #PUT request to associate line items curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/line_items/{lineItemId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate a quote template curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quote_ID}/associations/default/quote_template/{quoteTemplateId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate a deal curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/deals/{dealId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate contacts curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/contacts/{contactId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate a company curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/companies/{companyId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate discounts curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/discounts/{discountId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate fees curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/fees/{feeId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate taxes curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/line_items/{taxId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' ``` Por exemplo, se seu orçamento tiver o ID `123456`, as solicitações para associar o orçamento podem incluir o seguinte: * **Itens de linha (IDs: `55555`, `66666`):** * `/crm/v4/objects/quotes/123456/associations/default/line_items/55555` * `/crm/v4/objects/quotes/123456/associations/default/line_items/66666` * **Modelo de orçamento (ID:** `987654`**):** `/crm/v4/objects/quotes/123456/associations/default/quote_template/987654` * **Negócio (ID: `345345`):** `/crm/v4/objects/quotes/123456/associations/default/deals/345345` Cada associação bem-sucedida retornará uma resposta `200` com detalhes sobre a associação. As chamadas acima irão associar os objetos em ambas as direções, com cada direção tendo o seu próprio ID. Por exemplo, se você associar o orçamento a um modelo de orçamento, a resposta descreverá a associação de ambos. Na resposta de exemplo abaixo, `286` é o ID do tipo de associação de orçamento para modelo de orçamento e `285` é o ID do tipo de associação modelo de orçamento para orçamento. ```json theme={null} { "status": "COMPLETE", "results": [ { "from": { "id": "115045534742" }, "to": { "id": "102848290" }, "associationSpec": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 285 } }, { "from": { "id": "102848290" }, "to": { "id": "115045534742" }, "associationSpec": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 286 } } ], "startedAt": "2023-10-12T16:48:40.624Z", "completedAt": "2023-10-12T16:48:40.712Z" } ``` ### Observe que ao associar um orçamento a um modelo de orçamento: * Os modelos de orçamento devem ser [criados](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes-legacy) antes de serem associados a um orçamento. * Um orçamento pode ser associado somente a um modelo de orçamento. * Esta API não é compatível com orçamentos herdados ou de proposta. Somente o tipo de modelo `CUSTOMIZABLE_QUOTE_TEMPLATE` pode ser usado. ### Associação de signatários do orçamento Se estiver [habilitando o orçamento para assinaturas eletrônicas](#enable-e-signatures), você também precisará criar uma associação entre o orçamento e os contatos que estão assinando, usando um [rótulo de associação](/docs/api-reference/crm-associations-v4/guide#associate-records-with-a-label) específico de orçamento para contato. Em vez de usar os pontos de extremidade de associação padrão mostrados acima, você precisará fazer uma solicitação `PUT` para o seguinte URL: `/crm/v4/objects/quote/{quoteId}/associations/contact/{contactId}` No corpo da solicitação, você precisará especificar `associationCategory` e `associationTypeId`, conforme mostrado abaixo: ```json theme={null} [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 702 } ] ``` ## Criar um orçamento com associações (solicitação única) O corpo da solicitação a seguir criará um novo orçamento com associações para um modelo de orçamento, um negócio, dois itens de linha e um contato. Para que o corpo da solicitação abaixo crie um orçamento com êxito em sua conta, você precisará atualizar as IDs de objeto no `associations` para corresponder aos dados existentes em seu CRM. Reveja a seção [Recuperando IDs para associações](#retrieving-ids-for-associations) para obter orientações adicionais. `POST` `/crm/v3/objects/quote` ```json theme={null} { "properties": { "hs_title": "CustomerName - annual SEO audit", "hs_expiration_date": "2023-09-30" }, "associations": [ { "to": { "id": 115045534742 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 286 } ] }, { "to": { "id": 14795354663 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 64 } ] }, { "to": { "id": 75895447 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 67 } ] }, { "to": { "id": 256143985 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 67 } ] } ] } ``` | Parâmetro | Tipo | Descrição | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `properties` | Objeto | Valores de propriedade para definir os detalhes do orçamento. As propriedades necessárias são `hs_title` e `hs_expiration_date`: | | `associations` | Matriz | Os outros registros e objetos de CRM associados ao orçamento. Para que um orçamento possa ser publicado, ele deve ter um negócio associado e um modelo de orçamento. Os itens associados a um orçamento devem ser diferentes dos itens associados ao negócio do orçamento (ou seja, você deve criar cópias dos itens).

Para definir cada associação, inclua um objeto separado nessa matriz com os seguintes campos: | ### Observação: Esses itens devem ser diferentes dos itens em outros objetos, mesmo se estiverem associados (por exemplo, associando um orçamento a um negócio). Consulte a [documentação da API de itens de linha](https://br.developers.hubspot.com/docs/api-reference/crm-line-items-v3/guide) para obter mais informações. ## Atualizar estado do orçamento O estado de um orçamento descreve até que ponto ele está no processo de criação, desde a configuração inicial até a publicação e o acesso público. O estado do orçamento também pode refletir o [processo de aprovação do orçamento](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes), se as aprovações do orçamento estiverem ativadas para a conta. Ao definir o estado de um orçamento, o HubSpot [preencherá automaticamente certas propriedades](#properties-set-by-quote-state). Você pode atualizar o estado de um orçamento fazendo uma solicitação `PATCH` para `/crm/v3/objects/quote/{quoteId}`. O estado de um orçamento é baseado no campo `hs_status`. Alguns estados do orçamento permitem que os usuários editem, publiquem e usem o orçamento nos fluxos de trabalho de aprovação. Veja os estados de orçamento disponíveis. * **Sem estado:** se nenhum valor for fornecido para o campo `hs_status`, o orçamento estará no estado *Mínimo*. O orçamento aparecerá na página de índice da ferramenta de orçamentos, mas não pode ser editada diretamente. Os orçamentos nesse estado ainda podem ser usados na automação, como a ferramenta de sequências, e também estão disponíveis para análise dentro da ferramenta de relatório. * `DRAFT`: permite que o orçamento seja editado no HubSpot. Esse estado pode ser útil quando o orçamento não estiver totalmente configurado ou se você preferir que os representantes de vendas concluam o processo de configuração do orçamento no HubSpot. * `APPROVAL_NOT_NEEDED`: publica o orçamento em um URL de acesso público (`hs_quote_link`) sem precisar ser [aprovado](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes). * `PENDING_APPROVAL`: indica que o orçamento está [aguardando aprovação](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes) para que possa ser publicado. * `APPROVED`: o orçamento foi [aprovado](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes) e agora está publicado em um URL de acesso público (`hs_quote_link`). * `REJECTED`: indica que o orçamento foi configurado, mas não foi [aprovado](https://knowledge.hubspot.com/pt/quotes/set-up-legacy-quotes) para publicação e deve ser editado antes que possa ser enviado para aprovação novamente. ### Observação: Se você está [habilitando assinaturas eletrônicas](#enabling-e-signatures) no orçamento, você não poderá publicar o orçamento se tiver excedido o [limite mensal de assinatura eletrônica](https://knowledge.hubspot.com/pt/quotes/use-e-signatures-with-quotes#monitor-e-signature-usage). Por exemplo, a solicitação a seguir publicaria o orçamento em um URL acessível ao público. ```json theme={null} { "properties": { "hs_status": "APPROVAL_NOT_NEEDED" } } ``` ### Observação: Por padrão, a HubSpot definirá a propriedade `hs_template_type` do orçamento como `CUSTOMIZABLE_QUOTE_TEMPLATE` depois de [atualizar o estado do orçamento](https://br.developers.hubspot.com/docs/api-reference/crm-quotes-v3/guide#update-quote-state). Este tipo de modelo é suportado pela API v3, enquanto que os seguintes tipos são modelos antigos que não são mais suportados: * `QUOTE` * `PROPOSAL` ### Propriedades definidas pelo estado do orçamento A atualização do estado do orçamento atualizará as seguintes propriedades: * `hs_quote_amount`: calculado com base em quaisquer itens de linha, impostos, descontos e taxas associados. * `hs_domain`: definido a partir do modelo de orçamento associado. * `hs_slug`: gerado aleatoriamente se um não for fornecido explicitamente. * `hs_quote_total_preference`: definido com base nas configurações da sua conta. Se você não tiver configurado essa configuração, ela será padronizada para o valor do campo total\_first\_payment. * `hs_timezone`: o padrão é o fuso horário da sua conta da HubSpot. * `hs_locale`: definido a partir do modelo de orçamento associado. * `hs_quote_number`: define com base na data e hora atuais, a menos que uma seja fornecida. * `hs_language`: definido a partir do modelo de orçamento associado. * `hs_currency`: definido com base no negócio associado. Se você não associou um negócio ao orçamento, ele será padronizado para a moeda padrão da sua conta da HubSpot. Além disso, as propriedades abaixo serão calculadas quando o orçamento estiver definiu como um estado publicado: * `hs_pdf_download_link`: preenchido com uma URL de um PDF para o orçamento. * `hs_locked`: definido como `true`. Para modificar qualquer propriedade depois de publicar um orçamento, você deve primeiro atualizar o `hs_status` do orçamento de volta para `DRAFT`, `PENDING_APPROVAL` ou `REJECTED`. * `hs_quote_link`: o URL de acesso público do orçamento. Esta é uma propriedade somente leitura e não pode ser definida por meio da API após a publicação. * `hs_esign_num_signers_required`: exibe o número de assinaturas necessárias se as [assinaturas eletrônicas estiverem habilitadas](#enable-e-signatures). * `hs_payment_status`: o status do pagamento, caso tenha habilitado os pagamentos. Após a publicação com os pagamentos ativados, esta propriedade será definida como PENDENTE. Assim que o comprador fizer o pagamento por meio do orçamento, o status será atualizado automaticamente. Saiba mais sobre como [habilitar os pagamentos](https://br.developers.hubspot.com/docs/api-reference/crm-quotes-v3/guide#enable-payments). ## Recuperar orçamentos Você pode recuperar contatos individualmente ou em lotes. * Para recuperar um orçamento individual, faça uma solicitação `GET` para `/crm/v3/objects/quotes/{quoteID}`. * Para solicitar uma lista de todos os orçamentos, faça uma solicitação `GET` para `/crm/v3/objects/quotes`. Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação: | Parâmetro | Descrição | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `properties` | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se o quotecontact solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta. | | `propertiesWithHistory` | Uma lista separada por vírgulas das propriedades atuais e do histórico a serem retornadas em resposta. Se o orçamento solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta. | | `associations` | Uma lista separada por vírgulas de objetos para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a [API de associações.](/docs/api-reference/crm-associations-v4/guide) | Para recuperar um lote de orçamentos específicos por seus IDs, faça uma solicitação `POST` para `crm/v3/objects/quotes/batch/read` e inclua os IDs no corpo da solicitação. Você também pode incluir uma matriz de `properties` para especificar quais propriedades retornar. O ponto de extremidade em lote não pode recuperar associações. Saiba como fazer associações de leitura em lote com a [API de associações](/docs/api-reference/crm-associations-v4/guide). ```json theme={null} { "inputs": [ { "id": "342007287" }, { "id": "81204505203" } ], "properties": ["hs_content", "hs_sentiment", "hs_submission_timestamp"] } ``` ## Escopos Os seguintes escopos são necessários para que um aplicativo crie um orçamento publicável válido: * `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.read` * `crm.schemas.quote.read`, `crm.schemas.line_items.read`, `crm.schemas.contacts.read`, `crm.schemas.deals.read`, `crm.schemas.companies.read`