Ignorar e ir ao conteúdo principal

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.

Se você configurou os pagamentos do HubSpot ou o processamento de pagamentos do Stripe, poderá configurar um orçamento para ser pago por meio desta API. Saiba mais sobre orçamentos a pagar.

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.

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 e pagamentos.
  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.

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.

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

hs_title string (obrigatório)

O nome do orçamento.

hs_expiration_date string (obrigatório)

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

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

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

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.

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.

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.

ParâmetroTipoDescrição
hs_payment_enabledBooleanoQuando 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_typeEnumeraçãoDetermina qual processador de pagamentos usar. O valor pode ser HUBSPOT ou BYO_STRIPE.
hs_allowed_payment_methodsEnumeraçãoOs métodos de pagamento a serem usados (por exemplo, cartão de crédito).
hs_collect_billing_addressBooleanoQuando definido como true, permite que o comprador insira o seu endereço de envio ao finalizar a compra.
hs_collect_shipping_addressBooleanoQuando 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:

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.

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 objetoObrigatórioDescrição
Itens de linhaSimOs 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çamentoSimO 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ócioSimO 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.
ContatoNãoCompradores específicos que você está atendendo no orçamento.
EmpresaNãoUma empresa específica que você está atendendo no orçamento. Cada orçamento pode ser associado a uma empresa.
Descontos, taxas e impostosNãoQuaisquer 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

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.

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.

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}

DescriçãoParâmetro
fromObjectIdO ID do orçamento.
toObjectTypeO tipo de objeto ao qual você está fazendo a associação. Por exemplo, line_items, deals e quote_template.
toObjectIdO ID do objeto ao qual você está associando o orçamento.

Veja exemplos de solicitações PUT para cada tipo de objeto.

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.

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

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

Objeto properties

Detalhes do orçamento, que podem ser recuperados através da API de propriedades. As propriedades obrigatórias são hs_title e hs_expiration_date.

hs_title string (obrigatório)

O nome do orçamento.

hs_expiration_date string (obrigatório)

A data em que o orçamento expira.

hs_status string

O status do orçamento. Omitir esta propriedade na criação impedirá que os usuários possam editar o orçamento no HubSpot.

Matriz associations

Os registros associados do 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 de linha devem ser criados separadamente dos itens de linha no negócio associado.

Para definir cada associação, inclua um objeto separado na matriz de associações com os seguintes campos:

  • para: o ID do registro a associar.
  • associationCategory: o tipo de associação. Pode ser HUBSPOT_DEFINED ou USER_DEFINED.
  • associationTypeId: o ID do tipo de associação que está sendo feito:
    • 286: orçamento para modelo de orçamento
    • 64: orçamento para negócio
    • 67: orçamento para item de linha

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

Por exemplo, a solicitação a seguir publicaria o orçamento em um URL acessível ao público.

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:

DescriçãoParâmetro
propertiesUma 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.
propertiesWithHistoryUma 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.
associationsUma 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.

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.

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

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