개인화 데이터

1. 개요

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

---

2. 기본 정보

• Method: POST

• URL: https://api.groobee.io/personalizations

• 인증 방식: [설정 > 사이트]에서 발급 받은 API Key (Header)

동작 방식 (Upsert)

• 전화번호(phoneNumber)를 고유 식별값(Unique Key)으로 사용합니다.

• 전화번호가 존재하지 않는 경우: 신규 데이터로 저장(Insert)됩니다.

• 전화번호가 이미 존재하는 경우: 해당 회원의 memberId와 properties 정보가 요청한 데이터로 갱신(Update)됩니다.

---

3. 요청 (Request)

요청 헤더 (Header)

이름	설명	필수	비고
x-api-key	API 인증 키	O	예: x-api-key: {YOUR_API_KEY}
Content-Type	콘텐츠 타입	O	application/json

요청 본문 (Body)

• 데이터 구조: JSON Array (List) 형태

• 제약 사항: 한 번 요청 시 최대 1,000행(Row)까지 전송 가능 (초과 시 오류 반환)

이름	타입	설명	필수	비고
memberId	String	회원 ID	O
phoneNumber	String	회원 전화번호	O	구분자(-)만 허용 저장 시 암호화 처리
properties	Map	개인화 데이터	O	[설정 > 개인화 변수 설정]에 등록된 개인화 키와 해당되는 개인화 데이터 저장 시 암호화 처리

갱신 시 기존 데이터는 삭제되고, 요청한 데이터로 전체 교체(Replace)됩니다.

---

4. 예제 (Example)

요청 (Request)

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를 통해 확인해야 합니다.

성공 시

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

실패 시

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

응답 필드 설명

항목	타입	필수	반복
httpStatus.code	String	Y	N
httpStatus.reasonPhrase	String	Y	N
processCode	String	Y	N
processValue	Object	Y	N

---

6. 결과 코드 표 (Result Codes)

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

---

7. 주의사항

데이터 덮어쓰기 정책

• 기존에 저장된 전화번호로 데이터가 수정될 경우, properties 필드는 병합(Merge)되지 않고 전체 교체(Replace)됩니다.

• 예: 기존에 {A:1, B:2}가 저장되어 있을 때, {A:3}만 보내면 결과는 {A:3}이 됩니다. (B값 삭제됨)

전화번호 중복 처리

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