모두싸인 API QuickStart

모두싸인 API를 사용하여 전자서명 요청을 보내는 방법을 단계별로 안내합니다. 이 가이드를 따라하면 인증 → 템플릿 조회 → 템플릿으로 서명 요청 → 문서 상태 확인까지의 전체 플로우를 직접 경험할 수 있습니다.

⏱️

이 가이드를 완료하는 데 약 10분이 소요됩니다. 시작하기 전에 모두싸인 서비스에서 API Key를 발급받으세요.

사전 준비

시작하기 전에 아래 항목을 준비해 주세요.

📘

모두싸인 API의 Base URL은 https://api.modusign.co.kr 입니다. 모든 요청에 이 URL을 사용합니다.

전체 플로우 개요

Step 1. API Key 발급 및 인증 설정

모두싸인 API는 HTTP Basic 인증(RFC 7617)을 사용합니다. 모두싸인에서 발급받은 API Key와 사용자 이메일을 조합하여 인증 헤더를 생성합니다.

1-1. API Key 발급

모두싸인 서비스에 로그인 후 설정 → 개인설정 → API KEY 메뉴로 이동하여 API KEY 추가하기 버튼을 클릭합니다.

⚠️

API Key는 최초 발급 시에만 전체 내용을 확인할 수 있습니다. 발급 후에는 다시 조회할 수 없으므로, 즉시 복사하여 안전하게 보관하세요.

1-2. Authorization 헤더 생성

인증 헤더는 아래 3단계로 생성합니다.

인증 테스트

API Key가 정상적으로 작동하는지 간단한 문서 목록 조회로 확인해 보세요.

# 이메일과 API Key를 Base64로 인코딩하여 요청
curl -X GET "https://api.modusign.co.kr/documents?offset=0&limit=10" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(echo -n '[email protected]:your-api-key' | base64)"

💡

OAuth 2.0 인증이 필요한 경우 (예: 서버 간 연동, 사용자 대리 인증 등), 별도의 OAuth 앱 등록 및 토큰 발급 절차가 필요합니다. 자세한 내용은 OAuth 인증 가이드를 참고하세요.

Step 2. 템플릿 준비 및 확인

서명 요청에 앞서 템플릿을 준비하고, 서명 요청에 필요한 템플릿 ID, 참여자 역할(role), 데이터 라벨(dataLabel) 을 확인합니다.

2-1. 템플릿 생성

모두싸인 웹서비스에 로그인한 뒤 템플릿 메뉴에서 문서를 업로드하고, 서명란·입력란·참여자 역할 등을 설정하여 템플릿을 생성합니다.

템플릿 생성 시 아래 항목을 설정해 두면 API 연동이 훨씬 수월합니다.

📘

데이터 라벨 설정 방법: 템플릿 수정 페이지에서 텍스트 입력란을 클릭하면 우측 상단에 데이터 라벨을 설정할 수 있습니다. 이 라벨은 API에서 값을 동적으로 주입할 때 식별자로 사용됩니다.

2-2. 템플릿 ID 확인

템플릿 ID는 두 가지 방법으로 확인할 수 있습니다.

모두싸인에서 해당 템플릿의 수정 페이지로 이동하면, 브라우저 주소창에서 템플릿 ID를 직접 확인할 수 있습니다.

위 이미지와 같이 주소창의 /template/ 뒤에 오는 UUID 형식의 값이 템플릿 ID 입니다.

https://app.modusign.co.kr/template/{TEMPLATE_ID}/step/1st
                                     ↑ 이 부분이 템플릿 ID

예시: https://app.modusign.co.kr/template/ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f/step/1st → 템플릿 ID: ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f

2-3. 참여자 역할 및 데이터 라벨 확인 (선택)

서명 요청 시 정확한 role과 dataLabel 값이 필요합니다. 템플릿 수정 페이지 UI에서 직접 확인하거나, API로 상세 조회할 수 있습니다.

GET /templates/{templateId}

curl -X GET "https://api.modusign.co.kr/templates/ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f" \
  -H "Accept: application/json" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS"

⚠️

participants[].role 값은 Step 3에서 participantMappings[].role에 정확히 일치하도록 입력해야 합니다. 오타나 공백 차이가 있으면 매핑에 실패하므로, API 응답 값을 그대로 복사하여 사용하세요.

Step 3. 템플릿으로 서명 요청

미리 만들어 둔 템플릿을 기반으로 서명 요청을 보냅니다. 템플릿에 설정된 문서, 서명란, 입력란이 자동으로 적용되며, 참여자 이름과 연락처만 지정하면 됩니다.

요청

POST /documents/request-with-template

주요 파라미터

{
  "requesterInputMappings": [
    {
      "dataLabel": "계약시작일",
      "value": "2026-04-01"
    },
    {
      "dataLabel": "특이사항",
      "value": "수습기간 3개월"
    }
  ]
}

최소 요청 예시

아래는 근로자 역할의 참여자에게 이메일로 서명 요청을 보내는 가장 간단한 예시입니다.

curl -X POST https://api.modusign.co.kr/documents/request-with-template \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f",
    "document": {
      "title": "2026_근로계약서_김모두",
      "participantMappings": [
        {
          "role": "근로자",
          "name": "김모두",
          "signingMethod": {
            "type": "EMAIL",
            "value": "[email protected]"
          }
        }
      ]
    }
  }'

💡

participantMappings의 role은 템플릿에 설정된 역할명과 정확히 일치해야 합니다. Step 2에서 조회한 participants[].role 값을 그대로 사용하세요.

활용 예시

const body = {
  templateId: 'ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f',
  document: {
    title: '2026_근로계약서_김모두',
    participantMappings: [
      {
        role: '근로자',
        name: '김모두',
        signingMethod: { type: 'EMAIL', value: '[email protected]' }
      },
      {
        role: '근로자2',
        excluded: true
      }
    ]
  }
};

const body = {
  templateId: 'ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f',
  document: {
    title: '2026_근로계약서_김모두',
    participantMappings: [
      {
        role: '근로자',
        name: '김모두',
        signingMethod: { type: 'EMAIL', value: '[email protected]' },
        verification: {
          password: { value: '1234' },
          mobileIdentification: {
            name: '김모두',
            phoneNumber: '01012345678',
            allowOptions: ['SIMPLE_AUTH', 'SMS_OR_PASS']
          }
        }
      }
    ]
  }
};

const body = {
  templateId: 'ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f',
  document: {
    title: '2026_근로계약서_김모두',
    participantMappings: [
      {
        role: '근로자',
        name: '김모두',
        signingMethod: { type: 'EMAIL', value: '[email protected]' }
      }
    ],
    requesterInputMappings: [
      { dataLabel: '주소', value: '서울특별시 마포구 123-5번지' },
      { dataLabel: '동의', value: true }
    ]
  }
};

const body = {
  templateId: 'ca7295b0-76b4-11eb-b8d3-e3b7b0e3e62f',
  document: {
    title: '2026_근로계약서_김모두',
    participantMappings: [
      {
        role: '근로자',
        name: '김모두',
        signingMethod: { type: 'EMAIL', value: '[email protected]' },
        attachmentRequests: [
          { dataLabel: '사업자등록증 사본', excluded: true },
          { dataLabel: '주민등록증 사본', required: false },
          { dataLabel: '통장 사본', required: true }
        ]
      }
    ]
  }
};

응답 예시

서명 요청이 성공하면 문서 정보가 반환됩니다. 이때 초기 상태는 ON_PROCESSING (문서 처리 중)입니다.

{
  "id": "b30fa690-21c4-11f1-a119-f13b32237000",
  "title": "[테스트] 개인정보이용동의서_온보딩 0313",
  "status": "ON_PROCESSING",
  "requester": {
    "email": "[email protected]",
    "name": "김준성"
  },
  "participants": [
    {
      "id": "b357ac10-21c4-11f1-bfad-276d8ebdd208",
      "type": "SIGNER",
      "name": "김준성",
      "signingOrder": 1,
      "signingDue": {
        "valid": false,
        "datetime": null
      },
      "signingMethod": {
        "type": "KAKAO",
        "value": "01022319638"
      },
      "locale": "ko"
    }
  ],
  "currentSigningOrder": 0,
  "signings": [],
  "accessibleByParticipant": true,
  "abort": null,
  "file": {
    "downloadUrl": "https://api.modusign.co.kr/documents/{documentId}/file?signedUrlToken=..."
  },
  "auditTrail": null,
  "metadatas": [],
  "seal": {
    "integritySeal": {
      "enabled": false,
      "position": null
    }
  },
  "updatedAt": "2026-03-17T05:46:54.000Z",
  "createdAt": "2026-03-17T05:46:53.000Z",
  "brandId": "01KFD67CRXE14ES6W9XR3E5CPH"
}

주요 응답 필드

문서 상태 전환 흐름

📘

서명 요청 직후 문서는 ON_PROCESSING 상태로 생성됩니다. 모두싸인 서버에서 문서 처리가 완료되면 자동으로 ON_GOING 상태로 전환되며, 이때부터 참여자에게 서명 요청이 발송됩니다.

POST 요청 직후          문서 처리 완료           참여자 서명 완료
      │                      │                      │
      ▼                      ▼                      ▼
ON_PROCESSING ──────▶ ON_GOING ──────────▶ COMPLETED
 (문서 처리 중)       (서명 진행 중)         (서명 완료)

💡

ON_PROCESSING → ON_GOING 전환은 보통 수 초 내에 완료됩니다. 실시간으로 상태 변경을 감지하려면 **웹훅(Webhook)**을 설정하거나, Step 4의 상태 조회 API를 폴링하세요.

Step 4. 문서 상태 확인

서명 요청 후 문서의 진행 상태를 조회합니다. Step 3에서 받은 id 값을 사용합니다.

요청

GET /documents/{documentId}

curl -X GET https://api.modusign.co.kr/documents/doc_abc12345 \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS"

문서 상태 값

💡

문서 상태 변경을 실시간으로 수신하려면 **웹훅(Webhook)**을 설정하는 것을 권장합니다. POST /webhooks 엔드포인트를 통해 웹훅을 등록할 수 있습니다.

다음 단계

QuickStart를 완료했습니다! 이제 아래 심화 기능들을 살펴보세요.