取引
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は、案件パイプライン設定で確認できます。
例えば、新しい取引レコードを作成する場合、リクエストの内容は次のようになります。
label
フィールドを含めて、関連付けを説明する定義済み関連付けラベルを割り当てることもできます。レコードを関連付ける方法については関連付けAPIをご確認ください。
例えば、新しい取引を既存のコンタクトと会社に関連付ける場合、リクエストの内容は次のようになります。
取引レコードを個別に、または一括で取得できます。
- 個々の取引レコードを取得するには、
GET
リクエストを/crm/v3/objects/deals/{dealId}
に送信します。 - 全ての取引レコードのリストを取得するには、
GET
リクエストを/crm/v3/objects/deals
に送信します。
Parameter | Description |
---|---|
properties
| レスポンスで取得するプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
propertiesWithHistory
| レスポンスで取得する現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
associations
| 関連付けられているIDが取得されるオブジェクトの、カンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。 |
- レコードIDまたはカスタムの固有の識別子のプロパティーを指定して、特定の取引レコードを一括で取得するには、
crm/v3/objects/deals/batch/read
に対してPOST
リクエストを送信します。このバッチエンドポイントは関連付けを取得できません。関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。
一括読み取りエンドポイントの場合は、任意指定のidProperty
パラメーターを使用し、カスタムの固有の識別子のプロパティーを指定して、取引レコードを取得することもできます。既定で、リクエストのid
値はレコード ID(hs_object_id
)を表すので、レコードIDを使用して取得する場合はidProperty
パラメーターは不要です。カスタムの固有の値のプロパティーを使用して取引レコードを取得する場合は、idProperty
パラメーターを含める必要があります。
例えば、取引レコードを一括で取得する場合のリクエストは、次のいずれかのようになります。
プロパティーの現在の値と過去の値を含む取引を取得する場合のリクエストは、次のようになります。
取引レコードを個別に、または一括で更新できます。既存の取引の場合、APIを介してそのレコードを更新するために使用できる一意の値は、取引IDです。
取引IDを基準に個々の取引レコードを更新するには、PATCH
リクエストを/crm/v3/objects/deals/{dealId}
に送信します。リクエストには、更新するデータを含めます。
取引を他のCRMレコードまたはアクティビティーに関連付けるには、PUT
リクエストを /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
に送信します。
取引レコードを個別に、または一括で削除できます。削除した取引レコードは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後でHubSpot内で取引レコードを復元できます。
IDを基準に個々の取引レコードを削除するには、DELETE
リクエストを/crm/v3/objects/deals/{dealId}
に送信します。
取引レコードを一括で削除する方法については、この記事の上部にある[エンドポイント]タブをクリックしてください。
貴重なご意見をありがとうございました。