Orçamentos

No HubSpot, os orçamentos são usados para compartilhar informações de preços com possíveis compradores. Os endpoints de orçamentos permitem criar, recuperar e sincronizar orçamentos entre a HubSpot e outros sistemas.

No momento, a seguinte funcionalidade não é suportada ao usar a API de orçamentos do v3:

• Criação de orçamentos de propostas ou antigos por meio da API do v3. Somente o tipo de modelo CUSTOMIZABLE_QUOTE_TEMPLATE pode ser usado ao criar orçamentos com a API do v3. Saiba mais sobre como associar orçamentos a modelos de orçamento.
• Criação ou modificação de modelos de orçamento. Os modelos de orçamento devem ser criados ou personalizados em sua conta da HubSpot antes que possam ser referenciados usando a API de orçamentos v3.
• Uso de pagamentos Esign, Stripe ou HubSpot
• Uso de descontos, taxas ou impostos recorrentes no nível de orçamento

Observe as seguintes limitações ao criar um orçamento:

• Os modelos de orçamentos devem ser criados em sua conta da HubSpot antes que possam ser associados a um orçamento usando a API.
• Os orçamentos com status Publicável ou Publicado devem ter um negócio associado.

Para criar um orçamento, faça uma solicitação POST para /crm/v3/objects/quote.

No corpo do post, inclua as seguintes propriedades exigidas:

Junto com as propriedades, você também pode especificar as associações na solicitação de criação. No entanto, você também pode usar a API de associações para associar o orçamento após a criação.

Associações

Para associar o orçamento a outros registros do CRM no momento da criação, inclua uma matriz de associations no corpo do post da solicitação de criação. A matriz conterá um objeto para cada associação. 

Para que um orçamento seja totalmente acessível, editável e publicável no HubSpot, ele deve ter as seguintes associações:

• Modelo de orçamento: o modelo de CMS usado para renderizar um orçamento, juntamente com as configurações padrão para o orçamento, como o idioma. Para obter o ID do modelo de orçamento, faça uma solicitação GET para /crm/v3/objects/quote_template?properties=hs_name,hs_active, a fim de obter uma lista de modelos de orçamentos ativos. Saiba mais sobre como criar modelos de orçamento personalizados. Você só pode associar um orçamento a um modelo de orçamento.
• Negócio: o registro de negócio no HubSpot para rastrear a receita e o ciclo de vida. Um orçamento herda certos valores do negócio associado, incluindo o proprietário e a moeda. Você só pode associar um orçamento a um negócio.
• Itens de linha: produtos ou serviços individuais vendidos como parte do orçamento. Use a API de itens de linha para criar itens de linha independentes ou itens de linha com base em produtos existentes (criados por meio da API de produtos ou no HubSpot). Você pode obter o ID de um item de linha por meio da API de itens de linha, e o ID também será retornado quando você criar um item de linha.

Associações opcionais

Além disso, você pode associar um orçamento com o seguinte:

• Contatos: compradores específicos que você está atendendo no orçamento.
• Empresas: uma empresa específica que você está abordando no orçamento. Você só pode associar um orçamento a uma empresa.
• Descontos, taxas e impostos: quaisquer descontos, taxas e impostos aplicáveis a serem cobrados no orçamento na finalização da compra. Quando a HubSpot determinar o valor total do orçamento, primeiro serão aplicados os descontos e depois as taxas e os impostos, respectivamente. Você pode usar o campo hs_sort_order para reordenar objetos do mesmo tipo. Descontos, taxas e impostos podem ser especificados como valores fixos ou porcentagens, definindo o campo hs_type como FIXED ou PERCENT.

Por exemplo, o corpo do post a seguir criaria um orçamento com o nome "Novo orçamento" e o associaria a um modelo de orçamento (ID: 12345) e a um negócio (ID: 67890).

Quando terminar de configurar seu orçamento, você pode atualizar seu estado fazendo uma solicitação PATCH para/crm/v3/objects/quote/{QUOTE_ID}.

O estado de um orçamento é derivado do campo hs_status. Certos estados de orçamento permitem que você edite, publique, automatize ou relate o orçamento usando a ferramenta de orçamentos na sua conta da HubSpot.

• Mínimo: 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 em estado Mínimo 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.
• Editável: quando você define o campo hs_status como DRAFT, os orçamentos estarão em um estado Editável, que permite editar o orçamento diretamente na ferramenta de orçamentos.
• Publicável: um orçamento mudará para o estado Publicável assim que o campo hs_status estiver definido como PENDING_APPROVAL ou REJECTED.
• Publicado: um orçamento será publicado em um URL acessível publicamente assim que o campo hs_status estiver definido como APPROVAL_NOT_NEEDED ou APPROVED. Observe que APPROVED é apenas para uso em fluxos de trabalho de aprovação de orçamento.

Por exemplo, a solicitação a seguir atualizaria um orçamento para um estado Publicado:

Com base no novo estado do orçamento, algumas propriedades derivadas serão atualizadas automaticamente no objeto do orçamento.

Se você atualizar um orçamento para um estado Editável, Publicável ou Publicado, as seguintes propriedades serão derivadas da seguinte maneira:

• 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 mudar para 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.

Assim que um orçamento for publicado, você poderá visualizar a URL do orçamento acessível publicamente concatenando os campos hs_domain e hs_slug.

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