見積もり

見積もりAPIを使用して、潜在顧客と価格情報を共有するための見積書を作成、管理、および取得します。設定が完了すると、指定されたURLまたはPDFのいずれかで、購入者と見積もりを共有できます。ユーザーはHubSpotで見積もりを管理して、詳細の追加や関連付けの更新などを行うこともできます。

example-quote-api

使用例:ある顧客が貴社の年間SEO監査サービスパッケージの1つを購入することに関心があり、その顧客のために契約提案書を作成する必要があるとします。

以下では、APIを使用して見積もりを作成し、さまざまなプロパティー、関連付け、ステータスなどを構成する方法について説明します。

注:見積もりAPIは、電子署名や、StripeまたはHubSpotを介した支払い処理が含まれる見積もりの作成はサポートしていません。APIを介して、定期的な見積もりごとの割引、手数料、税金を設定することもできません。これらの機能を使用するには、代わりにHubSpotで見積もりを作成します。

概要

見積もり作成プロセスのステップは、次のように分割できます。

  1. 見積もりの作成:名前や有効期限など、いくつかの詳細を含む見積もりを作成します。電子署名を有効にするために見積もりの設定を変更することもできます。
  2. 関連付けの設定:見積もりと他のタイプのCRMオブジェクトに関連付けます。例えば、商品項目、見積もりテンプレート、取引などを関連付けます。次のステップで、見積もりはこれらの関連付けられたレコードの一部とアカウントの設定から、プロパティー値を継承します。
  3. 見積もりステータスの設定:見積もりのステータスを設定し、購入者と共有できる状態かどうかを示します。見積もりのステータスを、下書き、または一般公開済み、などに設定すると、関連するCRMレコードとアカウント設定から特定のプロパティーが継承されます。
  4. 見積もりの共有:見積もりが公開されると、購入者と共有できるようになります。

見積もりの作成

見積もりを作成するには、まず/crm/v3/objects/quotesPOSTリクエストを送信して、基本的な詳細を設定します。後で、見積もりテンプレート、取引、およびその商品項目などの他のオブジェクトを見積もりに関連付けるために、別の呼び出しを行います。

ご希望のワークフローに応じて、1つのPOSTリクエストで関連付けのある見積もりを作成できます。

POSTリクエスト本文には、次の必須プロパティーを含めて、基本的な詳細を設定します。

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

応答には、見積もりの設定を続行するために使用するidが含まれます。/crm/v3/objects/quotes/{quoteId}PATCHリクエストを送信することで、引用プロパティーをいつでも更新できます。

電子署名を有効にする

見積もりで電子署名を有効にするには、trueの値を持つhs_esign_enabledブール値プロパティーをリクエスト本文に含めます。APIを使用して副署名者を追加することはできないため、副署名者は見積もりを公開する前にHubSpotに追加する必要があることに注意してください。また、毎月の電子署名数の制限を超えた場合は、電子署名を有効にして見積もりを公開することはできません。 

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

後で、見積もりを見積もり署名者に関連付ける必要があります。見積もりに署名したコンタクトはHubSpotにコンタクトとして存在しますが、コンタクトとは別の関連タイプとして保存されます。見積もりを見積もり署名者に関連付ける方法について詳細をご確認ください。

関連付けを追加する

完全な見積もりを作成するには、関連付けAPIを使用して、商品項目などの他のCRMレコードと関連付ける必要があります。次の表は、完全な見積もりに必要なCRMレコードの関連付けと、オプションの関連付けを示しています。IDの取得と、IDを使用して必要な関連付けを作成する方法の詳細については、続きをお読みください。

オブジェクトタイプ 必須 説明
商品項目 はい 見積もりをとおして販売されている商品および/またはサービス。製品ライブラリーの製品から商品項目を作成したり、カスタムスタンドアロン商品項目を作成したりすることができます。
見積もりテンプレート はい 見積もりを表示するテンプレート。見積もりの既定設定(言語など)が含まれます。各見積もりは1つのテンプレートに関連付けることができます。
取引 はい 収益と営業ライフサイクルを追跡するために使用される取引レコード。見積もりは、関連付けられた取引からの値(担当者、通貨など)を継承します。各見積もりは、1つの取引に関連付けることができます。
お問い合わせ先 いいえ 見積もりの対象とする特定の顧客。
会社 いいえ 見積もりの対象とする特定の会社。各見積もりは1つの会社に関連付けることができます。
割引手数料税金 いいえ 決済時に適用されるあらゆる割引、手数料、税金。合計見積もり金額を決定する際、HubSpotはまず割引を適用し、次に手数料、その次に税金を適用します。同じタイプのオブジェクトを並べ替えるには、hs_sort_orderフィールドを使用します。固定値またはパーセンテージで指定できます。そのためには、hs_typeの値をFIXEDまたはPERCENTに設定します。

関連付けのIDの取得

各関連付けを作成するには、まず関連付ける各オブジェクトのIDを取得する必要があります。各IDを取得するには、関連するオブジェクトエンドポイントにGETリクエストを送信します。各CRMオブジェクトで同様の処理を行います。各リクエストを送信するときは、必要に応じて特定のプロパティーを返すようにするために、プロパティー クエリー パラメーターを含めることもできます。以下は、各タイプのオブジェクトに対するGETリクエストの例です。

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'

成功した呼び出しごとに、取得された各オブジェクトタイプの詳細を含む200の応答が返されます。次のステップでは、idフィールドの値を使用して関連付けを設定します。

// 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 } ] }

関連付けの更新

IDが取得されると、関連付けAPIを呼び出して関連付けを作成できるようになります。

見積もりに関連付けるオブジェクトのタイプごとに、以下のURL構造を使用してPUTリクエストを送信することで、個別の呼び出しを行う必要があります。

 /crm/v4/objects/quotes/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}

Use this table to describe parameters / fields
ParameterDescription
fromObjectId

見積もりのID

toObjectType

関連付けているオブジェクトのタイプ。例えば、line_itemsdealsquote_templateなどです。 

toObjectId

見積もりを関連付けるオブジェクトのID。 

以下は、各タイプのオブジェクトに対するPUTリクエストの例です。

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

成功した関連付けごとに、その関連付けの詳細を含む200の応答が返されます。上記の呼び出しは、オブジェクトを両方向に関連付け、各方向に独自のIDがあります。例えば、見積もりを見積もりテンプレートに関連付けると、レスポンスには両方からの関連付けが記述されます。以下のレスポンスの例では、286は「見積もり-見積もりテンプレート」関連付けタイプIDで、285は「見積もりテンプレート-見積もり」関連付けタイプIDである。

// 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" }

注:見積もりを見積もりテンプレートに関連付ける場合は、次の制限に注意してください。

  • 見積もりテンプレートに見積もりを関連付ける前に、見積もりテンプレートを作成しておく必要があります。
  • 見積もりは見積もりテンプレートでのみ関連付けることができます。
  • このAPIは、従来の見積もりと見積もり提案をサポートしていません。CUSTOMIZABLE_QUOTE_TEMPLATEテンプレートタイプのみを使用できます。

見積もり署名者を関連付ける

見積もりで電子署名の使用を有効にする場合は、特定の見積もりとコンタクト間の関連付けラベルを使用して、見積もりと署名者であるコンタクトとの間に関連付けを作成する必要もあります。

上記の既定の関連付けエンドポイントを使用するのではなく、次のURLにPUTリクエストを行う必要があります。

/crm/v4/objects/quote/{quoteId}/associations/contact/{contactId}

リクエスト本文で、次のようにassociationCategoryassociationTypeIdを指定する必要があります。

// Example request body [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 702 } ]

関連付けのある見積もりを作成する(1つのリクエスト)

次のリクエスト本文では、見積もりテンプレート、取引、2つの商品項目、および連絡先に関連付けられた、新しい見積もりを作成します。

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

見積もりステータスの更新

見積もりのステータスは、初期設定段階から一般公開までの作成プロセスの中で、どの位置にいるかを表すものです。見積もり承認がアカウントに対して有効になっている場合、見積もりのステータスは見積もりの承認プロセスを反映することもできます。見積もりのステータスを設定すると、HubSpotは特定のプロパティーを自動的に入力します。

見積もりのステータスを更新するには、/crm/v3/objects/quote/{quoteId}PATCHリクエストを送信します。

見積もりのステータスは、hs_statusフィールドに基づきます。特定の見積もりのステータスで、ユーザーは見積もり承認ワークフローで見積もりを編集、公開、使用できます。以下の見積もりのステータスを利用できます。

  • ステータスなし:hs_statusフィールドに値が指定されていない場合、見積もりは「最小限」ステータスになります。この場合、見積もりは見積もりツールのインデックスページに表示されますが、直接編集することはできません。このステータスの見積もりも、シーケンスツールなどの自動化やレポートツール内での分析に使用できます。
  • DRAFT:HubSpotで見積もりを編集できます。このステータスは、見積もりが完全に設定されていない場合や、HubSpotでの見積もり設定プロセスを営業担当者によって完了できるようにしたい場合に役立ちます。 
  • APPROVAL_NOT_NEEDED承認を必要とせずに、誰でもアクセス可能なURL(hs_quote_link)で見積もりを公開します。
  • PENDING_APPROVAL:見積もりが公開される前の承認待ちであることを示します。
  • APPROVED:見積もりが承認され、誰でもアクセス可能なURL(hs_quote_link)に公開されました。
  • REJECTED:見積もりが設定されたものの、公開が承認されておらず、承認のために再送信する前に、編集が必要であることを示します。

注:見積もりで電子署名を有効にしている場合、毎月の電子署名数の制限を超えると見積もりが公開できなくなります。

例えば次のリクエストは、誰でもアクセス可能なURLで見積もりを公開します。
// PATCH request to https://api.hubapi.com/crm/v3/objects/quote/{QUOTE_ID} { "properties": { "hs_status": "APPROVAL_NOT_NEEDED" } }

注:既定では、見積もりの状態が更新された後で、見積もりのhs_template_typeプロパティーがCUSTOMIZABLE_QUOTE_TEMPLATEに設定されます。このテンプレートタイプはv3 APIでサポートされていますが、次のテンプレートタイプはレガシーテンプレートであり、サポートが終了しています。

  • QUOTE
  • PROPOSAL

見積もりのステータスで設定されたプロパティー

見積もりのステータスを更新すると、次のプロパティーが更新されます。

  • hs_quote_amount:関連付けられている商品項目、税金、割引、手数料に基づいて計算されます。
  • hs_domain:関連付けられている見積もりテンプレートから設定されます。
  • hs_slug:指定されていない場合は無作為に生成されます。
  • hs_quote_total_preference:アカウントの設定に基づいて設定されます。この設定が指定されていない場合には、既定値としてtotal_first_paymentフィールドの値が使用されます。
  • hs_timezone:既定値としてHubSpotアカウントのタイムゾーンが使用されます。
  • hs_locale:関連付けられている見積もりテンプレートから設定されます。
  • hs_quote_number:指定されていない場合には現在の日付と時刻に基づいて設定されます。
  • hs_language:関連付けられている見積もりテンプレートから設定されます。
  • hs_currency:関連付けられている取引に基づいて設定されます。見積もりに取引を関連付けていない場合、HubSpotアカウントの既定の通貨が既定値として使用されます。

見積もりが「公開中」ステータスに設定されるときには、次のプロパティーも計算されます。

  • hs_pdf_download_link:見積もりのPDFのURLが取り込まれます。
  • hs_lockedtrueに設定されます。見積もりを公開した後にプロパティーを変更するには、まず見積もりのhs_statusDRAFTPENDING_APPROVAL、またはREJECTEDに更新する必要があります。
  • hs_quote_link:見積もりの一般公開URL。これは読み取り専用プロパティーであり、公開後にAPIを介して設定することはできません。
  • hs_esign_num_signers_required電子署名を有効にしている場合、必要な署名の数が表示されます。

スコープ

有効で公開可能な見積もりを作成するには、次のスコープが必要です。

  • crm.objects.quotes.writecrm.objects.quotes.readcrm.objects.line_items.writecrm.objects.line_items.readcrm.objects.owners.readcrm.objects.contacts.writecrm.objects.contacts.readcrm.objects.deals.writecrm.objects.deals.readcrm.objects.companies.writecrm.objects.companies.read
  • crm.schemas.quote.readcrm.schemas.line_items.read, crm.schemas.contacts.readcrm.schemas.deals.readcrm.schemas.companies.read

参考になりましたか?
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。