取引

概要エンドポイント

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

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

取引レコードを作成する

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

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

プロパティー

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

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

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

Please note: you must use the internal ID of a deal stage or pipeline when creating a deal via the API. The internal ID will also be returned when you retrieve deals via the API. You can find a deal stage's or pipeline's internal ID in your deal pipeline settings.

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

///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
レスポンスで取得するプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
associations

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

取引レコードを取得する方法については、この記事の上部にある［エンドポイント］タブをクリックしてください。

取引レコードを更新する

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

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

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

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

To retrieve the associationTypeId value, make a GET request to /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がご提供しているヘルプはこちらでご確認ください。