取引

HubSpotにおける取引は、コンタクトまたは会社との間で進めている商取引を表します。パイプラインステージ上で成約または失注になるまでの間、トラッキングが行われます。取引エンドポイントを使用することにより、取引レコードを作成および管理したり、HubSpotと他のシステムの間で取引データを同期したりできます。 

オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、「CRMについて」のガイドをご確認ください。HubSpotのオブジェクトとレコードに関する一般的な情報については、CRMデータベースを管理する方法をご確認ください。

取引レコードを作成する

新しい取引レコードを作成するには、POSTリクエストを/crm/v3/objects/dealsに送信します。

リクエスト内のpropertiesオブジェクトに取引データを含めます。また、associationsオブジェクトを追加して、新しい取引を既存のレコード(コンタクト、会社など)やアクティビティー(ミーティング、メモなど)に関連付けることもできます。

プロパティー

取引の詳細は、取引プロパティーに保存されます。HubSpotの既定の取引プロパティーがありますが、カスタムプロパティーを作成することもできます。

新しい取引レコードを作成する際は、dealnameおよびdealstageプロパティーをリクエストに含める必要があります。また、複数のパイプラインがある場合はpipelineも含めます。パイプラインが指定されていない場合は、既定のパイプラインが使用されます。 

利用可能な全てのプロパティーを確認するには、GETリクエストを/crm/v3/properties/dealsに送信して、アカウントの取引プロパティーのリストを取得します。詳しくはプロパティーAPIをご参照ください。

:APIを介して取引を作成するときには、取引ステージまたはパイプラインの内部IDを使用する必要があります。APIを介して取引を取得すると、内部IDも返されます。案件ステージまたはパイプラインの内部IDは、案件パイプライン設定で確認できます。

例えば、新しい取引レコードを作成する場合、リクエストの内容は次のようになります。

///Example request body { "properties": { "amount": "1500.00", "closedate": "2019-12-07T16:50:06.678Z", "dealname": "New deal", "pipeline": "default", "dealstage": "contractsent", "hubspot_owner_id": "910901" } }

関連付け

新しい取引レコードを作成する際に、その取引を既存のレコードアクティビティーに関連付けることもできます。associationsオブジェクトに、次のフィールドを含めます。

Use this table to describe parameters / fields
ParameterDescription
toObjectId

取引を関連付けるレコードまたはアクティビティーのID。

associationTypeId

取引と他のオブジェクトまたはアクティビティーとの関連付けタイプを示す一意の識別子。既定の関連付けタイプは、ここにリストされています。または、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信して値を取得できます。詳しくは関連付けAPIをご確認ください。

labelフィールドを含めて、関連付けを説明する定義済み関連付けラベルを割り当てることもできます。レコードを関連付ける方法については関連付けAPIをご確認ください。

例えば、新しい取引を既存のコンタクトと会社に関連付ける場合、リクエストの内容は次のようになります。

///Example request body { "properties": { "amount": "1500.00", "closedate": "2019-12-07T16:50:06.678Z", "dealname": "New deal", "pipeline": "default", "dealstage": "contractsent", "hubspot_owner_id": "910901" }, "associations": [ { "to": { "id": 201 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 5 } ] }, { "to": { "id": 301 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3 } ] }] }

取引レコードを取得する

取引レコードを個別に、または一括で取得できます。

  • 個々の取引レコードを取得するには、GETリクエストを/crm/v3/objects/deals/{dealId}に送信します。
  • 全ての取引レコードのリストを取得するには、GETリクエストを/crm/v3/objects/dealsに送信します。
これらのエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。
Use this table to describe parameters / fields
ParameterDescription
properties
レスポンスで取得するプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
propertiesWithHistory

レスポンスで取得する現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。

associations

関連付けられているIDが取得されるオブジェクトの、カンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。

  • レコードIDまたはカスタムの固有の識別子のプロパティーを指定して、特定の取引レコードを一括で取得するには、crm/v3/objects/deals/batch/readに対してPOSTリクエストを送信します。このバッチエンドポイントは関連付けを取得できません関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。

一括読み取りエンドポイントの場合は、任意指定のidPropertyパラメーターを使用し、カスタムの固有の識別子のプロパティーを指定して、取引レコードを取得することもできます。既定で、リクエストのid値はレコード ID(hs_object_id)を表すので、レコードIDを使用して取得する場合はidPropertyパラメーターは不要です。カスタムの固有の値のプロパティーを使用して取引レコードを取得する場合は、idPropertyパラメーターを含める必要があります。

例えば、取引レコードを一括で取得する場合のリクエストは、次のいずれかのようになります。

///Example request body with record ID { "properties": [ "dealname", "dealstage", "pipeline" ], "inputs": [ { "id": "7891023" }, { "id": "987654" } ] }
///Example request body with a unique value property { "properties": [ "dealname", "dealstage", "pipeline" ], "idProperty": "uniqueordernumber", "inputs": [ { "id": "0001111" }, { "id": "0001112" } ] }

プロパティーの現在の値と過去の値を含む取引を取得する場合のリクエストは、次のようになります。

///Example request body with record ID (current and historical values) { "propertiesWithHistory": [ "dealstage" ], "inputs": [ { "id": "7891023" }, { "id": "987654" } ] }

取引レコードを更新する

取引レコードを個別に、または一括で更新できます。既存の取引の場合、APIを介してそのレコードを更新するために使用できる一意の値は、取引IDです。

取引IDを基準に個々の取引レコードを更新するには、PATCHリクエストを/crm/v3/objects/deals/{dealId}に送信します。リクエストには、更新するデータを含めます。

既存の取引を他のレコードまたはアクティビティーに関連付ける

取引を他のCRMレコードまたはアクティビティーに関連付けるには、PUTリクエストを  /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。

associationTypeId値を取得するには、この既定値リストを参照するか、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。

レコードを関連付ける方法について詳しくは関連付けAPIご確認ください。

関連付けを削除する

取引と他のレコードまたはアクティビティーの関連付けを削除するには、DELETEリクエストを/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。

取引レコードを削除する

取引レコードを個別に、または一括で削除できます。削除した取引レコードは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後でHubSpot内で取引レコードを復元できます。

IDを基準に個々の取引レコードを削除するには、DELETEリクエストを/crm/v3/objects/deals/{dealId}に送信します。

取引レコードを一括で削除する方法については、この記事の上部にある[エンドポイント]タブをクリックしてください。


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