# 커스텀 데이터 v1

## **연동 방식**

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 관리](/old-admin/settings/site.md)에서 key 생성 후 확인 가능

<br>

### **응답 결과**

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

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

### **processCode 코드값**

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

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

* 레거시 데이터는 문자열, 숫자, 날짜 양식의 데이터 타입을 제공하며 아래는 공통 포맷에 대한 가이드 입니다.
* 날짜는 반드시 YYYY-MM-DD 포맷으로 등록해야 합니다.

**문자열**

```
"memberId" : {
    "legacyDataKey" : "GOLD"
}
```

**숫자**

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

**날짜**

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

***

## **엔드 포인트**

### **레거시 데이터 조회**

레거시 데이터를 조회하는 API

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

```
/v1/legacy?seq=<nextPageSeq 값>
```

* **전체 요청 형태**

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| GET    | /v1/legacy | JSON     |

* **단일 요청 형태**

<table><thead><tr><th width="141.5341796875">Method</th><th>URI</th><th>요청/응답 형식</th></tr></thead><tbody><tr><td>GET</td><td>/v1/legacy?memberId=&#x3C;멤버아이디값></td><td>JSON</td></tr></tbody></table>

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

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

### **레거시 데이터 등록**

레거시 데이터를 등록하는 API

{% hint style="info" %}
이미 등록되어 있는 데이터에 동일한 멤버아이디, 레거시 데이터 키로 추가 등록 요청을 하게되면 update 처리됩니다.<br>
{% endhint %}

* 요청 형태 및 데이터 : 등록할 레거시 데이터 정보들을 배열로 요청 합니다. (1 회 시도 최대 1,000 개)

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| POST   | /v1/legacy | JSON     |

```
{
    <멤버아이디값> : {
        <레거시 데이터 키>: <레거시 데이터 값>, 
        ...
    },
    ...
}          

```

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

### **레거시 데이터 변경**<br>

* **요청 형태 및 데이터** : 변경할 레거시 데이터 정보들을 배열로 요청 합다. (1 회 시도 최대 1000 개)

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| PUT    | /v1/legacy | JSON     |

```
 {
    <변경 하고자 하는 멤버아이디값> : {
         <레거시 데이터 키>: <레거시 데이터 값>,
         ... 
    },
    ...
 } 
```

<br>

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

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

### **레거시 데이터 삭제**

레거시 데이터를 삭제하는 API

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

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

* 복수 요청 형태 및 데이터

| Method | URI        | 요청/응답 형식 |
| ------ | ---------- | -------- |
| DELETE | /v1/legacy | JSON     |

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

* 단일 요청 형태 및 데이터 (단일 멤버아이디의 삭제하고자 하는 일부 레거시 데이터 키 기준)

| Method | URI                         | 요청/응답 형식 |
| ------ | --------------------------- | -------- |
| DELETE | /v1/legacy/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/v1.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.