임베디드 내용 수정은 이미 발송한 진행 중 문서를, 요청자가 임베디드 화면에서 다시 수정할 수 있는 기능입니다.
요청자는 고객사 사이트(연동 서비스) 화면 안에서 참여자, 입력란, 첨부파일 요청, 문서 파일 등을 수정한 뒤 다시 서명 요청을 이어갈 수 있습니다.

전체 흐름

전체 과정은 크게 아래 6단계로 진행됩니다. 파란색은 서버에서 API로 처리하는 단계, 초록색은 요청자가 임베디드 화면에서 직접 진행하는 단계입니다.

1. 수정할 문서에 대해 POST /documents/{documentId}/start-modification 을 호출해 수정을 시작합니다.
2. GET /documents/{documentId}/embedded-view API로 embeddedUrl 을 발급받습니다.
3. 발급받은 embeddedUrl 을 iframe, 새 창, 또는 현재 창에서 엽니다.
4. 요청자가 임베디드 화면에서 내용을 수정하고 완료합니다.
5. 완료 후 설정한 redirectUrl 로 이동합니다.
6. Webhook event 로 최종 상태를 동기화합니다.

1. 문서 수정 시작하기

먼저 문서를 수정 중 상태로 전환합니다.

curl --request POST \
  --url https://api.modusign.co.kr/documents/{DOCUMENT_ID}/start-modification \
  --header 'Authorization: Basic {YOUR_ENCODED_AUTH_STRING}'

2. 임베디드 URL 발급하기

수정이 시작된 문서에 대해 임베디드 URL을 발급합니다.

curl --get \
  --url 'https://api.modusign.co.kr/documents/{DOCUMENT_ID}/embedded-view' \
  --header 'Authorization: Basic {YOUR_ENCODED_AUTH_STRING}' \
  --data-urlencode 'redirectUrl=https://www.modusign.co.kr'

응답으로 받은 embeddedUrl 을 iframe, 새 창, 또는 현재 창에서 열면 임베디드 수정 화면으로 진입합니다.

// 새 탭으로 열기
window.open("https://app.modusign.co.kr/embedded-view/XXX?at=XXXXXXX...");

// iframe에 열기
var targetIframe = document.getElementById('target-iframe');
targetIframe.src = 'https://app.modusign.co.kr/embedded-view/XXX?at=XXXXXXX...';

3. 파일을 수정할 때 (파일 업로드 API 사용)

수정 과정에서 문서 파일이나 첨부파일을 API로 다뤄야 할 경우, 파일 데이터를 요청 본문에 base64로 직접 담는 방식도 지원되지만, 되도록 파일 업로드 API 를 사용하시길 강력히 권장합니다.

curl --request POST \
  --url 'https://api.modusign.co.kr/files?type=document' \
  --header 'Authorization: Basic {YOUR_ENCODED_AUTH_STRING}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@계약서.pdf'

{
  "fileId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "token": "XXXXXXX...",
  "url": "https://.../계약서.pdf"
}

4. 수정 완료 후 처리하기

요청자가 임베디드 화면에서 수정을 완료하면 redirectUrl 로 이동합니다. 이때 다음 쿼리 파라미터가 함께 전달됩니다.

https://www.modusign.co.kr?documentId={DOCUMENT_ID}&eventType=document_modification_completed

내부결재가 필요한 문서는 다음 eventType 으로 전달됩니다.

https://www.modusign.co.kr?documentId={DOCUMENT_ID}&eventType=document_modification_approval_requested

5. Webhook event

임베디드 내용 수정과 관련된 event는 다음과 같습니다.

6. API 호출 시 주의사항

임베디드 내용 수정 API를 연동하실 때 다음 사항을 미리 확인하시면 오류를 크게 줄일 수 있습니다.

• 진행 중 문서만 수정할 수 있습니다. 수정을 시작하려면 문서가 진행 중(ON_GOING) 상태여야 합니다. 이미 완료·취소된 문서는 수정할 수 없습니다.
• API KEY는 서버에서만 사용하세요. API KEY는 유저 권한을 획득하는 민감한 정보입니다. 클라이언트(브라우저)에 노출하지 말고, embeddedUrl 만 클라이언트로 전달해 여세요.
• embeddedUrl 은 발급 후 2시간만 유효합니다. 만료되면 다시 발급받아야 하며, 마지막 저장 시점까지의 내용은 보존됩니다.
• 요청자 본인만 임베디드 수정 화면에 진입할 수 있습니다.
• 링크서명 문서는 지원되지 않습니다.
• Rate Limit(요청 횟수 제한)을 고려하세요. 일반 API는 분당 300회·초당 10회, 연산량이 큰 High-cost API는 분당 150회·초당 5회로 제한됩니다. 파일 업로드 API 는 High-cost API 로 분류되니 대량 호출 시 간격 조절이 필요합니다.
• 파일 크기·형식 제한을 확인하세요. 문서 파일은 PDF 최대 10MB·그 외 확장자 최대 5MB, 첨부파일은 개당 최대 10MB이며, 문서 파일은 PDF를 권장합니다.

자주 발생하는 오류

FAQ

{
  "statusCode": 422,
  "message": "This file is invalid"
}

{
  "statusCode": 429,
  "message": "Too Many Requests"
}