문서 열람 요청은 통지·확인·청구 문서를 상대방에게 공유하고 열람 이력을 남기기 위한 기능입니다. 계정에 설정된 열람용 템플릿을 기반으로 추가 정보를 입력해 전자문서를 시작하고, 참여자에게 열람 요청 알림을 발송할 수 있습니다.

전체 흐름

열람용 템플릿을 웹서비스에서 준비한 뒤, 열람 요청 API 한 번으로 문서 생성부터 참여자 알림 발송까지 처리됩니다. 아래 흐름도에서 파랑은 서버·API 처리 단계, 민트는 사용자 화면·완료 단계를 의미합니다.

1. 열람용 템플릿 준비 — 모두싸인 웹서비스에서 열람용 템플릿을 만들고, 데이터 라벨을 설정한 뒤 템플릿 ID를 확인합니다.
2. POST /documents/request-with-template — 템플릿 ID와 열람자 정보를 담아 열람 요청을 보냅니다. (role은 '열람자')
3. 문서 생성 & 알림 발송 — 문서가 생성되고 참여자에게 열람 요청 알림이 발송됩니다. 문서 상태는 ON_GOING이 됩니다.
4. 열람 완료 — 참여자가 열람을 마치면 문서 상태가 COMPLETED로 바뀝니다. (진행 상황은 Webhook으로 추적할 수 있습니다.)

1. 열람용 템플릿 생성하기

반복해서 사용할 통지·확인·청구 문서를 열람용 템플릿으로 만들어 둡니다. 템플릿은 모두싸인 웹서비스에 로그인해 생성할 수 있습니다. 자세한 방법은 템플릿 이용방법 바로가기를 참고하세요.

2. 추가내용 입력 데이터 라벨 설정하기

API로 템플릿의 추가내용 입력을 동적으로 채우려면, 각 입력란에 데이터 라벨을 지정해 두어야 합니다. 데이터 라벨은 템플릿 수정 페이지에서 확인·설정할 수 있습니다.

• 텍스트 입력란을 클릭하면 오른쪽 상단에서 데이터 라벨을 설정할 수 있습니다.

3. 템플릿 ID 확인하기

열람 요청에는 사용할 템플릿의 ID가 필요합니다. 템플릿 ID는 템플릿 리스트 조회 API로 확인하거나, 템플릿 수정 페이지의 주소창에서 확인할 수 있습니다.

4. 열람 요청 API 호출하기

준비한 열람용 템플릿 ID와 열람자 정보를 담아 아래 엔드포인트로 요청합니다. 참여자 역할(role)이 '열람자'라는 점을 제외하면 서명 요청과 동일한 방식입니다.

curl -X POST 'https://api.modusign.co.kr/documents/request-with-template' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "{TEMPLATE_ID}",
    "document": {
      "title": "2024_확인서_홍길동",
      "participantMappings": [
        {
          "role": "열람자",
          "name": "김모두",
          "signingMethod": { "type": "EMAIL", "value": "[email protected]" }
        }
      ]
    }
  }'

주요 요청 항목

응답 예시

요청이 성공하면 201과 함께 생성된 문서 정보가 반환됩니다. 참여자 타입(type)은 VIEWER로, 문서 상태(status)는 진행 중을 뜻하는 ON_GOING입니다.

{
  "id": "DOCUMENT_ID",
  "title": "2024_확인서_홍길동",
  "status": "ON_GOING",
  "participants": [
    {
      "id": "PARTICIPANT_ID",
      "type": "VIEWER",
      "name": "김모두",
      "signingOrder": 1,
      "signingMethod": { "type": "EMAIL", "value": "[email protected]" },
      "locale": "ko"
    }
  ],
  "currentSigningOrder": 1,
  "createdAt": "2026-07-14"
}

5. 요청 시나리오별 예시

자주 쓰는 요청 형태를 document 본문 기준으로 정리했습니다. 열람 요청에서는 role이 '열람자'여야 합니다.

참여자(열람자)만 변경하여 요청하기

템플릿에 설정된 값은 그대로 두고 열람자 정보만 바꿔 요청합니다.

{
  "templateId": "{TEMPLATE_ID}",
  "document": {
    "title": "2024_확인서_홍길동",
    "participantMappings": [
      {
        "role": "열람자",
        "name": "김모두",
        "signingMethod": { "type": "EMAIL", "value": "[email protected]" }
      }
    ]
  }
}

열람자에게 추가 인증 적용하기

열람자에게 접근 암호와 휴대폰 본인 인증을 적용합니다.

{
  "templateId": "{TEMPLATE_ID}",
  "document": {
    "title": "2024_확인서_홍길동",
    "participantMappings": [
      {
        "role": "열람자",
        "name": "김모두",
        "signingMethod": { "type": "EMAIL", "value": "[email protected]" },
        "verification": {
          "password": { "value": "1234" },
          "mobileIdentification": {
            "name": "김모두",
            "phoneNumber": "01012345678"
          }
        }
      }
    ]
  }
}

추가내용 입력을 동적으로 적용하기

템플릿에 설정된 추가내용 입력란에 데이터 라벨로 값을 채웁니다. 텍스트는 문자열, 체크박스는 true/false로 지정합니다.

{
  "templateId": "{TEMPLATE_ID}",
  "document": {
    "title": "2024_확인서_홍길동",
    "participantMappings": [
      {
        "role": "열람자",
        "name": "김모두",
        "signingMethod": { "type": "EMAIL", "value": "[email protected]" }
      }
    ],
    "requesterInputMappings": [
      { "dataLabel": "주소", "value": "서울특별시 마포구 123-5번지" },
      { "dataLabel": "동의", "value": true }
    ]
  }
}

6. API 호출 시 주의사항

• 열람용 템플릿이 선행되어야 합니다. 참여자 역할이 '열람자'로 설정된 전용 템플릿을 만든 뒤 요청하세요.
• 역할(role)은 '열람자' 여야 합니다. 서명용 역할로 요청하면 열람 요청으로 처리되지 않습니다.
• API KEY는 서버사이드 전용입니다. 브라우저 등 클라이언트에 노출하지 마세요.
• 참여 수단(signingMethod.type)은 EMAIL, KAKAO, SECURE_LINK만 지원합니다.
• 추가 인증 조합 제한 — 휴대폰 본인 인증과 법인 공동인증서 인증은 한 참여자에게 함께 설정할 수 없습니다.
• Rate Limit — Standard는 분당 300·초당 10, High-cost는 분당 150·초당 5입니다. 초과 시 429와 X-Retry-After(초)가 반환되므로 지수 백오프를 권장합니다.

자주 발생하는 오류

7. 자주 묻는 질문

FAQ

{
  "statusCode": 422,
  "message": "Validation failed"
}