# 커스텀 데이터 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>