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

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

GET kit-api/v1/contracts

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

Example

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

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

Response

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

• file, concludedFile의 url은 외부에서 사용할 수 없습니다. (프릭스 서비스에서만 열람이 가능합니다)

• 계약서 파일을 사용(파일을 외부로 다운로드 등)하기 위해서는 계약서 상세 조회 API를 사용해야 합니다.

{
  "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: "자체 구분값"
          }
        ]
      }
    ]
  }
}

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

Status Code	Error Code	Description
400	INVALID_CUSTOMER_CUSTOM_KEY	규칙을 벗어난 customKey인 경우
400	SLUG_COLUMN_KEYS_AND_VALUES_MISMATCH	slugColumnKeys 값과 slugColumnValues 값 중에서 하나만 존재하는 경우