見積もり

注：HubSpotは見積もりAPIのいくつかの新機能をリリースしました。これらの機能は現在ベータ版であり、開発途中のためテストとフィードバックに基づいて今後変更が生じる可能性があります。リリースされたベータ版の機能をご利用いただくことによって、HubSpotの開発者向け規約とDeveloper Beta Terms（開発者向けベータ版利用規約）（英語）に同意したものと見なされます。

現在ベータ版で提供中の新機能には次のようなものがあります。

  • 見積もりの作成と更新
  • 割引、手数料、税金の管理
  • 割引、手数料、税金の見積もりへの関連付け
  • OAuthアクセスと以下に示す新しいスコープ
以前リリースされたエンドポイントは既存の見積もり取得のために引き続き完全にサポートされており、事前の通知なしに破損につながる変更が行われることはありません。
概要エンドポイント

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

見積もりの構造

全ての情報を記載した見積もりは、コア見積もりオブジェクト、見積もりテンプレート、およびその他の関連オブジェクトで構成されます。コアオブジェクトには、名前やステータスなどのさまざまなメタデータフィールドが含まれ、コンタクト、会社、取引レコードを見積もりに関連付けることができます。また、商品項目、手数料、税金、または割引データを関連付けることもできます。

HubSpotアカウント内で公開して編集できる完全な見積もりを作成するには、次のCRMオブジェクトとフィールドが必要です。

  • コア見積もりオブジェクト：見積もりの名前、ステータス、ドメインなどのメタデータを格納するオブジェクト。
  • 見積もりテンプレート：見積もりを表示するために使用されるCMSテンプレート。見積もりの既定設定（言語など）が含まれます。
  • 商品項目：見積もりの一部である販売対象のアイテムまたはサービスの個別レコード。
  • 取引：完全な見積もりは、関連付けられている取引から特定の値を反映します（通貨など）。 

完全な見積もりを作成するときに、次の任意のプロパティーを関連付けることもできます。

  • 手数料：適用される全ての手数料
  • 税金：適用される全ての税金
  • 割引：適用される全ての割引
  • コンタクト：見積もりの対象とする特定の顧客
  • 会社：見積もりの対象とする特定の会社

見積もりのステータス

見積もりのステータスは、コア見積もりオブジェクト内のhs_statusフィールドから取得されます。見積もりのステータスは、HubSpotアカウントの見積もりツールを使用して、見積もりを編集、公開、自動化、または報告することができるかどうかを示します。

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

制限事項

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

  • v3 APIからの旧バージョンの見積もりまたは見積もり提案の作成。
  • 見積もりテンプレートの作成または変更。v3見積もりAPIを使用して見積もりテンプレートを参照する前に、HubSpotアカウント内で見積もりテンプレートを作成またはカスタマイズしておく必要があります。
  • 電子署名、Stripe決済、またはHubSpot Paymentsの使用。
  • 見積もりレベルの割引、手数料、税金の繰り返しの使用。

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

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

スコープ

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

  • 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

見積もりの作成

v3 APIから見積もりを作成するには、コア見積もりオブジェクトを作成してから、取引、見積もりテンプレート、および商品項目を関連付けます。必要に応じて、会社またはコンタクトを見積もりに関連付け、割引、手数料、税金を設定することができます。見積もりの編集および使用目的に基づいて、見積もりのステータスを更新できます。

コア見積もりオブジェクトの作成

最初に、/crm/v3/objects/quoteにPOSTリクエストを送信して「最小限」のステータスで見積もりを作成し、名前と有効期限を指定します。

// POST request to https://api.hubapi.com/crm/v3/objects/quote { "properties": { "hs_title": "A new quote", "hs_expiration_date": "2022-04-02" } }

取引の関連付け

コア見積オブジェクトを作成したら、/crm/v3/objects/deal/{DEAL_ID}/associations/quote/{QUOTE_ID}/deal_to_quoteにPUTリクエストを送信して取引を関連付けることができます。

  • DEAL_IDを取得するには、/crm/v3/objects/dealsにGETリクエストを送信できます。取引APIの詳細については、こちらをご覧ください。
  • 取引の関連付けが完了すると、取引の所有者とチームの詳細が見積もりに反映されます。
  • 見積もりに関連付けることができる取引は1件のみです。

見積もりテンプレートを関連付ける

次に、既存の見積もりテンプレートを見積もりに関連付けるため、/crm/v3/objects/quote_template/{QUOTE_TEMPLATE_ID}/associations/quote/{QUOTE_ID}/quote_template_to_quoteにPUTリクエストを送信します。

  • QUOTE_TEMPLATE_IDを取得するには、/crm/v3/objects?properties=hs_name,hs_activeにGETリクエストを送信して、関連付けることができるアクティブな見積もりテンプレートのリストを取得します。
  • 見積もりに関連付けることができる見積もりテンプレートは1つのみです。

商品項目を作成して関連付ける

商品項目APIを使用して、見積もりに関連付けることができる商品項目を作成できます。単独の商品項目を作成するには、/crm/v3/objects/line_itemにPOSTリクエストを送信します。

// POST request to https://api.hubapi.com/crm/v3/objects/line_item { "properties": { "price": 10, "quantity": 1, "name": "New standalone line item" } }

既存の製品に基づいて商品項目を作成することもできます。このためには、新しい商品項目に反映する他の製品フィールドとともに、リクエストのpropertiesフィールドにhs_product_idを指定します。

// POST request to https://api.hubapi.com/crm/v3/objects/line_item { "properties": { "hs_product_id": "1360404657", "hs_line_item_currency_code": "EUR", "name": "Product-derived line item" } }

商品項目を作成したら、/crm/v3/objects/line_item/{LINE_ITEM_ID}/associations/quote/{QUOTE_ID}/line_item_to_quoteにPUTリクエストを送信して、商品項目を見積もりに関連付けることができます。 

商品項目のIDを調べる必要がある場合は、/crm/v3/objects/line_itemにGETリクエストを送信できます。商品項目を作成すると、応答でIDも返されます。

会社とコンタクトの関連付け

必要に応じて、会社または個人のコンタクトを見積もりに関連付けることができます。見積に関連付けられる会社は1件のみですが、コンタクトは複数の関連付けることが可能です。

  • 会社を見積もりに関連付けるには、/crm/v3/objects/company/{COMPANY_ID}/associations/quote/{QUOTE_ID}/company_to_quoteにPUTリクエストを送信します。 
  • コンタクトを関連付けるには、/crm/v3/objects/contact/{CONTACT_ID}/associations/quote/{QUOTE_ID}/contact_to_quoteにPUTリクエストを送信します。

割引、手数料、税金を作成して関連付ける

割引、手数料、税金の作成と関連付けが、見積もり作成の最後のステップとなります。これらの関連付けを行う際には、次の点にご留意ください。

  • HubSpotでは見積もり総額を決定する際に、割引、手数料、税金がこの順序で適用されます。同じタイプのオブジェクトを並べ替えるには、hs_sort_orderフィールドを使用します。
  • 割引、手数料、税金は、固定値またはパーセンテージで指定できます。このためには、hs_typeフィールドにFIXEDまたはPERCENTを設定します。

次の手順で、割引を作成します。

// POST request to https://api.hubspi.com/crm/v3/objects/discount { "properties": { "hs_label": "A fixed, one-time discount", "hs_duration": "ONCE", "hs_type": "PERCENT", "hs_value": "50", "hs_sort_order": "2" } }

次の手順で、手数料をパーセンテージ割引で作成します。

// POST request to https://api.hubspi.com/crm/v3/objects/fee { "properties": { "hs_label": "A percentage-based fee of 10%", "hs_type": "PERCENT", "hs_value": "10", } }

次の手順で、税金をパーセンテージで作成します。

// POST request to https://api.hubspi.com/crm/v3/objects/tax { "properties": { "hs_label": "A percentage-based tax of 6.5%", "hs_type": "PERCENT", "hs_value": "6.5" } }

割引、税金、手数料を作成したら、見積もりに関連付けます。

  • 割引を関連付けるには、/crm/v3/objects/discount/{DISCOUNT_ID}/associations/quote/{QUOTE_ID}/discount_to_quoteにPUTリクエストを送信します。
  • 手数料を関連付けるには、/crm/v3/objects/fee/{FEE_ID}/associations/quote/{QUOTE_ID}/fee_to_quoteにPUTリクエストを送信します。
  • 税金を関連付けるには、/crm/v3/objects/tax/{TAX_ID}/associations/quote/{QUOTE_ID}/tax_to_quoteにPUTリクエストを送信します。

見積もりのステータスを更新する

見積もりの設定が完了したら、そのステータスを更新できます。このためには、/crm/v3/objects/quote/{QUOTE_ID}にPATCHリクエストを送信します。見積もりの各ステータスについては前のセクションをご参照ください。 

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

// PATCH request to https://api.hubapi.com/crm/v3/objects/quote/{QUOTE_ID} { "properties" { "hs_status": "APPROVAL_NOT_NEEDED" } }

見積もりの新しいステータスに基づいて、見積もりオブジェクトのいくつかの派生プロパティーが自動的に更新されます。

見積もりのステータスを「編集可能」、「公開可能」、または「公開中」に更新すると、次のプロパティーが取得されます。

  • 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を確認できます。

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