> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt > Use this file to discover all available pages before exploring further. # CRM API | 取引 export const postmanIcon = ; export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return

{description}

{sortedScopes.map((scope, index) =>


              {scope}

)}

; }; HubSpotにおける「取引」とは、コンタクトまたは会社との間で進めている商取引を表します。[パイプラインステージ](https://knowledge.hubspot.com/ja/object-settings/set-up-and-customize-pipelines)上で成約または失注になるまでの間、営業プロセスを通してトラッキングが行われます。取引エンドポイントを使用することにより、取引レコードを作成、管理したり、HubSpotと他のシステムの間で取引データを同期したりできます。オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、[CRMのガイド](/guides/crm/understanding-the-crm)をご確認ください。HubSpotのオブジェクトとレコードに関する一般的な情報については、[CRMデータベースを管理する方法](https://knowledge.hubspot.com/ja/get-started/manage-your-crm-database)をご確認ください。 ## 取引を作成する新しい取引を作成するには、`POST`リクエストを`/crm/v3/objects/deals`に送信します。リクエスト本文の`properties`オブジェクトに取引データを含めます。また、`associations`オブジェクトを追加して、新しい取引を既存のレコード（コンタクト、会社など）またはアクティビティー（ミーティング、メモなど）に関連付けることもできます。 ### プロパティー取引の詳細は、取引プロパティーに格納されます。HubSpot には[デフォルトの取引プロパティー](https://knowledge.hubspot.com/ja/properties/hubspots-default-deal-properties)が用意されていますが、[カスタムプロパティーを作成](https://knowledge.hubspot.com/ja/properties/create-and-edit-properties)することもできます。新しい取引を作成する際には`dealname`と`dealstage`のプロパティーをリクエストに含める必要があります。また、複数のパイプラインがある場合は`pipeline`も含めます。パイプラインが指定されない場合、デフォルトのパイプラインが使用されます。利用可能な全てのプロパティーを確認するには、`GET`リクエストを`/crm/v3/properties/deals`に送信して、アカウントの取引プロパティーのリストを取得します。詳しくは[プロパティーAPI](/api-reference/crm-properties-v3/guide)をご参照ください。 ### 注： APIを介して取引を作成する際は、取引ステージまたはパイプラインの内部IDを使用する必要があります。APIを介して取引を取得すると、内部IDも返されます。取引ステージまたはパイプラインの内部IDは、[取引パイプライン設定](https://knowledge.hubspot.com/ja/object-settings/set-up-and-customize-pipelines#edit-or-delete-pipelines)で確認できます。例えば、新しい取引レコードを作成する場合、リクエストの内容は以下のようになります。 ```json theme={null} { "properties": { "amount": "1500.00", "closedate": "2019-12-07T16:50:06.678Z", "dealname": "New deal", "pipeline": "default", "dealstage": "contractsent", "hubspot_owner_id": "910901", "hs_all_collaborator_owner_ids": ";12345678;9101112" } } ``` ### 関連付けまた、新しい取引を作成する際には、`associations`オブジェクトで[既存のレコード](https://knowledge.hubspot.com/ja/records/associate-records)または[アクティビティー](https://knowledge.hubspot.com/ja/records/associate-activities-with-records)に関連付けることもできます。例えば、新しい取引を既存のコンタクトと会社に関連付ける場合、リクエストの内容は以下のようになります。 ```json theme={null} { "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 } ] } ] } ``` 以下を`associations`オブジェクトに含める必要があります。 | パラメーター | 説明 | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `to` | 取引に関連付けるレコードまたはアクティビティー。一意の`id`値で指定します。 | | `types` | 取引とレコードまたはアクティビティーの間の関連付けのタイプ。`associationCategory`と`associationTypeId`を含めます。デフォルトの関連付けタイプIDは[こちらのページ](/api-reference/crm-associations-v4/guide#association-type-id-values)に記載されています。または、[関連付けAPI](/api-reference/crm-associations-v4/guide#retrieve-association-types)を使用して、カスタム関連付けタイプ（ラベル）の値を取得することもできます。 | ## 取引を取得する取引レコードを個別に、または一括で取得できます。 * 取引を個別に取得するには、`GET`リクエストを`/crm/v3/objects/deals/{dealId}`に送信します。 * 全ての取引のリストを要求するには、`GET`リクエストを`/crm/v3/objects/deals`に送信します。これらのエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。 | パラメーター | 説明 | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `properties` | レスポンスで返されるプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 | | `propertiesWithHistory` | レスポンスで返される現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 | | `associations` | 関連付けられたIDを取得する対象のオブジェクトのカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは[関連付けAPI](/api-reference/crm-associations-v4/guide)をご参照ください。 | * レコードIDまたは[カスタム固有IDプロパティー](/api-reference/crm-properties-v3/guide#create-unique-identifier-properties)を指定して特定の取引を一括で取得するには、`POST`リクエストを`crm/v3/objects/deals/batch/read`に送信します。 * このバッチエンドポイントは関連付けを取得できません。詳しくは、[関連付けAPI](/api-reference/crm-associations-v4/guide)を使用して関連付けを一括読み取りする方法をご参照ください。 * 取引IDではなくカスタムの[固有IDプロパティー](/api-reference/crm-properties-v3/guide#create-unique-identifier-properties)によって取引を取得するには、リクエスト本文に`idProperty`パラメーターを含めてプロパティー名を指定します。次に、`inputs`配列に取引IDではなく固有IDプロパティーの値を含めます。例えば、取引レコードを一括で取得する場合のリクエストは、以下のいずれかのようになります。 ```text get by id.txt theme={null} { "properties": ["dealname", "dealstage", "pipeline"], "inputs": [ { "id": "7891023" }, { "id": "987654" } ] } ``` ```text get by unique property.txt theme={null} { "properties": ["dealname", "dealstage", "pipeline"], "idProperty": "uniqueordernumber", "inputs": [ { "id": "0001111" }, { "id": "0001112" } ] } ``` 特定のプロパティーの現在の値と過去の値を含む取引を取得するには、以下の通り、リクエスト本文に`propertiesWithHistory`パラメーターを含めます。 ```json theme={null} { "propertiesWithHistory": ["dealstage"], "inputs": [ { "id": "7891023" }, { "id": "987654" } ] } ``` ## 取引を更新する取引レコードを個別に、または一括で更新できます。既存の取引の場合、APIを介してそのレコードを更新するために使用できるデフォルトの一意の値は、取引IDです。ただし、[カスタムの固有IDプロパティー](/api-reference/crm-properties-v3/guide#create-unique-identifier-properties)を使用して取引を識別することもできます。 * レコードIDを基に取引を個別に更新するには、`PATCH`リクエストに更新対象のデータを含めて`/crm/v3/objects/deals/{dealId}`に送信します。 * 複数の取引を更新するには、`POST`リクエストを`/crm/v3/objects/deals/batch/update`に送信します。リクエストの本文に、取引の識別子と更新するプロパティーを含む配列を含めます。 ### 既存の取引を他のレコードまたはアクティビティーに関連付ける取引を他のCRMレコードやアクティビティーに関連付けるには、`PUT`リクエストを`/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`に送信します。 `associationTypeId`値を取得するには、[デフォルト値のリスト](/api-reference/crm-associations-v4/guide#association-type-id-values)を参照するか、`GET`リクエストを`/crm/v4/associations/{fromObjectType}/{toObjectType}/labels`に送信します。レコード関連付けの詳細については[関連付けAPI](/api-reference/crm-associations-v4/guide)をご確認ください。 ### 関連付けを削除する取引とレコードまたはアクティビティーの間の関連付けを削除するには、`DELETE`リクエストを`/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`に送信します。 ## 取引レコード上でアクティビティーをピン留めするリクエストに`hs_pinned_engagement_id`パラメーターを含めることで、APIを介して取引レコードでアクティビティーをピン留めできます。パラメーターの値には、ピン留めするアクティビティーのIDを指定します。これは[エンゲージメントAPI](/api-reference/overview)を介して取得できます。レコードごとに1つのアクティビティーをピン留めすることができ、そのアクティビティーはピン留めする前にすでに取引に関連付けられている必要があります。取引にピン留めするアクティビティーを設定または更新する場合、リクエストは以下のようになります。 ```json theme={null} { "properties": { "hs_pinned_engagement_id": 123456789 } } ``` 同じリクエスト内で、取引を作成し、既存のアクティビティーに関連付け、アクティビティーをピン留めすることもできます。以下に例を示します。 ```json theme={null} { "properties": { "dealname": "New deal", "pipelines": "default", "dealstage": "contractsent", "hs_pinned_engagement_id": 123456789 }, "associations": [ { "to": { "id": 123456789 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 213 } ] } ] } ``` ## 取引を削除する取引レコードを個別に、または一括で削除できます。削除した取引レコードは、HubSpot内のごみ箱に追加されます。後から[HubSpot内で取引を復元](https://knowledge.hubspot.com/ja/records/restore-deleted-records)することも可能です。 * IDを基準に[取引を個別に削除](/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D)するには、`DELETE`リクエストを`/crm/v3/objects/deals/{dealId}`に送信します。このリクエストにリクエスト本文は必要ありません。 * [取引を一括で削除する](/api-reference/crm-deals-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2Fbatch%2Farchive)には、`POST`リクエストを`/crm/v3/objects/deals/batch/archive`に送信します。以下の例のように、リクエスト本文には取引IDの値を`id`入力として含めます。 ```json theme={null} { "inputs": [ { "id": "123456" }, { "id": "7891011" }, { "id": "12123434" } ] } ``` 取引の削除について詳しくは、[リファレンスドキュメント](/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D)をご参照ください。