HubSpot API 거래

거래(deals)는 진행 중인 판매 거래(transaction)에 대한 데이터를 저장해요. HubSpot의 거래는 연락처(contact)나 회사(company)와 연결된 판매 과정으로, 파이프라인 단계(pipeline stages)를 따라 진행되다가 성사(won)되거나 실패(lost)돼요. 이 거래 엔드포인트 덕분에 거래 레코드를 만들고 관리하고, HubSpot과 다른 시스템 사이에 거래 데이터를 동기화할 수 있어요.

거래는 CRM에서 객체(object)의 하나로 취급돼요. 객체와 레코드, 속성(properties), 연결(associations) API에 대해 더 자세히 알고 싶다면 Understanding the CRM 가이드를 참고하면 좋아요.

출처: 문서

본문

거래 만들기 (Create deals)

새 거래를 만들려면 /crm/v3/objects/deals 엔드포인트로 POST 요청을 보내요. 요청 본문의 properties 객체에 거래 데이터를 넣고, 새 거래를 기존 레코드(예: 연락처, 회사)나 활동(예: 회의, 메모)과 연결하고 싶다면 associations 객체도 같이 추가할 수 있어요.

curl -X POST \
  'https://api.hubapi.com/crm/v3/objects/deals' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

속성 (Properties)

거래 상세 정보는 거래 속성(deal properties)에 저장돼요. HubSpot은 기본 거래 속성을 제공하고, 필요하면 커스텀 속성도 만들 수 있어요.

새 거래를 만들 때는 요청에 다음 속성을 포함하는 게 좋아요: dealname, dealstage, 그리고 파이프라인이 여러 개라면 pipeline. 파이프라인을 지정하지 않으면 기본 파이프라인(default pipeline)이 사용돼요.

계정에서 사용 가능한 모든 거래 속성 목록을 보려면 /crm/v3/properties/deals 엔드포인트로 GET 요청을 보내면 돼요. 자세한 내용은 properties API를 참고하세요.

주의: API로 거래를 만들 때는 반드시 거래 단계(deal stage)나 파이프라인의 **내부 ID(internal ID)**를 사용해야 해요. 내부 ID는 API로 거래를 조회할 때도 함께 반환돼요. 거래 단계나 파이프라인의 내부 ID는 거래 파이프라인 설정에서 확인할 수 있어요.

예를 들어 새 거래를 만들 때 요청은 다음과 비슷하게 생겼어요:

{
  "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)

새 거래를 만들 때 associations 객체에 기존 레코드(records)나 활동(activities)을 연결할 수도 있어요. 예를 들어 새 거래를 기존 연락처와 회사에 연결한다면 요청은 다음과 같아요:

{
  "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 객체에 포함해야 하는 항목은 다음과 같아요:

Parameter	설명
`to`	거래와 연결하려는 레코드나 활동을 고유한 `id` 값으로 지정해요.
`types`	거래와 레코드/활동 사이의 연결 유형이에요. `associationCategory`와 `associationTypeId`를 포함해요. 기본 연결 유형 ID는 여기에 나열되고, 커스텀 연결 유형(레이블)의 값은 associations API로 조회할 수 있어요.

거래 조회하기 (Retrieve deals)

거래는 개별 또는 배치(batch)로 조회할 수 있어요.

개별 거래를 조회하려면 /crm/v3/objects/deals/{dealId}로 GET 요청을 보내요.
모든 거래 목록을 요청하려면 /crm/v3/objects/deals로 GET 요청을 보내요.

이 엔드포인트에서는 요청 URL에 다음 쿼리 파라미터를 포함할 수 있어요:

Parameter	설명
`properties`	응답에 반환할 속성 목록(쉼표로 구분). 요청한 속성이 정의되지 않았다면 응답에 포함되지 않아요. 정의됐는데 거래에 값이 없다면 `null`로 반환돼요.
`propertiesWithHistory`	응답에 반환할 현재 및 과거 속성 목록(쉼표로 구분). 요청한 속성이 정의되지 않았다면 응답에 포함되지 않아요. 정의됐는데 거래에 값이 없다면 `null`로 반환돼요.
`associations`	연결된 ID를 조회할 객체 목록(쉼표로 구분). 지정한 연결이 존재하지 않으면 응답에 포함되지 않아요. 자세한 내용은 associations API를 참고하세요.

레코드 ID나 커스텀 고유 식별자 속성으로 특정 거래들을 배치 조회하려면 crm/v3/objects/deals/batch/read로 POST 요청을 보내요.

배치 엔드포인트는 연결(associations)을 조회할 수 없어요. 연결 배치 조회 방법은 associations API를 참고하세요.

거래 ID 대신 커스텀 고유 식별자 속성으로 거래를 조회하려면, 요청 본문에 idProperty 파라미터를 넣어 속성 이름을 지정해요. 그리고 inputs 배열에는 거래 ID가 아니라 그 고유 식별자 속성의 값들을 넣어요.

예를 들어 거래들을 배치로 조회할 때 요청은 다음 두 가지 중 하나처럼 생겼어요:

id로 조회 (get by id):

{
  "properties": ["dealname", "dealstage", "pipeline"],
  "inputs": [
    { "id": "7891023" },
    { "id": "987654" }
  ]
}

고유 속성으로 조회 (get by unique property):

{
  "properties": ["dealname", "dealstage", "pipeline"],
  "idProperty": "uniqueordernumber",
  "inputs": [
    { "id": "0001111" },
    { "id": "0001112" }
  ]
}

특정 속성의 현재 값과 과거 값(히스토리)을 함께 조회하려면 요청 본문에 propertiesWithHistory 파라미터를 포함하면 돼요:

{
  "propertiesWithHistory": ["dealstage"],
  "inputs": [
    { "id": "7891023" },
    { "id": "987654" }
  ]
}

거래 업데이트하기 (Update deals)

거래는 개별 또는 배치로 업데이트할 수 있어요. 기존 거래의 경우 거래 ID가 기본 고유 값이라 API로 업데이트할 때 사용할 수 있지만, 커스텀 고유 식별자 속성으로 거래를 식별할 수도 있어요.

레코드 ID로 개별 거래를 업데이트하려면 /crm/v3/objects/deals/{dealId}로 PATCH 요청을 보내고, 업데이트할 데이터를 포함해요.
여러 거래를 업데이트하려면 /crm/v3/objects/deals/batch/update로 POST 요청을 보내요. 요청 본문에는 업데이트할 거래들의 식별자 배열과 속성을 포함해요.

기존 거래를 레코드나 활동과 연결하기 (Associate existing deals)

거래를 다른 CRM 레코드나 활동과 연결하려면 /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}로 PUT 요청을 보내요.

associationTypeId 값을 가져오려면 기본 값 목록을 참고하거나, /crm/v4/associations/{fromObjectType}/{toObjectType}/labels로 GET 요청을 보내면 돼요. 레코드 연결에 대한 자세한 내용은 associations API를 참고하세요.

연결 제거하기 (Remove an association)

거래와 레코드 또는 활동 사이의 연결을 제거하려면 다음 URL로 DELETE 요청을 보내요:

/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

거래 레코드에 활동 고정하기 (Pin an activity)

요청에 hs_pinned_engagement_id 파라미터를 포함하면 API로 거래 레코드에 활동을 고정(pin)할 수 있어요. 파라미터 값으로는 고정할 활동의 ID를 지정하면 되고, 그 ID는 engagements APIs로 조회할 수 있어요. 레코드당 하나의 활동만 고정할 수 있고, 고정하려면 활동이 미리 거래와 연결되어 있어야 해요.

거래의 고정 활동을 설정하거나 업데이트하려면 요청이 다음과 같을 수 있어요:

{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}

거래를 만들면서 기존 활동과 연결하고 같은 요청에서 활동을 고정할 수도 있어요:

{
  "properties": {
    "dealname": "New deal",
    "pipelines": "default",
    "dealstage": "contractsent",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": { "id": 123456789 },
      "types": [
        { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 213 }
      ]
    }
  ]
}

거래 삭제하기 (Delete deals)

거래는 개별 또는 배치로 삭제할 수 있어요. 삭제된 거래는 HubSpot의 휴지통(recycling bin)에 들어가고, 나중에 HubSpot 안에서 복원할 수 있어요.

ID로 개별 거래를 삭제하려면 /crm/v3/objects/deals/{dealId}로 DELETE 요청을 보내요. 이 요청에는 요청 본문이 필요 없어요.
거래를 배치 삭제하려면 /crm/v3/objects/deals/batch/archive로 POST 요청을 보내요. 요청 본문에는 아래 예시처럼 거래 ID 값을 id 입력으로 포함해요.

{
  "inputs": [
    { "id": "123456" },
    { "id": "7891011" },
    { "id": "12123434" }
  ]
}

더 알아보기 (Learn more)

공식 문서