프로젝트 목록 조회 API

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

• API 권한이 연결된 멤버가 속한 팀의 프로젝트 조회 권한 범위로 결과를 반환합니다.

• 프로젝트에 연결된 계약서, 영업문서, 세금계산서, 커스텀테이블 데이터는 각 목록 조회 API의 dealUuids 파라미터로 조회할 수 있습니다.

• updatedAtAfter 파라미터로 마지막 동기화 이후 변경된 데이터만 조회할 수 있습니다. 프로젝트의 updatedAt은 프로젝트 정보와 별도 컬럼 값이 변경될 때 갱신되며, 연결된 일정·재무정보·계약서·영업문서의 변경은 각 데이터의 updatedAt으로 추적해 주세요.

GET kit-api/v1/deals

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

Example

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

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

Response

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

{
  "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": "[e-mail]" }], // 담당자
        "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" // 변경일
      }
    ]
  }
}

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

Error Codes

Status Code	Error Code	Description
400	INVALID_CUSTOMER_CUSTOM_KEY	규칙을 벗어난 customKey인 경우