> 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/platform/search-deal.md).

# 프로젝트 목록 조회 API

프로젝트 목록을 조회할 수 있는 API를 제공합니다.

프로젝트 목록을 조회할 수 있는 API입니다.

* API 권한이 연결된 멤버가 속한 팀의 프로젝트 조회 권한 범위로 결과를 반환합니다.
* 프로젝트에 연결된 계약서, 영업문서, 세금계산서, 커스텀테이블 데이터는 각 목록 조회 API의 `dealUuids` 파라미터로 조회할 수 있습니다.
* `updatedAtAfter` 파라미터로 마지막 동기화 이후 변경된 데이터만 조회할 수 있습니다. 프로젝트의 `updatedAt`은 프로젝트 정보와 별도 컬럼 값이 변경될 때 갱신되며, 연결된 일정·재무정보·계약서·영업문서의 변경은 각 데이터의 `updatedAt`으로 추적해 주세요.

<br>

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

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

<br>

## Example

```
...kit-api/v1/deals?limit=10&offset=0&status=ACTIVE&updatedAtAfter=2026-08-01T00:00:00.000Z
```

<br>

## Request Query

| Key                | Description                                                 | Required |
| ------------------ | ----------------------------------------------------------- | -------- |
| limit              | 목록 개수 (default 10, max 100)                                 | no       |
| offset             | 스킵할 목록 개수                                                   | no       |
| name               | 프로젝트명으로 조회 (부분 일치)                                          | no       |
| customKeys         | 프로젝트 커스텀 ID 목록으로 조회 (콤마 구분)                                 | no       |
| customerIds        | 해당 id 속성을 가진 고객들과 연결된 프로젝트 조회 (콤마 구분)                       | no       |
| customerCustomKeys | 해당 customKey 속성을 가진 고객들과 연결된 프로젝트 조회 (콤마 구분)                | no       |
| tagIds             | 해당 태그들과 연결된 프로젝트 조회 (콤마 구분)                                 | no       |
| status             | 프로젝트 상태로 조회 (ACTIVE, CANCELED). 미지정 시 삭제된 프로젝트를 제외한 전체      | no       |
| periodStatus       | 기간 상태에 해당하는 프로젝트 조회 (before, ongoing, after)                | no       |
| startDateAfter     | 시작일이 해당 날짜 이후인 프로젝트 조회 (date)                               | no       |
| endDateAfter       | 종료일이 해당 날짜 이후인 프로젝트 조회 (date)                               | no       |
| endDateBefore      | 종료일이 해당 날짜 이전인 프로젝트 조회 (date)                               | no       |
| createdAtAfter     | 해당 날짜 이후 생성된 프로젝트 조회 (date)                                 | no       |
| createdAtBefore    | 해당 날짜 이전 생성된 프로젝트 조회 (date)                                 | no       |
| updatedAtAfter     | 해당 날짜 이후 변경된 프로젝트 조회 (date, 증분 동기화용)                        | no       |
| updatedAtBefore    | 해당 날짜 이전 변경된 프로젝트 조회 (date)                                 | no       |
| orderKey           | 정렬 기준 (값: startDate, endDate, createdAt. default createdAt) | no       |
| orderValue         | 정렬 방향 (값: ASC, DESC. default DESC)                          | no       |

<br>

## Response

\*재무정보는 프로젝트 상세 조회 API에서 조회할 수 있습니다.

```json
{
  "ok": true, // api 성공
  "data": {
    "total": 1,
    "deals": [
      {
        "id": 1,
        "uuid": "38432ad8-a21f-43b3-9912-44295e3ecca1", // 프로젝트 식별값 (상세 조회, 다른 API의 dealUuids 파라미터에 사용)
        "customKey": "P-2026-001", // 프로젝트 커스텀 ID (없으면 null)
        "name": "A사 법률 자문", // 프로젝트명
        "status": "ACTIVE", // 프로젝트 상태 (ACTIVE, CANCELED)
        "memo": "메모", // 프로젝트 메모 (없으면 null)
        "startDate": "2026-01-01T00:00:00.000Z", // 시작일 (없으면 null)
        "endDate": null, // 종료일 (없으면 null)
        "customers": [{ "id": 1, "title": "A컴퍼니", "customKey": "A5-k159402" }], // 연결된 고객
        "managers": [{ "id": 3, "name": "홍길동", "email": "hong@example.com" }], // 담당자
        "tags": [{ "id": 7, "name": "자문" }], // 프로젝트 태그
        "columnItems": [
          // 별도 컬럼 (컬럼 타입별 value: STRING 문자열, NUMBER 숫자, BOOLEAN 불리언, DATE 날짜, TAG [{ id, name }], LOOKUP 문자열)
          { "columnId": 11, "name": "담당 변호사", "slug": "lawyer", "value": "김변호사" },
          { "columnId": 12, "name": "분야", "slug": "field", "value": [{ "id": 5, "name": "기업법무" }] }
        ],
        "createdAt": "2026-01-01T00:00:00.000Z", // 생성일
        "updatedAt": "2026-08-01T00:00:00.000Z" // 변경일
      }
    ]
  }
}
```

<br>

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

<br>

## Error Codes

| Status Code | Error Code                     | Description           |
| ----------- | ------------------------------ | --------------------- |
| 400         | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 |

<br>