> For the complete documentation index, see [llms.txt](https://api-kit.prix.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-kit.prix.im/signature/search.md).

# 계약서/전자서명 목록 조회 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>