Orçamentos

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 para adicionar detalhes, atualizar associações e muito mais.

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.

Observação: a API de orçamentos não é compatível com a criação de orçamentos com assinatura eletrônica ou o processamento de pagamento por meio do Stripe ou do HubSpot. Você também não pode configurar descontos, taxas ou impostos recorrentes no orçamento por meio da API. Para usar esses recursos, você pode criar o orçamento no HubSpot

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 as assinaturas eletrônicas
  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 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, um negócio e seus itens de linha.

Dependendo do seu fluxo de trabalho preferido, você pode criar um orçamento com associações por meio de uma solicitação POST.

No corpo do post, inclua as seguintes propriedades exigidas para configurar seus detalhes básicos.

hs_title  string (required)

The name of the quote.

hs_expiration_date  string (required)

The date that the quote expires.

The above are just the minimum required properties to get a quote started. To see all available quote properties, make a GET request to crm/v3/properties/quotes. Learn more about the properties API.

// example POST request body { "properties": { "hs_title": "CustomerName - annual SEO audit", "hs_expiration_date": "2023-12-10" } }

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}.

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 de 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

// example POST request body { "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 do orçamento. 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.

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. 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 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 ou criar itens de linha personalizados independentes.
Modelo de orçamentos 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 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 Não Compradores específicos que você está atendendo no orçamento.
Empresa Não Uma empresa específica que você está atendendo no orçamento. Cada orçamento pode ser associado a uma empresa.
Descontos, taxas e impostos 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 endpoint 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.

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 #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.

// Example quote template GET response { "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 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}

Use this table to describe parameters / fields
ParameterDescription
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.

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} #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'

As an example, if your quote has an ID of 123456, the requests to associate the quote might include the following:

  • Line items (IDs: 55555, 66666): 
    • /crm/v4/objects/quotes/123456/associations/default/line_items/55555
    • /crm/v4/objects/quotes/123456/associations/default/line_items/66666
  • Quote template (ID: 987654):  /crm/v4/objects/quotes/123456/associations/default/quote_template/987654
  • Deal (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.

// Example response { "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" }

Observação: ao associar um orçamento a um modelo de orçamento, lembre-se dos seguintes limites:

  • Os modelos de orçamento devem ser criados 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, 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 específico de orçamento para contato.

Em vez de usar os endpoints 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:

// Example request body [ { "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.

POST /crm/v3/objects/quote 

properties  object 

Quote details, which can be retrieved through the properties API. Required properties are: hs_title and hs_expiration_date.

⮑ hs_title  string (required)

The name of the quote.

⮑ hs_expiration_date  string (required)

The date that the quote expires.

⮑ hs_status  string

The quote status. Omitting this property on create will prevent users from being able to edit the quote in HubSpot.

associations  array

The quote's associated records. For a quote to be publishable, it must have an associated deal and quote template. Learn more about association type IDs.

// POST request to https://api.hubapi.com/crm/v3/objects/quote { "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 }] } ] }

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, 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.

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.
  • RASCUNHO: 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.
  • PENDING_APPROVAL: indica que o orçamento está aguardando aprovação para que possa ser publicado.
  • APPROVED: o orçamento foi aprovado 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 para publicação e deve ser editado antes que possa ser enviado para aprovação novamente.

Observação: se estiver habilitando as assinaturas eletrônicas no orçamento, não poderá publicar o orçamento se exceder o seu limite mensal de assinaturas eletrônicas.

Por exemplo, a solicitação a seguir publicaria o orçamento em um URL acessível ao público.
// PATCH request to https://api.hubapi.com/crm/v3/objects/quote/{QUOTE_ID} { "properties": { "hs_status": "APPROVAL_NOT_NEEDED" } }

Observação: por padrão, o HubSpot definirá a propriedade hs_template_type do orçamento como CUSTOMIZABLE_QUOTE_TEMPLATE depois de atualizar o estado do orçamento. 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: set to 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.

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

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..