> 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개의 이벤트를 적재**할 수 있습니다. 또한, 한번의 요청에서 **최대 100개의 이벤트 아이템을 적재**할 수 있습니다.

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

## **쿼리 파라미터**

<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>

## **헤더**

<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>

## **요청 본문**

<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

<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

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

<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

이벤트 정보입니다. 적재하고자 하는 이벤트는 콘솔에서 사전 등록되어 있어야 합니다. 표준 이벤트와 이벤트 속성에 대한 자세한 내용은 사용자 가이드의 [이벤트 텍소노미 설계하기](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

이벤트 아이템 속성입니다. **필드명은 콘솔에서 사전 등록된 아이템(`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

이벤트 속성입니다. **필드명은 아이템(`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>

## 요청 예시

```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
        }
      ]
    }
  ]
}'
```

## **응답 예시**

### 정상 응답

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

### 실패 응답

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

#### 40402 TOO\_MANY\_EVENTS

이벤트 수가 100개를 초과하거나, 이벤트 아이템 수가 100개를 초과한 경우입니다.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dfinery.ai/api-guide/api/import-api/event-api/post.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.