# 개인화 데이터

## **1. 개요**

오프사이트 캠페인(SMS, 카카오 브랜드 메시지) 발송 대상 회원의 개인화 데이터를 그루비에 전송하는 API입니다.

***

## **2. 기본 정보**

* **Method:** `POST`
* **URL:** `https://api.groobee.io/personalizations`
* **인증 방식:** [**\[설정 > 사이트\]**](/new-admin/settings/site.md)에서 발급 받은 API Key (Header)

> **동작 방식 (Upsert)**
>
> * 전화번호(phoneNumber)를 고유 식별값(Unique Key)으로 사용합니다.
> * 전화번호가 존재하지 않는 경우: 신규 데이터로 저장(Insert)됩니다.
> * 전화번호가 이미 존재하는 경우: 해당 회원의 `memberId`와 `properties` 정보가 요청한 데이터로 갱신(Update)됩니다.

***

## **3. 요청 (Request)**

### **요청 헤더 (Header)**

<table><thead><tr><th>이름</th><th>설명</th><th width="100">필수</th><th>비고</th></tr></thead><tbody><tr><td>x-api-key</td><td>API 인증 키</td><td>O</td><td>예: x-api-key: {YOUR_API_KEY}</td></tr><tr><td>Content-Type</td><td>콘텐츠 타입</td><td>O</td><td>application/json</td></tr></tbody></table>

### **요청 본문 (Body)**

* **데이터 구조:** JSON Array (List) 형태
* **제약 사항:** 한 번 요청 시 최대 1,000행(Row)까지 전송 가능 (초과 시 오류 반환)

<table><thead><tr><th>이름</th><th width="100">타입</th><th>설명</th><th width="100">필수</th><th>비고</th></tr></thead><tbody><tr><td>memberId</td><td>String</td><td>회원 ID</td><td>O</td><td></td></tr><tr><td>phoneNumber</td><td>String</td><td>회원 전화번호</td><td>O</td><td><ul><li>구분자(<code>-</code>)만 허용</li><li>저장 시 암호화 처리</li></ul></td></tr><tr><td>properties</td><td>Map</td><td>개인화 데이터</td><td>O</td><td><ul><li><a href="/pages/qP7rW2zyEIzB9bHmp5bx"><mark style="color:$primary;"><strong>[설정 > 개인화 변수 설정]</strong></mark></a>에 등록된 <strong>개인화 키</strong>와 해당되는 <strong>개인화 데이터</strong></li><li>저장 시 암호화 처리</li></ul></td></tr></tbody></table>

{% hint style="warning" %}
갱신 시 기존 데이터는 삭제되고, 요청한 데이터로 전체 교체(Replace)됩니다.
{% endhint %}

***

## **4. 예제 (Example)**

### **요청 (Request)**

```json
curl --location --request POST 'https://api.groobee.io/personalizations' \
--header 'x-api-key : ${x-api-key}'
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "memberId" : "groobee1",
        "phoneNumber" : "010-0000-2222",
        "properties" : {
            "key1" : "그루비1",
            "key2" : "value2",
            "key3" : "value3"
        }
    },
    {
        "memberId" : "groobee2",
        "phoneNumber" : "010-3333-4444",
        "properties" : {
            "key1" : "그루비2",
            "key2" : "value5",
            "key3" : "value6"
        }
    }
]'
```

***

## **5. 응답 (Response)**

**HTTP Status Code:** 항상 `200`을 반환하며, 실제 성공/실패 여부는 Body의 `processCode`를 통해 확인해야 합니다.

### **성공 시**

```json
{
    "httpStatus": {
        "code": "200",
        "reasonPhrase": "OK"
    },
    "processCode": "0",
    "processValue": true
}
```

### **실패 시**

```json
{
    "httpStatus": {
        "code": "400",
        "reasonPhrase": "Bad Request"
    },
    "processCode": "-9998",
    "processValue": {
        "message": "전송데이터에 오류가 있습니다",
        "errors": [
            "properties: 널이어서는 안됩니다"
        ]
    }
}
```

### **응답 필드 설명**

<table><thead><tr><th>항목</th><th width="100">타입</th><th width="100">필수</th><th width="100">반복</th></tr></thead><tbody><tr><td>httpStatus.code</td><td>String</td><td>Y</td><td>N</td></tr><tr><td>httpStatus.reasonPhrase</td><td>String</td><td>Y</td><td>N</td></tr><tr><td>processCode</td><td>String</td><td>Y</td><td>N</td></tr><tr><td>processValue</td><td>Object</td><td>Y</td><td>N</td></tr></tbody></table>

***

## **6. 결과 코드 표 (Result Codes)**

<table><thead><tr><th width="100">코드 값</th><th width="100">상태</th><th>설명</th></tr></thead><tbody><tr><td>0</td><td>성공</td><td>정상 처리</td></tr><tr><td>-1000</td><td>실패</td><td>요청 시 Header에 x-api-key 미존재</td></tr><tr><td>-1001</td><td>실패</td><td>고객사 미존재</td></tr><tr><td>-1002</td><td>실패</td><td>고객사 미승인 상태 (승인 필요)</td></tr><tr><td>-1003</td><td>실패</td><td>고객사 계약기간 만료</td></tr><tr><td>-1004</td><td>실패</td><td>데이터 초과</td></tr><tr><td>-1006</td><td>실패</td><td>회원 ID가 올바르지 않습니다.</td></tr><tr><td>-1007</td><td>실패</td><td>회원 전화번호가 올바르지 않습니다.</td></tr><tr><td>-9997</td><td>실패</td><td>데이터가 올바르지 않습니다.</td></tr><tr><td>-9998</td><td>실패</td><td>http 관련 에러</td></tr><tr><td>-9999</td><td>실패</td><td>요청 API 서버 에러</td></tr></tbody></table>

***

## **7. 주의사항**

### **데이터 덮어쓰기 정책**

* 기존에 저장된 전화번호로 데이터가 수정될 경우, `properties` 필드는 병합(Merge)되지 않고 전체 교체(Replace)됩니다.
* 예: 기존에 `{A:1, B:2}`가 저장되어 있을 때, `{A:3}`만 보내면 결과는 `{A:3}`이 됩니다. (B값 삭제됨)

### **전화번호 중복 처리**

* 본 API는 `전화번호`를 기준으로 식별합니다. 만약 서로 다른 `memberId`가 동일한 전화번호를 전송할 경우, 마지막에 처리된 요청의 `memberId`와 데이터로 최종 갱신됩니다.


---

# Agent Instructions: 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.groobee.ai/developer-guide/api-guide/personalization.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.