# 커스텀 데이터 v2.0.1

## **연동 방식**

https 프로토콜을 이용한 Rest API

***

## **필수 값**

| 이름      | 내용                     |
| ------- | ---------------------- |
| API Key | 설정 페이지에서 발급한 API Key 값 |

***

## **요청 주소**

[https://api.groobee.io](https://api.groobee.io/)

***

## **공통 사항**

### **요청 방법**

Rest API 요청 시 Header에 x-api-key 키로 API Key를 값으로 포함해야 합니다.

```
curl --location --request GET 'https://api.groobee.io/<요청주소>' \
--header 'x-api-key: <발급 받은 API Key 값>'
```

* **API key 확인 방법**
  * <https://app.groobee.io/> 접속하여 계정 로그인
  * [설정 > 사이트 > 사이트 설정 > Key 관리](https://app.groobee.io/setting/main)에서 key 생성 후 확인 가능

### **응답 결과**

JSON으로 응답하며 형태는 아래를 참고해 주세요.

```
{
    "httpStatus": {
        "code": <http status code>,
        "reasonPhrase": <http status 내용>
    },
    "processCode": <결과 코드>,
    "processValue": <요청한 엔드포인트의 응답값>
}
```

### **processCode 코드 값**

| 코드 값  | 설명                              |
| ----- | ------------------------------- |
| 0     | 전체 성공                           |
| 1     | 부분 성공                           |
| -1000 | 실패 - 요청 시 Header에 x-api-key 미존재 |
| -1001 | 실패 - 고객사 미존재                    |
| -1002 | 실패 - 고객사 미승인 상태(승인 필요)          |
| -1003 | 실패 - 고객사 계약기간 만료                |
| -1004 | 실패 - 데이터 요청 수 초과                |
| -1005 | 실패 - 진행 중인 프로세스 있음              |
| -1009 | 실패 - 해당 데이터는 30분 이후 삭제 요청       |
| -1010 | 실패 - 데이터 삭제 에러                  |
| -9997 | 실패 - 데이터가 올바르지 않습니다.            |
| -9998 | 실패 - http 관련 에러                 |
| -9999 | 실패 - 요청 API 서버 에러               |

***

### **데이터 양식**

{% hint style="warning" %}
커스텀 데이터는 문자열, 숫자, 날짜 양식의 데이터 타입을 제공하며 아래는 공통 포맷에 대한 가이드 입니다.

날짜는 반드시 YYYY-MM-DD 포맷으로 등록해야 합니다.
{% endhint %}

**문자열**

```
"memberId" : {
    "customDataKey" : "GOLD"
}
```

**숫자**

```
"memberId" : {
    "customDataKey1" : 34,
    "customDataKey2" : "12" // ""를 추가하여도 정상적으로 등록됨
}
```

**날짜**

```
"memberId" : {
    "customDataKey" : "2022-12-30" // YYYY-MM-DD
}
```

***

## **엔드 포인트**

### **커스텀 데이터 조회**

커스텀 데이터를 조회하는 API

* **요청 형태 공통** : 최초 조회 이후 다음 페이지 조회를 위한 nextPageSeq 를 제공합니다. (한 페이지 조회 수: 1000 개)

```
/v2/custom?seq=<nextPageSeq값>
```

* **전체 요청 형태**

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| GET    | /v2/custom | JSON     |

* **단일 요청 형태**

| Method | URI                          | 요청/응답 형식 |
| ------ | ---------------------------- | -------- |
| GET    | /v2/custom?memberId=<멤버아이디값> | JSON     |

* **공통 응답 데이터**

```
{
    "httpStatus": {
        "code": <http status code>, 
        "reasonPhrase": <http status 내용> 
    }, 
    "processCode": <성공여부>, 
    "processValue": { 
        "nextPageSeq": <다음 페이지 조회 seq 값>, 
        "dataList": [ 
            { 
                "memberId": <멤버아이디>, 
                "customDataKey": <커스텀 데이터 키>, 
                "customDataValue": <커스텀 데이터 값> 
            }, 
            ... 
        ] 
    } 
} 
```

### **커스텀 데이터 등록**

커스텀 데이터를 등록하는 API

{% hint style="warning" %}
※ 등록 요청 데이터가 null일 경우 해당 데이터를 제거 후 전송할 것을 권장합니다.&#x20;

그루비 내부에서 null 데이터는 다음과 같이 처리됩니다.

* 문자열(String) 타입 : 그루비 내부 변환 작업 시 빈 값으로 처리
* 날짜(Date) 또는 숫자(Int) 타입 : F02 양식 불일치 코드 리턴

이미 등록되어 있는 데이터에 동일한 멤버아이디, 커스텀 데이터 키로 추가 등록 요청을 하면 업데이트 처리됩니다.
{% endhint %}

* **요청 형태 및 데이터** : 등록할 커스텀 데이터 정보들을 배열로 요청 합니다. (1회 시도 멤버아이디 값 기준으로 최대 1000개)

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| POST   | /v2/custom | JSON     |

```
{
    <멤버아이디값> : {
        <커스텀 데이터 키>: <커스텀 데이터 값>, 
        ...
    },
    ...
}          
```

<br>

* **응답 데이터**

"processCode" : 1(부분 성공)

{% hint style="danger" %}
커스텀 데이터 키 미등록, 데이터 양식 불 일치의 이유로 부분적으로 실패가 존재할 수 있습니다.
{% endhint %}

```
{
     "httpStatus": {
         "code": <http status code>,
         "reasonPhrase": <http status 내용>
     },
     "processCode": <성공여부>,
     "processValue": [
         {
             "memberId" : <등록 실패한 멤버아이디 값>,
             "failKey" : <등록 실패한 커스텀 데이터 키>,
             "failValue" : <등록 실패한 커스텀 데이터 값>,
             "failCode" : <등록 실패 코드>
         },
         ...(등록 요청 중 실패한 커스텀 데이터 정보)
     ]
 
}
```

* **등록 실패 코드**

| 코드 값 | 설명             |
| ---- | -------------- |
| F01  | 커스텀 데이터 키 미등록  |
| F02  | 커스텀 데이터 양식 불일치 |

### **커스텀 데이터 변경**

* **요청 형태 및 데이터** : 변경할 커스텀 데이터 정보들을 오브젝트로 요청 합니다. (1회 시도 멤버아이디 값 기준으로 최대 1000개)

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| PUT    | /v2/custom | JSON     |

```
 {
    <멤버아이디값> : {
         <커스텀 데이터 키>: <커스텀 데이터 값>,
         ... 
    },
    ...
 } 
```

<br>

* **응답 데이터**

"processCode" : 1(부분 성공)

{% hint style="danger" %}
커스텀 데이터 키 미등록, 데이터 양식 불 일치의 이유로 부분적으로 실패가 존재할 수 있습니다.
{% endhint %}

```
{
     "httpStatus": {
         "code": <http status code>,
         "reasonPhrase": <http status 내용>
     },
     "processCode": <성공여부>,
     "processValue": [
         {
             "memberId" : <변경 실패한 멤버아이디 값>
             "failKey" : <변경 실패한 커스텀 데이터 키>
             "failValue" : <변경 실패한 커스텀 데이터 값>,
             "failCode" : <변경 실패 코드>
         },
         ...(변경 요청 중 실패한 커스텀 데이터 정보)
     ]
}
```

* **변경 실패 코드**

| 코드 값 | 설명             |
| ---- | -------------- |
| F01  | 커스텀 데이터 키 미등록  |
| F02  | 커스텀 데이터 양식 불일치 |

### **커스텀 데이터 삭제**

커스텀 데이터를 삭제하는 API

{% hint style="danger" %}
삭제 시도 시 데이터 삭제 실패로 -1009 또는 -1010 에러가 발생 할 수 있습니다.&#x20;

이 경우에는 30 분 후에 삭제 재시도가 필요합니다.
{% endhint %}

* 복수 요청 형태 및 데이터 : 삭제할 멤버 아이디 값들을 배열로 요청 합니다. (1 회 시도 최대 1000 개)

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| DELETE | /v2/custom | JSON     |

```
[
    <삭제할 멤버아이디 값>,
    ... 
]
```

<br>

* 단일 요청 형태 및 데이터 (단일 멤버아이디의 삭제하고자 하는 일부 커스텀 데이터 키 기준) :\
  삭제할 커스텀 데이터 정보들을 오브젝트로 요청 합니다. (1회 시도 멤버아이디 값 기준으로 최대 1000개)

| Method | URI                         | 요청/응답 형식 |
| ------ | --------------------------- | -------- |
| DELETE | /v2/custom/data-format-name | JSON     |

```
{
     <삭제할 멤버아이디 값> : [
         <삭제할 커스텀 데이터 키>,
         ...
     ],
     ...
}
```

* 공통 응답 데이터

```
{
    "httpStatus": {
        "code": <http status code>,
        "reasonPhrase": <http status 내용> 
    },
    "processCode": <성공여부>,                    
    "processValue": <삭제된 데이터 수> 
}
```

<br>


---

# 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/custom-data/v2.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.