# 계약서/전자서명 목록 조회 API

계약서 목록을 조회할 수 있는 API입니다.

<br>

## `GET` kit-api/v1/contracts

Method: GET\
Endpoint: kit-api/v1/contracts

<br>

## Example

```
...kit-api/v1/contracts?limit=10&offset=0
```

<br>

## Request Query

| Key                | Description                                             | Required |
| ------------------ | ------------------------------------------------------- | -------- |
| customerCustomKeys | 해당 customKeys 속성을 가진 고객들과 연결된 계약서 목록을 조회                | no       |
| customerIds        | 해당 id 속성을 가진 고객들과 연결된 계약서 목록을 조회                        | no       |
| title              | 제목으로 계약서 조회 (string)                                    | no       |
| customer           | 고객이름으로 계약서 조회 (string)                                  | no       |
| participantName    | 서명참여자 이름으로 계약서 조회 (string)                              | no       |
| participantEmail   | 서명참여자 이메일로 계약서 조회 (string)                              | no       |
| participantPhone   | 서명참여자 전화번호로 계약서 조회 (string)                             | no       |
| type               | 해당 타입에 해당하는 계약서 조회 (NEW, RENEWAL)                       | no       |
| status             | 계약 체결 여부에 따른 계약서 조회 (CREATED, CONCLUDED)                | no       |
| tagIds             | 해당 tagIds 속성을 가진 태그들과 연결된 계약서 목록을 조회                    | no       |
| signature          | 전자서명 존재 여부에 따라 계약서 조회 (included, excluded)              | no       |
| periodStatus       | 기간 상태에 해당하는 계약서 조회 (before, ongoing, after)             | no       |
| createdAtAfter     | 해당 날짜 이후 생성된 계약서 조회 (date)                              | no       |
| createdAtBefore    | 해당 날짜 이전 생성된 계약서 조회 (date)                              | no       |
| endDateAfter       | 종료일이 해당 날짜 이후인 계약서 조회 (date)                            | no       |
| endDateBefore      | 종료일이 해당 날짜 이전인 계약서 조회 (date)                            | no       |
| limit              | 한 번에 몇 개의 값을 받아올지 의미하는 숫자 (max 100)                     | no       |
| offset             | offset 개수 이후만큼의 limit 개수를 조회                            | no       |
| hasNoCustomer      | 고객과 연결되지 않은 목록만 조회 (값: true)                            | no       |
| slugColumnKeys     | 검색할 칼럼을 특정하기 위한 slug값 (string)                          | no       |
| slugColumnValues   | 검색할 칼럼에 해당하는 검색값으로 slugColumnKeys 값이 존재하면 필수 (string)   | no       |
| orderKey           | 정렬 옵션 (값: endDate, startDate, createdAt, concludedDate) | no       |
| orderValue         | 정렬의 내림차순/올림차순 여부 (값: ASC, DESC)                         | no       |

<br>

## Response

\*계약서 파일은 계약서 상세 조회 API를 이용해 주세요.

* file, concludedFile의 url은 외부에서 사용할 수 없습니다. (프릭스 서비스에서만 열람이 가능합니다)
* 계약서 파일을 사용(파일을 외부로 다운로드 등)하기 위해서는 계약서 상세 조회 API를 사용해야 합니다.

```json
{
  "ok": true, // api 성공
  "data": {
    "total": 1,
    "contracts": [
      {
        // 계약서의 파일은 계약서 상세 조회 API에서 조회할 수 있습니다.
        "id": 1,
        "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용합니다)
        "customKey": "a4-k1234", // 커스텀 계약 ID
        "title": "A컴퍼니 MOU", // 계약서 이름
        "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED)
        "type": "NEW", // 신규계약/재계약 여부 (NEW, RENEWAL)
        "createdAt": "2024-07-05T00:00:00.000Z", // 생성일
        "updatedAt": "2024-10-15T00:00:00.000Z", // 변경일
        "contractDate": {
          "startDate": "2024-10-01T00:00:00.000Z", // 시작일
          "endDate": null, // 종료일
          "concludedDate": null // 체결일
        },
        "signature": {
          // 전자서명 정보
          "id": 1,
          "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별값
          "title": "A컴퍼니 MOU 전자서명", // 전자서명 제목
          "expiredDate": "2024-10-15T00:00:00.000Z", // 전자서명 만료일
          "status": "WAITING", // 전자서명 상태 (CREATED, WAITING, DONE, CANCELED)
          "createdAt": "2024-07-15T00:00:00.000Z", // 생성일
          "updatedAt": "2024-10-15T00:00:00.000Z", // 변경일
          "participants": [], // 전자서명 참여자 정보 (uuid, name, status, auth, send, email, phone, role, language)
          "objects": [
            {
              // 전자서명 입력값 정보
              "id": 1,
              "contents": "서울시 강남구 선릉로 551", // 내용
              "type": "TEXT", // 종류 (TEXT, SIGNATURE, CHECKBOX)
              "category": "DEFAULT", // 유형 (DEFAULT, INPUT)
              "name": "주소", // 이름
              "description": "상세 주소를 입력해 주세요." // 설명
            }
          ]
        },
        "columnItems": [ // 별도 컬럼
          {
            value: "ABCDE",
            slug: "service-key",
            name: "자체 구분값"
          }
        ]
      }
    ]
  }
}
```

<br>

```json
{
  "ok": false, // api 실패
  "message": "error message", // Error가 존재하면 message(string)로 전달
  "errorCode": "ERROR_CODE"
}
```

<br>

| Status Code | Error Code                                | Description                                          |
| ----------- | ----------------------------------------- | ---------------------------------------------------- |
| 400         | INVALID\_CUSTOMER\_CUSTOM\_KEY            | 규칙을 벗어난 customKey인 경우                                |
| 400         | SLUG\_COLUMN\_KEYS\_AND\_VALUES\_MISMATCH | slugColumnKeys 값과 slugColumnValues 값 중에서 하나만 존재하는 경우 |

<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://api-kit.prix.im/signature/search.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.