계약서 진행 단계 통합 API — step 파라미터로 OPEN / FILL / SIGN 처리

계약서 진행 단계 통합 API

open, fill, sign 세 단계를 step 파라미터 하나로 처리합니다.

항목	값
메서드	`POST`
경로	`/ai/business/contract/process`
Content-Type	`multipart/form-data`

step 별 요청

step=OPEN — 계약서 열람

진행 중인 계약 없으면 자동 생성 후 OPENED 처리합니다.

POST /ai/business/contract/process?memberId=biz_user_001&step=OPEN HTTP/1.1
Host: api.glowb.com

step=FILL — 기업 정보 입력

계약서에 기재할 기업 정보를 입력합니다. data 파트에 JSON 문자열을 담아 전송합니다.

data 파트의 Content-Type 은 application/json 또는 application/octet-stream 어느 쪽이든 허용됩니다. 서버가 String으로 받아 ObjectMapper로 직접 파싱하므로 클라이언트 multipart 라이브러리에 의존하지 않습니다.

POST /ai/business/contract/process?memberId=biz_user_001&step=FILL HTTP/1.1
Host: api.glowb.com
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="data"
Content-Type: application/json

{
  "businessName": "ABC주식회사",
  "license": "123-45-67890",
  "address": "서울시 중구 청계천로 40",
  "representative": "홍길동"
}
------Boundary--

step=SIGN — 인감 업로드 = 서명

인감 이미지를 업로드하면 계약서 PDF를 생성하고 SIGNED 처리합니다. 서명 직후에는 어드민 검수 대기 상태(contractSignStatus = PENDING)로 진입하며, 어드민이 검수를 승인한 시점에야 캠페인 생성이 가능해집니다.

POST /ai/business/contract/process?memberId=biz_user_001&step=SIGN HTTP/1.1
Host: api.glowb.com
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="stamp"; filename="stamp.png"
Content-Type: image/png

[인감 이미지 바이너리]
------Boundary--

인감 재사용: stamp 파일을 생략하면 TB_BUSINESS.stamp_image_url에 저장된 기존 인감을 자동으로 재사용합니다. 재계약 시 재업로드 불필요합니다.

누끼(투명 배경) 권장: PNG 형식의 인감 이미지를 업로드하면 계약서 PDF에 깔끔하게 합성됩니다.

cURL 예시

curl -X POST \
  "https://api.glowb.com/ai/business/contract/process?memberId=biz_user_001&step=OPEN"

curl -X POST \
  "https://api.glowb.com/ai/business/contract/process?memberId=biz_user_001&step=FILL" \
  -F 'data={"businessName":"ABC주식회사","license":"123-45-67890","address":"서울시 중구...","representative":"홍길동"};type=application/json'

curl -X POST \
  "https://api.glowb.com/ai/business/contract/process?memberId=biz_user_001&step=SIGN" \
  -F "stamp=@/path/to/stamp.png"

응답 (200 OK)

모든 step 공통 응답 형식입니다.

{
  "status": 200,
  "code": null,
  "message": "계약이 완료되었습니다.",
  "data": {
    "contractStatus": "SIGNED",
    "contractSignStatus": "PENDING",
    "approvalStatus": "PENDING_APPROVAL",
    "stampImageUrl": "https://glowb-input.s3.ap-southeast-1.amazonaws.com/contract/business/stamp/...",
    "finalPdfUrl": "https://glowb-input.s3.ap-southeast-1.amazonaws.com/contract/business/pdf/...",
    "sentAt": null,
    "openedAt": "2026-04-27T10:00:00",
    "filledAt": "2026-04-27T10:05:00",
    "signedAt": "2026-04-27T10:06:00"
  }
}

step별 상태 변화

step	선행 조건	contractStatus 변화	contractSignStatus 변화
`OPEN`	없음 (레코드 없으면 자동 생성)	→ `OPENED`	변화 없음
`FILL`	OPENED 또는 FILLED 상태	→ `FILLED`	변화 없음
`SIGN`	FILLED 상태	→ `SIGNED`	→ `PENDING` (검수 대기)

step=SIGN만으로는 캠페인 생성이 풀리지 않습니다. 어드민이 PATCH /ai/admin/business-contracts/{businessId}/review?decision=APPROVED 를 호출해야 contractSignStatus가 SIGNED로 전환됩니다. 거절 시 NONE으로 떨어지고 재발송이 필요합니다.

에러 응답

케이스	코드	설명
step 값 오류	`BIZ_C009`	`OPEN / FILL / SIGN` 중 하나여야 함
FILL인데 data 없음	`BIZ_C009`	data 파라미터 필수
FILL인데 OPENED 아님	`BIZ_C009`	open 먼저 호출 필요
SIGN인데 FILLED 아님	`BIZ_C009`	fill 먼저 호출 필요
SIGN인데 stamp 없고 기존 인감도 없음	`BIZ_C008`	인감 이미지 필요
기업 정보 없음	`BIZ_C007`	등록된 기업 계정이 아님

POST /ai/business/contract/process

On this page