見積もり

概要エンドポイント

HubSpotの見積もりツールは、購入を検討している見込み客に価格情報を提供するために使用します。見積もりエンドポイントを使用することにより、見積もりを作成、取得したり、HubSpotと他のシステムとの間で同期したりできます。

制限事項

v3の見積もりAPIを使用している場合、次の機能は現在サポートされません。

  • v3のAPIによる、旧バージョンの見積もり、または見積もり提案の作成。v3のAPIで見積もりを作成する場合は、CUSTOMIZABLE_QUOTE_TEMPLATEテンプレートタイプのみを使用できます。詳しくは見積もりを見積もりテンプレートに関連付ける方法をご確認ください。
  • 見積もりテンプレートの作成または変更。v3の見積もりAPIを使用して見積もりテンプレートを参照する前に、HubSpotアカウント内で見積もりテンプレートを作成またはカスタマイズしておく必要があります。
  • 電子署名、Stripe決済、またはHubSpotの支払いツールの使用。
  • 見積もり単位での割引、手数料、税金の繰り返しの使用。

見積もりを作成する際には、次の制限事項にご注意ください。

  • APIを使用して見積もりに見積もりテンプレートを関連付ける前に、HubSpotアカウントで見積もりテンプレートを作成しておく必要があります。
  • 「公開可能」または「公開中」ステータスの見積もりには、取引が関連付けられていなければなりません。

見積もりの作成

見積もりを作成するには、POSTリクエストを/crm/v3/objects/quoteに送信します。

POSTリクエスト本文には、次の必須プロパティーを含めます。

Use this table to describe parameters / fields
ParameterDescription
hs_title

見積もりの名前。

hs_expiration_date

見積もりの有効期限。
GETリクエストをcrm/v3/properties/quotesに送信すると、利用可能な全ての見積もりプロパティーをプロパティーAPIから取得できます。

プロパティーに加えて、関連付けも作成リクエストで指定できます。ただし、関連付けAPIを使用して、作成後に見積もりを関連付けることもできます。

関連付け

作成時に見積もりを他のCRMレコードと関連付けるには、POSTリクエスト本文にassociations配列を含めます。この配列に、関連付けごとの対象オブジェクトを格納します。 

見積もりをHubSpotで完全にアクセス、編集、公開可能にするには、次の関連付けが必要です。

  • 見積もりテンプレート：見積もりを表示するために使用されるCMSテンプレート。見積もりの既定設定（言語など）が含まれます。見積テンプレートIDを取得するには、GETリクエストを/crm/v3/objects/quote_template?properties=hs_name,hs_activeに送信して、アクティブな見積もりテンプレートのリストを取得します。詳しくはカスタム見積もりテンプレートの作成（英語）をご確認ください。1件の見積もりに関連付けることができる見積もりテンプレートは1つのみです。
  • 取引：収益とライフサイクルを追跡するために使用される、HubSpot内の取引レコード。見積もりは、関連付けられた取引から特定の値（担当者、通貨など）を継承します。1件の見積もりに関連付けることができる取引レコードは1つのみです。
  • 商品項目：見積もりに含まれる、販売対象の個々の製品またはサービス。商品項目APIを使用して、スタンドアロンの商品項目または（製品APIを使用して、もしくはHubSpot内で作成された）製品に基づく商品項目を作成できます。商品項目のIDは、商品項目APIから取得でき、商品項目の作成時にも返されます。

オプションの関連付け

さらに、見積もりを次のオブジェクトと関連付けることもできます。

  • コンタクト：見積もりの対象とする特定の顧客。
  • 会社：見積もりの対象とする特定の会社。1件の見積もりを関連付けることができる会社は1社のみです。
  • 割引（英語）、手数料（英語）、税金（英語）：決済時に見積もり額に対して適用される割引、手数料、税金。HubSpotでは見積もり総額を決定する際に、割引、手数料、税金の順序で適用されます。同じタイプのオブジェクトを並べ替えるには、hs_sort_orderフィールドを使用します。割引、手数料、税金は、固定値またはパーセンテージで指定できます。そのためには、hs_typeフィールドの値をFIXEDまたはPERCENTに設定します。

例えば、次のPOSTリクエスト本文を送信すると、「New quote」という名前の見積もりが作成され、その見積もりが見積もりテンプレート（ID：12345）と取引（ID：67890）に関連付けられます。

// POST request to https://api.hubapi.com/crm/v3/objects/quote { "properties": { "hs_title": "New quote", "hs_expiration_date": "2023-04-02" }, "associations": [ { "to": { "id": 12345 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 286 } ] }, { "to": { "id": 67890 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 64 } ] } ] }
associationTypeIdを取得するには、/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに対してGETリクエストを行います。詳しくは関連付けAPIをご参照ください。

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

見積もりの設定が完了したら、ステータスを更新できます。更新するには、/crm/v3/objects/quote/{QUOTE_ID}にPATCHリクエストを送信します。

見積もりのステータスは、hs_statusフィールドから取得されます。見積もりのステータスによって、HubSpotアカウントの見積もりツールを使用して見積もりの編集、公開、自動化、またはレポート作成ができるかどうかが示されます。

  • 最小限：hs_statusフィールドに値が指定されていない場合、見積もりは「最小限」ステータスになります。この場合、見積もりは見積もりツールのインデックスページに表示されますが、直接編集することはできません。「最小限」ステータスの見積もりでも、シーケンスツールなどの自動化やレポートツール内での分析に使用できます。
  • 編集可能：hs_statusフィールドの値をDRAFTに設定すると、見積もりは「編集可能」ステータスになり、見積もりツールで直接編集できるようになります。
  • 公開可能：hs_statusフィールドの値がPENDING_APPROVALまたはREJECTEDに設定されると、見積もりのステータスが「公開可能」に変わります。
  • 公開中：hs_statusフィールドの値がAPPROVAL_NOT_NEEDEDまたはAPPROVEDに設定されると、見積もりが一般公開されているURLで公開されます。APPROVEDは、見積もり承認ワークフローでのみ使用されます。

例えば、次のリクエストで見積もりのステータスを「公開中」に更新できます。

// 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_locked：trueに設定されます。見積もりを公開した後にプロパティーを変更するには、まず見積もりのhs_statusをDRAFT、PENDING_APPROVAL、またはREJECTEDに更新する必要があります。

見積もりが公開されたら、hs_domainとhs_slugフィールドを連結することで、一般公開されている見積もりのURLを確認できます。

スコープ

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

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