> For the complete documentation index, see [llms.txt](https://docs.dfinery.ai/api-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dfinery.ai/api-guide/api/import-api/event-api/post.md).

# POST: 이벤트 적재

<mark style="color:green;">`POST`</mark> `/api/v1/events`

이벤트 적재 API를 통해 하나 혹은 여러 이벤트를 한번에 적재할 수 있습니다. 적재하고자 하는 이벤트는 콘솔에서 사전 등록되어 있어야 합니다.

한번의 요청에서 **최대 100개의 이벤트**를 적재할 수 있습니다. 또한, 이벤트 1건당 **최대 100개의 이벤트 아이템**을 적재할 수 있습니다.

{% hint style="warning" %}
많은 이벤트를 적재 해야 한다면, 개별로 이벤트 적재 API를 호출하는 것 보다 여러 이벤트를 모아두었다가 한번에 이벤트 적재 API를 호출하는 것이 속도 및 요청 제한 측면에서 좋습니다. 연동 시에는 항상 [요청 제한](/api-guide/rate-limit.md)을 고려해야 합니다.
{% endhint %}

## **쿼리 파라미터** <a href="#query-parameters" id="query-parameters"></a>

<table><thead><tr><th width="210">이름</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>service_id</code></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>String</td><td>서비스 ID</td></tr></tbody></table>

## **헤더** <a href="#headers" id="headers"></a>

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="3Gw9yCGdnldk" label="필수" color="blue"></option><option value="mVPQehiUZOei" label="선택" color="blue"></option></select></th><th>타입</th><th>값</th><th>설명</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td><span data-option="3Gw9yCGdnldk">필수</span></td><td>String</td><td><code>application/json</code></td><td>-</td></tr><tr><td><code>access_token</code></td><td><span data-option="3Gw9yCGdnldk">필수</span></td><td>String</td><td><code>your-api-token-key</code></td><td>API 인증 토큰</td></tr></tbody></table>

## **요청 본문** <a href="#request-body" id="request-body"></a>

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><a href="#common"><code>common</code></a></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>Object</td><td>이벤트 적재를 위한 공통 속성</td></tr><tr><td><a href="#events"><code>events</code></a></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>Array of Object</td><td>이벤트 정보</td></tr></tbody></table>

### common <a href="#common" id="common"></a>

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><a href="#identity"><code>identity</code></a></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>Object</td><td>유저 식별자</td></tr></tbody></table>

### identity <a href="#identity" id="identity"></a>

유저 식별자 정보입니다. **아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.**

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>external_id</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>외부 ID</td></tr><tr><td><code>phone_no</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>전화 번호</td></tr><tr><td><code>email</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>이메일</td></tr><tr><td><code>kakao_user_id</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>카카오 ID</td></tr><tr><td><code>line_user_id</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>라인 ID</td></tr></tbody></table>

### events <a href="#events" id="events"></a>

이벤트 정보입니다. 적재하고자 하는 이벤트는 콘솔에서 사전 등록되어 있어야 합니다. 표준 이벤트와 이벤트 속성에 대한 자세한 내용은 사용자 가이드의 [이벤트 텍소노미 설계하기](https://github.com/IGAWorksDev/dfn-v2-developer-reference-gitbook/blob/main/user_guide/ko/begin-to-use-dfinery/event-and-property/taxonomy.md)를 참고해 주시면 됩니다.

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>event_log_id</code></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>String</td><td>이벤트 식별 ID, UUID Format,<br><code>xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx</code></td></tr><tr><td><code>event_name</code></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>String</td><td>이벤트명</td></tr><tr><td><code>event_datetime</code></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>Datetime</td><td>이벤트 발생 시각, UTC 타임존 기준</td></tr><tr><td><a href="#event_items"><code>event_items</code></a></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>Array of Object</td><td>상품 정보, Datetime 타입의 경우 UTC 타임존 기준</td></tr><tr><td><a href="#event_properties"><code>event_properties</code></a></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>Object</td><td>이벤트 속성, Datetime 타입의 경우 UTC 타임존 기준</td></tr></tbody></table>

### event\_items <a href="#event-items" id="event-items"></a>

이벤트 아이템 속성입니다. **필드명은 콘솔에서 사전 등록된 아이템(`df_item`) 의 하위 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다.** 이벤트 아이템은 한번에 최대 100개까지 적재 가능합니다.

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>${your-df-item-property-key}</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String, Long, Double, Boolean, Datetime, Array</td><td>사전 등록된 이벤트 아이템 속성 정보</td></tr></tbody></table>

### event\_properties <a href="#event-properties" id="event-properties"></a>

이벤트 속성입니다. **필드명은 아이템(`df_item`) 을 제외한 콘솔에서 사전 등록된 이벤트 속성의 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다.**

<table><thead><tr><th>이름</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>${your-event-property-key}</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String, Long, Double, Boolean, Datetime, Array</td><td>사전 등록된 이벤트 속성 정보</td></tr></tbody></table>

## 요청 예시 <a href="#request-example" id="request-example"></a>

```sh
curl -L \
  -X POST \
  -H 'access_token: ${your-import-api-token}' \
  -H 'Content-Type: application/json' \
  'https://openapi.dfinery.ai/api/v1/events?service_id=${your-service-id}' \
  -d '{
  "common": {
    "identity": {
      "external_id": "dfn-user-123",
      "email": "dfn@gmail.com"
    }
  },
  "events": [
    {
      "event_log_id": "b0c9cf18-f3c0-4879-bb2e-92c65858dabc",
      "event_name": "df_login",
      "event_datetime": "2024-06-24T06:01:48.501Z",
      "event_properties": null,
      "event_items": null
    },
    {
      "event_log_id": "464bc021-9c56-481e-8ee8-3bf06de7c418",
      "event_name": "df_purchase",
      "event_datetime": "2024-06-24T06:42:25.394Z",
      "event_properties": {
        "df_order_id": "dwtfmoe",
        "df_delivery_charge": 1000,
        "df_payment_method": "card",
        "df_total_purchase_amount": 4000
      },
      "event_items": [
        {
          "df_item_id": "1",
          "df_item_name": "item1",
          "df_price": 3000,
          "df_quantity": 1,
          "df_discount": 0
        }
      ]
    }
  ]
}'
```

## **응답 예시** <a href="#response-example" id="response-example"></a>

### 정상 응답 <a href="#success-response" id="success-response"></a>

```json
Content-Type: application/json
access_token: ${your-api-token}
{
  "status": true,
  "code": 20000,
  "message": "OK",
  "data": true
}
```

### 실패 응답 <a href="#error-response" id="error-response"></a>

자세한 내용은 [상세 응답](/api-guide/api/import-api/response.md) 참고하시면 됩니다.

#### 40402 TOO\_MANY\_EVENTS <a href="#error-40402" id="error-40402"></a>

이벤트 수가 100개를 초과한 경우입니다.

```json
Content-Type: application/json
access_token: ${your-api-token}
{
  "status": false,
  "code": 40402,
  "message": "TOO_MANY_EVENTS",
  "data": true
}
```