DocsReferencesChangelogCommunity
Docs

진행 중인 문서 수정하기

문서 내용 수정

진행 중인 서명 요청·열람 요청 문서의 내용을 API로 수정할 수 있는 기능입니다.
수정 시작 API로 문서를 "수정 중" 상태로 전환한 뒤, 수정 중 데이터를 조회하고, 필요한 데이터를 PATCH 로 변경한 다음, 수정 완료 또는 수정 취소 를 호출합니다.

📘

시작하기 전에 꼭 이해하기

이 기능을 처음 연동하실 때 아래 두 가지 개념을 먼저 이해하시면 훨씬 수월합니다.

① "수정 중" 은 임시저장 상태입니다.
수정 시작부터 수정 완료 전까지의 모든 변경은 임시 저장본에만 반영됩니다. 원본 문서와 문서 목록·검색 결과는 수정 완료를 호출하기 전까지 그대로입니다. 즉, 수정 완료를 해야 실제 문서에 반영되고, 수정 취소를 하면 없던 일이 됩니다.

② 목록(배열) 데이터는 "전체 교체" 방식입니다.
참여자·입력란·첨부파일·참조자처럼 여러 개가 들어가는 데이터는, 요청에 포함하는 순간 보낸 목록이 전체 기준이 됩니다. 그래서 일부만 바꾸더라도 유지할 항목까지 함께 보내야 하고, 제외된 항목은 삭제됩니다.
(자세한 규칙은 아래 3번에서 설명되어 있습니다.)

🚧

유의사항

  • 수정 시작 후 완료 또는 취소 전까지 기존 참여 링크는 일시적으로 비활성화됩니다.
  • 수정 완료 전까지 문서 목록 조회와 검색 결과는 수정 전 원본 데이터를 기준으로 표시됩니다.
  • 이미 서명 또는 열람이 완료된 참여자의 데이터는 수정할 수 없습니다.
  • 링크서명 문서는 내용 수정을 지원하지 않습니다.
  • PATCH 요청은 한 번에 여러 데이터를 함께 보낼 수 있습니다. 다만 배열형 데이터는 요청에 포함한 배열이 전체 기준이므로, 유지할 항목도 함께 보내야 합니다.

전체 흐름

전체 과정은 아래와 같습니다. 파란색은 수정을 진행하는 API 호출 단계이고, 마지막에 변경을 확정(완료) 하거나 폐기(취소) 하는 것으로 끝납니다.

  1. POST /documents/{documentId}/start-modification — 문서를 수정 중 상태로 전환합니다.
  2. GET /documents/{documentId}/modification — 수정 중 데이터를 조회합니다.
  3. PATCH /documents/{documentId}/modification — 필요한 데이터를 변경합니다.
  4. POST /documents/{documentId}/complete-modification — 변경을 확정합니다.
  5. POST /documents/{documentId}/cancel-modification — 변경을 폐기합니다.

1. 내용 수정 시작하기

먼저 문서를 수정 중 상태로 전환합니다. 수정이 시작되면 서명자 또는 열람자에게 발송된 기존 참여 링크는 일시적으로 비활성화됩니다.

curl -X POST 'https://api.modusign.co.kr/documents/{DOCUMENT_ID}/start-modification' \
  -H 'Authorization: Basic {인코딩된 API-KEY}'
🌟

주의사항

링크서명 문서는 내용 수정을 지원하지 않습니다.

2. 수정 중 데이터 조회하기

수정 중 상태의 문서 데이터는 다음 API로 조회합니다. PATCH에서 기존 항목을 수정하려면 이 응답에 포함된 id 를 사용합니다.

curl -X GET 'https://api.modusign.co.kr/documents/{DOCUMENT_ID}/modification' \
  -H 'Authorization: Basic {인코딩된 API-KEY}'

응답에는 제목, 문서 파일, 참여자, 요청자 입력란, 요청자 첨부파일, 참조자 등이 포함됩니다.

📘

안내사항

수정 중 데이터는 임시 저장본입니다. 문서 목록 조회와 검색 결과는 수정 완료 전까지 수정 전 원본 데이터를 기준으로 표시됩니다.

3. 데이터 변경하기 (PATCH)

PATCH /documents/{documentId}/modification 은 수정할 데이터만 요청 본문에 포함합니다.

데이터 종류별 동작

데이터는 크게 두 종류로 나뉘며, 동작 방식이 다릅니다.

종류대상동작 방식
단일 값title, fileOpenPassword, file, seal보낸 필드만 변경됩니다. (fileOpenPassword 는 null 을 보내면 해제)
목록(배열)participants, requesterInputs, requesterAttachments, carbonCopies요청 본문에 포함하면 배열 전체가 교체됩니다.
🚧

목록(배열) 데이터는 "전체 교체" 입니다 — 가장 주의할 점

배열 데이터(participants 등)는 키를 보내는 순간, 보낸 배열이 전체 기준이 됩니다. 그래서 아래 규칙을 꼭 기억해주세요.

하려는 것방법
기존 항목 유지그 항목의 id 를 배열에 포함
기존 항목 수정그 항목의 id + 바꿀 속성을 함께 포함
새 항목 추가id 없이 포함
기존 항목 삭제배열에서 제외
전체 삭제빈 배열 [] 전송

즉, "1명만 수정" 하려 해도 유지할 나머지 항목까지 배열에 함께 담아야 다른 항목이 사라지지 않습니다.

수정하지 않을 데이터는 요청 본문에서 제외하세요. 예를 들어 제목만 수정할 때는 title 만 보내면 됩니다.

PATCH 요청 본문에는 다음 최상위 키를 사용할 수 있습니다.

{
  "title": "수정할 문서 제목",
  "fileOpenPassword": "완료 문서 비밀번호 또는 null",
  "file": {
    "fileId": "업로드한 파일 ID",
    "token": "업로드한 파일 토큰"
  },
  "participants": [],
  "requesterInputs": [],
  "requesterAttachments": [],
  "carbonCopies": [],
  "seal": {
    "integritySeal": {
      "enabled": true,
      "position": "TOP_RIGHT"
    }
  }
}

제목과 완료 문서 비밀번호 수정하기

문서 제목과 완료 문서 비밀번호는 필요한 필드만 보내면 됩니다.

{
  "title": "수정된 계약서",
  "fileOpenPassword": "1234"
}

설정된 완료 문서 비밀번호를 해제하려면 fileOpenPassword 에 null 을 보냅니다.

{
  "fileOpenPassword": null
}

문서 파일 교체하기

문서 파일을 교체 하려면 먼저 파일 업로드 API 로 파일을 업로드한 뒤, 발급받은 fileId 와 token 을 file 에 전달합니다.

{
  "file": {
    "fileId": "{FILE_ID}",
    "token": "{FILE_TOKEN}"
  }
}
🚧

파일은 반드시 파일 업로드 API를 사용하세요 (base64 미지원)

이 PATCH API는 base64 인라인 파일을 지원하지 않습니다. 파일 교체는 파일 업로드 API 로 먼저 업로드한 뒤 fileId · token 으로 참조하는 방식만 지원합니다.

base64 방식은 인코딩이 어긋나면 오류가 발생하기 쉽고, 데이터 크기도 커져 안정성이 낮습니다. 모두싸인의 파일 관련 기능은 파일 업로드 API를 중심으로 개선되고 있으므로, 앞으로의 호환성과 사용성 측면에서도 파일 업로드 API 사용을 권장드립니다.

참여자 수정하기

participants 는 요청 본문에 포함하면 참여자 목록 전체가 교체됩니다. 기존 참여자를 유지하거나 수정하려면 GET /modification 응답의 참여자 id 를 포함해야 합니다.

기존 참여자 id 를 포함한 항목에서 보내지 않은 속성은 기존 값이 유지됩니다. 예를 들어 name 만 보내면 해당 참여자의 이름만 바뀌고, 참여 수단·순서·입력란 등은 그대로 유지됩니다.

다음 예시는 기존 서명자의 이름만 수정합니다. 수정하지 않는 기존 참여자도 유지하려면 같은 participants 배열에 함께 포함해야 합니다.

{
  "participants": [
    {
      "id": "{SIGNER_ID_TO_UPDATE}",
      "name": "김모두",
      "signingOrder": 1,
      "signingMethod": {
        "type": "EMAIL",
        "value": "[email protected]"
      }
    },
    {
      "id": "{SIGNER_ID_TO_KEEP}",
      "name": "박모두",
      "signingOrder": 2,
      "signingMethod": {
        "type": "KAKAO",
        "value": "01000000000"
      }
    }
  ]
}

위 예시에서 {SIGNER_ID_TO_UPDATE} 참여자는 이름이 김모두 로 변경되고, {SIGNER_ID_TO_KEEP} 참여자는 유지됩니다. {SIGNER_ID_TO_KEEP} 를 배열에서 제외하면 해당 참여자는 삭제됩니다.

다음 예시는 기존 서명자를 수정하면서 새 서명자를 추가합니다.

{
  "participants": [
    {
      "id": "{EXISTING_PARTICIPANT_ID}",
      "name": "김모두",
      "signingOrder": 1,
      "signingMethod": {
        "type": "EMAIL",
        "value": "[email protected]"
      }
    },
    {
      "type": "SIGNER",
      "name": "이모두",
      "signingOrder": 2,
      "signingMethod": {
        "type": "KAKAO",
        "value": "01000000000"
      }
    }
  ]
}
🌟

주의사항

  • 기존 참여자의 type 은 생략할 수 있지만, 신규 참여자는 type 을 반드시 포함해야 합니다.
  • 기존 참여자를 서명자 ↔ 열람자로 바꾸는 변경은 지원하지 않습니다.

기존 참여자 2명 중 1명의 이름만 바꾸고 1명은 유지하려면 다음처럼 보내면 됩니다.

{
  "participants": [
    {
      "id": "{PARTICIPANT_ID_TO_UPDATE}",
      "name": "김모두"
    },
    {
      "id": "{PARTICIPANT_ID_TO_KEEP}"
    }
  ]
}

참여자의 입력란 수정하기

참여자의 입력란을 수정하려면 해당 참여자 항목 안에 fields 를 함께 보냅니다. fields 를 보내지 않으면 기존 입력란은 그대로 유지됩니다.

fields 의 구조는 서명 요청 생성 API의 참여자 입력란 구조와 동일합니다. fields 를 보내면 입력란 배열 전체가 교체되므로, 이미 설정된 입력란을 유지하려면 해당 입력란도 함께 보내야 합니다.

다음 예시는 기존 서명 입력란을 유지하면서 텍스트 입력란을 추가합니다.

{
  "participants": [
    {
      "id": "{EXISTING_PARTICIPANT_ID}",
      "fields": [
        {
          "id": "{EXISTING_FIELD_ID}",
          "type": "SIGNATURE",
          "dataLabel": "서명",
          "required": true,
          "signatureTypes": ["SIGN"],
          "position": { "page": 1, "x": 0.1, "y": 0.3 },
          "size": { "width": 0.2, "height": 0.05 }
        },
        {
          "type": "TEXT",
          "dataLabel": "직책",
          "required": true,
          "position": { "page": 1, "x": 0.2, "y": 0.4 },
          "size": { "width": 0.2, "height": 0.03 },
          "textStyle": { "size": 12, "font": "NOTO_SANS", "align": "LEFT" }
        }
      ]
    }
  ]
}

위 예시에서 {EXISTING_FIELD_ID} 입력란은 유지되고, id 가 없는 직책 입력란은 새로 추가됩니다. 기존 입력란을 fields 배열에서 제외하면 삭제됩니다.

기존 입력란 1개는 유지하고 새 텍스트 입력란 1개를 추가하려면 다음처럼 보내면 됩니다.

{
  "participants": [
    {
      "id": "{EXISTING_PARTICIPANT_ID}",
      "fields": [
        { "id": "{FIELD_ID_TO_KEEP}" },
        {
          "type": "TEXT",
          "dataLabel": "직책",
          "required": true,
          "position": { "page": 1, "x": 0.2, "y": 0.4 },
          "size": { "width": 0.2, "height": 0.03 },
          "textStyle": { "size": 12, "font": "NOTO_SANS", "align": "LEFT" },
          "value": "매니저"
        }
      ]
    }
  ]
}

요청자 입력란 수정하기

requesterInputs 는 요청자 입력란 목록 전체가 교체됩니다. 기존 입력란을 유지하거나 수정하려면 id 를 포함하세요.

다음 예시는 기존 텍스트 입력란의 값을 바꾸고, 새 체크박스 입력란을 추가합니다.

{
  "requesterInputs": [
    {
      "id": "{EXISTING_REQUESTER_INPUT_ID}",
      "type": "TEXT",
      "dataLabel": "계약 금액",
      "position": { "page": 1, "x": 0.2, "y": 0.3 },
      "size": { "width": 0.2, "height": 0.03 },
      "textStyle": { "size": 12, "font": "NOTO_SANS", "align": "LEFT" },
      "value": "1000000"
    },
    {
      "type": "CHECKBOX",
      "position": { "page": 1, "x": 0.5, "y": 0.3 },
      "size": { "width": 0.03, "height": 0.03 },
      "value": true
    }
  ]
}

요청자 입력란을 모두 삭제하려면 빈 배열을 보냅니다.

{
  "requesterInputs": []
}

요청자 첨부파일 수정하기

requesterAttachments 는 요청자 첨부파일 목록 전체가 교체됩니다. 기존 첨부파일을 유지하거나 수정하려면 id 를 포함하세요. 첨부파일 역시 파일 업로드 API 로 업로드한 fileId · token 을 사용합니다.

{
  "requesterAttachments": [
    {
      "id": "{EXISTING_ATTACHMENT_ID}",
      "name": "사업자등록증",
      "file": {
        "fileId": "{FILE_ID}",
        "token": "{FILE_TOKEN}",
        "name": "business-license.pdf"
      }
    }
  ]
}

요청자 첨부파일을 모두 삭제하려면 빈 배열을 보냅니다.

{
  "requesterAttachments": []
}

참조자 수정하기

carbonCopies 는 id 를 사용하지 않습니다. 요청 본문에 포함하면 참조자 목록 전체가 교체됩니다.

{
  "carbonCopies": [
    { "contact": "[email protected]", "locale": "ko" },
    { "contact": "01000000000", "locale": "ko" }
  ]
}

참조자를 모두 삭제하려면 빈 배열을 보냅니다.

{
  "carbonCopies": []
}

진본 증명 도장 수정하기

진본 증명 도장 설정은 seal 로 수정합니다.

{
  "seal": {
    "integritySeal": {
      "enabled": true,
      "position": "TOP_RIGHT"
    }
  }
}

진본 증명 도장을 사용하지 않으려면 enabled 를 false 로 보냅니다.

{
  "seal": {
    "integritySeal": {
      "enabled": false,
      "position": null
    }
  }
}

4. 내용 수정 완료하기

변경 내용을 원본 문서에 확정하려면 수정 완료 API를 호출합니다. reason 은 수정 사유이며, 감사추적인증서와 알림 본문에 사용됩니다.

curl -X POST 'https://api.modusign.co.kr/documents/{DOCUMENT_ID}/complete-modification' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "계약 금액과 서명자 연락처 수정"
  }'

일반 문서는 수정 완료 후 ON_GOING 상태로 돌아가고, 내부결재로 요청된 문서는 APPROVAL_PENDING 상태로 전환됩니다.

📸

스크린샷 자리 (선택) — 필요 시 수정 완료 후 문서 상태 변화 화면을 넣어주세요.

5. 내용 수정 취소하기

수정 중인 변경 내용을 폐기하려면 수정 취소 API를 호출합니다. 임시저장된 변경점은 삭제되고 문서는 진행 중 상태로 돌아갑니다.

curl -X POST 'https://api.modusign.co.kr/documents/{DOCUMENT_ID}/cancel-modification' \
  -H 'Authorization: Basic {인코딩된 API-KEY}'
🌟

안내사항

수정 취소 API는 요청 본문과 응답 본문이 없습니다.

6. API 호출 시 주의사항

  • 진행 중 문서만 수정할 수 있습니다. 수정 시작은 문서가 진행 중(ON_GOING) 상태일 때만 가능합니다.
  • 이미 서명·열람이 완료된 참여자의 데이터는 수정할 수 없습니다.
  • 목록(배열) 데이터는 전체 교체입니다. 유지할 항목도 반드시 함께 보내야 하며, 제외하면 삭제됩니다.
  • 내용 수정 시, 문서 파일·첨부파일은 base64가 아닌 파일 업로드 API 로 처리해야 합니다.
  • API KEY는 서버에서만 사용하세요. 클라이언트(브라우저)에 노출하지 마세요.
  • 링크서명 문서는 지원되지 않습니다.

  • Rate Limit(요청 횟수 제한)을 고려하세요. 일반 API는 분당 300회·초당 10회, 연산량이 큰 High-cost API는 분당 150회·초당 5회로 제한됩니다. 파일 업로드 API 는 High-cost API 로 분류되니 대량 호출 시 간격 조절이 필요합니다.

  • 파일 크기·형식 제한을 확인하세요. 문서 파일은 PDF 최대 10MB·그 외 확장자 최대 5MB, 첨부파일은 개당 최대 10MB이며, 문서 파일은 PDF를 권장합니다.

자주 발생하는 오류

응답에러 메시지원인해결 방법
401UnauthorizedAPI KEY 또는 인증 헤더 오류API KEY와 Authorization 헤더(Basic 인코딩) 확인
403Usage limit exceededAPI 사용량 소진사용량 한도 확인 또는 플랜 업그레이드
404Not found잘못된 URL 또는 존재하지 않는 documentId요청 URL과 문서 ID 확인
422Document status is invalid문서가 진행 중(ON_GOING) 상태가 아님수정 시작 전 문서 상태 확인
422This file is invalid파일이 유효하지 않음파일 업로드 API 로 업로드 후 fileId·token 사용
429Too Many RequestsRate Limit 초과응답의 X-Retry-After(초)만큼 대기 후 재시도, 지수 백오프 권장

FAQ

수정하면 원본 문서가 바로 바뀌나요?

아니요. 수정 시작부터 완료 전까지는 임시저장본에만 반영됩니다. complete-modification 을 호출해야 원본에 확정되고, cancel-modification 을 호출하면 변경이 폐기됩니다. 완료 전에는 문서 목록·검색 결과도 원본 기준으로 표시됩니다.

참여자 1명만 수정하고 싶은데, 다른 참여자가 사라졌어요.

participants 같은 목록 데이터는 전체 교체 방식이기 때문입니다. 배열에 유지할 참여자의 id 까지 함께 담아야 사라지지 않습니다.

  • 기존 항목 유지·수정 → 그 항목의 id 를 포함
  • 새 항목 추가 → id 없이 포함
  • 삭제 → 배열에서 제외
수정하는 동안 서명자가 서명할 수 있나요?

수정 시작부터 완료·취소 전까지 기존 참여 링크는 일시적으로 비활성화됩니다. 완료 또는 취소로 진행 중 상태로 돌아가면 다시 참여할 수 있습니다.

문서 파일을 base64로 바로 넣을 수 있나요?

아니요. 이 PATCH API는 base64 인라인 파일을 지원하지 않습니다. 파일은 파일 업로드 API 로 먼저 업로드한 뒤 fileId · token 으로 전달해야 합니다.

base64 방식은 인코딩 오류가 나기 쉽고 데이터 크기가 커져 불안정합니다. 또한 모두싸인의 파일 기능은 파일 업로드 API를 중심으로 개선되고 있어, 앞으로의 호환성과 사용성 측면에서도 파일 업로드 API 사용을 권장드립니다.

서명자를 열람자로(또는 그 반대로) 바꿀 수 있나요?

아니요. 기존 참여자의 역할(서명자 ↔ 열람자)을 바꾸는 변경은 지원하지 않습니다. 필요하면 기존 참여자를 삭제하고 새 참여자로 추가하는 방식을 검토해주세요.

수정 완료 후 문서 상태는 어떻게 되나요?

일반 문서는 다시 ON_GOING(진행 중) 상태가 되고, 내부결재로 요청된 문서는 APPROVAL_PENDING(결재 대기) 상태로 전환됩니다.

422 Document status is invalid 오류가 발생합니다.

수정을 시작하려는 문서가 진행 중(ON_GOING) 상태가 아닐 때 발생합니다.

응답 예시:

{
  "statusCode": 422,
  "message": "Document status is invalid"
}

이미 완료·취소된 문서는 수정할 수 없습니다. 문서 상태를 먼저 확인하세요.

429 Too Many Requests 오류가 발생합니다.

요청 횟수 제한(Rate Limit)을 초과했을 때 발생합니다.

응답 예시:

{
  "statusCode": 429,
  "message": "Too Many Requests"
}
  • 응답의 X-Retry-After 헤더(초)만큼 기다린 후 재시도하세요.
  • 연속 호출 시에는 요청 사이에 간격을 두거나 지수 백오프(Exponential Backoff) 방식을 적용하세요.
  • 파일 업로드 API는 High-cost API로 제한이 더 엄격합니다.
👍

본문 내 다른 API에 대한 내용은 각 API References에서 확인하세요!

파일 업로드 API와 에러 안내 문서를 함께 확인하세요.


Updated about 5 hours ago

Did this page help you?