見積もり
見積もりAPIを使用して、潜在顧客と価格情報を共有するための見積書を作成、管理、および取得します。設定が完了すると、指定されたURLまたはPDFのいずれかで、購入者と見積もりを共有できます。ユーザーはHubSpotで見積もりを管理して、詳細の追加や関連付けの更新などを行うこともできます。
使用例:ある顧客が貴社の年間SEO監査サービスパッケージの1つを購入することに関心があり、その顧客のために契約提案書を作成する必要があるとします。
以下では、APIを使用して見積もりを作成し、さまざまなプロパティー、関連付け、ステータスなどを構成する方法について説明します。
注:見積もりAPIは、電子署名や、StripeまたはHubSpotを介した支払い処理が含まれる見積もりの作成はサポートしていません。APIを介して、定期的な見積もりごとの割引、手数料、税金を設定することもできません。これらの機能を使用するには、代わりにHubSpotで見積もりを作成します。
見積もり作成プロセスのステップは、次のように分割できます。
- 見積もりの作成:名前や有効期限など、いくつかの詳細を含む見積もりを作成します。電子署名を有効にするために見積もりの設定を変更することもできます。
- 関連付けの設定:見積もりと他のタイプのCRMオブジェクトに関連付けます。例えば、商品項目、見積もりテンプレート、取引などを関連付けます。次のステップで、見積もりはこれらの関連付けられたレコードの一部とアカウントの設定から、プロパティー値を継承します。
- 見積もりステータスの設定:見積もりのステータスを設定し、購入者と共有できる状態かどうかを示します。見積もりのステータスを、下書き、または一般公開済み、などに設定すると、関連するCRMレコードとアカウント設定から特定のプロパティーが継承されます。
- 見積もりの共有:見積もりが公開されると、購入者と共有できるようになります。
見積もりを作成するには、まず/crm/v3/objects/quotes
に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.
応答には、見積もりの設定を続行するために使用するid
が含まれます。/crm/v3/objects/quotes/{quoteId}
にPATCH
リクエストを送信することで、引用プロパティーをいつでも更新できます。
見積もりで電子署名を有効にするには、true
の値を持つhs_esign_enabled
ブール値プロパティーをリクエスト本文に含めます。APIを使用して副署名者を追加することはできないため、副署名者は見積もりを公開する前にHubSpotに追加する必要があることに注意してください。また、毎月の電子署名数の制限を超えた場合は、電子署名を有効にして見積もりを公開することはできません。
後で、見積もりを見積もり署名者に関連付ける必要があります。見積もりに署名したコンタクトはHubSpotにコンタクトとして存在しますが、コンタクトとは別の関連タイプとして保存されます。見積もりを見積もり署名者に関連付ける方法について詳細をご確認ください。
完全な見積もりを作成するには、関連付けAPIを使用して、商品項目などの他のCRMレコードと関連付ける必要があります。次の表は、完全な見積もりに必要なCRMレコードの関連付けと、オプションの関連付けを示しています。IDの取得と、IDを使用して必要な関連付けを作成する方法の詳細については、続きをお読みください。
オブジェクトタイプ | 必須 | 説明 |
---|---|---|
商品項目 | はい | 見積もりをとおして販売されている商品および/またはサービス。製品ライブラリーの製品から商品項目を作成したり、カスタムスタンドアロン商品項目を作成したりすることができます。 |
見積もりテンプレート | はい | 見積もりを表示するテンプレート。見積もりの既定設定(言語など)が含まれます。各見積もりは1つのテンプレートに関連付けることができます。 |
取引 | はい | 収益と営業ライフサイクルを追跡するために使用される取引レコード。見積もりは、関連付けられた取引からの値(担当者、通貨など)を継承します。各見積もりは、1つの取引に関連付けることができます。 |
お問い合わせ先 | いいえ | 見積もりの対象とする特定の顧客。 |
会社 | いいえ | 見積もりの対象とする特定の会社。各見積もりは1つの会社に関連付けることができます。 |
割引、手数料、税金 | いいえ | 決済時に適用されるあらゆる割引、手数料、税金。合計見積もり金額を決定する際、HubSpotはまず割引を適用し、次に手数料、その次に税金を適用します。同じタイプのオブジェクトを並べ替えるには、hs_sort_order フィールドを使用します。固定値またはパーセンテージで指定できます。そのためには、hs_type の値をFIXED またはPERCENT に設定します。 |
各関連付けを作成するには、まず関連付ける各オブジェクトのIDを取得する必要があります。各IDを取得するには、関連するオブジェクトエンドポイントにGET
リクエストを送信します。各CRMオブジェクトで同様の処理を行います。各リクエストを送信するときは、必要に応じて特定のプロパティーを返すようにするために、プロパティー
クエリー パラメーターを含めることもできます。以下は、各タイプのオブジェクトに対するGET
リクエストの例です。
成功した呼び出しごとに、取得された各オブジェクトタイプの詳細を含む200
の応答が返されます。次のステップでは、id
フィールドの値を使用して関連付けを設定します。
IDが取得されると、関連付けAPIを呼び出して関連付けを作成できるようになります。
見積もりに関連付けるオブジェクトのタイプごとに、以下のURL構造を使用してPUT
リクエストを送信することで、個別の呼び出しを行う必要があります。
/crm/v4/objects/quotes/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}
Parameter | Description |
---|---|
fromObjectId
| 見積もりのID |
toObjectType
| 関連付けているオブジェクトのタイプ。例えば、 |
toObjectId
| 見積もりを関連付けるオブジェクトのID。 |
以下は、各タイプのオブジェクトに対するPUT
リクエストの例です。
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である。
注:見積もりを見積もりテンプレートに関連付ける場合は、次の制限に注意してください。
- 見積もりテンプレートに見積もりを関連付ける前に、見積もりテンプレートを作成しておく必要があります。
- 見積もりは見積もりテンプレートでのみ関連付けることができます。
- このAPIは、従来の見積もりと見積もり提案をサポートしていません。
CUSTOMIZABLE_QUOTE_TEMPLATE
テンプレートタイプのみを使用できます。
見積もりで電子署名の使用を有効にする場合は、特定の見積もりとコンタクト間の関連付けラベルを使用して、見積もりと署名者であるコンタクトとの間に関連付けを作成する必要もあります。
上記の既定の関連付けエンドポイントを使用するのではなく、次のURLにPUT
リクエストを行う必要があります。
/crm/v4/objects/quote/{quoteId}/associations/contact/{contactId}
リクエスト本文で、次のようにassociationCategory
とassociationTypeId
を指定する必要があります。
次のリクエスト本文では、見積もりテンプレート、取引、2つの商品項目、および連絡先に関連付けられた、新しい見積もりを作成します。
POST
/crm/v3/objects/quote
properties object
Quote details, which can be retrieved through the properties API. Required properties are: |
⮑ hs_title string (required)The name of the quote. |
⮑ hs_expiration_date string (required)The date that the quote expires. |
⮑ hs_status stringThe 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. |
見積もりのステータスは、初期設定段階から一般公開までの作成プロセスの中で、どの位置にいるかを表すものです。見積もり承認がアカウントに対して有効になっている場合、見積もりのステータスは見積もりの承認プロセスを反映することもできます。見積もりのステータスを設定すると、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
:見積もりが設定されたものの、公開が承認されておらず、承認のために再送信する前に、編集が必要であることを示します。
注:見積もりで電子署名を有効にしている場合、毎月の電子署名数の制限を超えると見積もりが公開できなくなります。
注:既定では、見積もりの状態が更新された後で、見積もりの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_quote_link
:見積もりの一般公開URL。これは読み取り専用プロパティーであり、公開後にAPIを介して設定することはできません。hs_esign_num_signers_required
:電子署名を有効にしている場合、必要な署名の数が表示されます。
有効で公開可能な見積もりを作成するには、次のスコープが必要です。
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
貴重なご意見をありがとうございました。