쉽게 연동하기

스노우싸인 Public API 가이드

목차

개요

스노우싸인 Public API를 통해 외부 시스템에서 전자계약 기능을 연동할 수 있습니다.

항목값
Base URLhttps://api-snowsign.jtsnowball.com/public
프로토콜HTTPS
응답 형식JSON (UTF-8)
인증 방식X-API-Key 헤더

인증

API Key 발급

  1. 스노우싸인 웹 콘솔 → 조직 설정 → API 키
  2. 새 API 키 → 키 이름과 사용 목적 입력 → 즉시 활성화
  3. API Key 확인

⚠️ API Key는 최초 생성 시에만 확인할 수 있습니다. 안전한 곳에 보관하세요.

인증 방법

모든 API 요청에 X-API-Key 헤더를 포함합니다.

http
X-API-Key: YOUR_API_KEY

API 목록

Hosted Embed

메서드엔드포인트설명
POST/v1/embed-sessions외부 서버가 PDF/템플릿/AI 계약 생성 iframe 세션 발급

계약서

메서드엔드포인트설명
GET/v1/contracts계약서 목록 조회
GET/v1/contracts/{id}계약서 상세 조회
GET/v1/contracts/{id}/status계약서 상태 조회
POST/v1/templates/{id}/create-contract템플릿 기반 계약서 생성
POST/v1/uploadsPDF 업로드 세션 생성
POST/v1/uploads/{id}/diagnostics업로드 PDF 사전 진단(선택)
POST/v1/contracts업로드 PDF 기반 계약서 생성. send_immediately=true이면 즉시 발송
POST/v1/contracts/{id}/send계약서 발송
POST/v1/contracts/{id}/cancel계약서 취소
POST/v1/contracts/{id}/remind리마인더 발송
GET/v1/contracts/{id}/download완료된 계약서 PDF 다운로드
GET/v1/contracts/{id}/attachments완료된 계약의 제출 파일과 다운로드 URL 조회
GET/v1/contracts/{id}/audit-certificate감사추적인증서 다운로드
POST/v1/contracts/bulk-download여러 계약서 PDF 일괄 다운로드
POST/v1/contracts/bulk-audit-certificates감사추적인증서 일괄 다운로드

템플릿

메서드엔드포인트설명
POST/v1/templates업로드 PDF 기반 템플릿 생성
GET/v1/templates템플릿 목록 조회
GET/v1/templates/{id}템플릿 상세 조회
GET/v1/templates/{id}/download템플릿 원본 파일 다운로드

링크서명

메서드엔드포인트설명
POST/v1/link-signings링크서명 생성
GET/v1/link-signings링크서명 목록 조회
GET/v1/link-signings/{id}링크서명 상세 조회
PATCH/v1/link-signings/{id}링크서명 설정 수정
POST/v1/link-signings/{id}/pause일시중지
POST/v1/link-signings/{id}/resume재개
POST/v1/link-signings/{id}/close종료
GET/v1/link-signings/{id}/contracts링크별 완료 계약 조회

Hosted Embed

Hosted Embed는 외부 ERP/그룹웨어 화면 안의 iframe에서 스노우싸인 계약 생성 흐름을 제공하는 방식입니다. 외부 서버는 API Key로 단기 Embed Session을 만들고, 브라우저에는 iframe_url만 전달합니다. 스노우싸인 API Key는 브라우저, iframe URL, postMessage payload에 노출하지 않습니다.

구현 순서와 샘플 코드는 Hosted Embed 개발 가이드를 참고하세요.

지원 흐름:

  • PDF 업로드 계약 생성/즉시 발송
  • 템플릿 단건 계약 생성
  • 템플릿 대량 발송 spreadsheet UI
  • AI 문서 작성 후 PDF 계약 생성/즉시 발송

관리 그룹과 결재

API Key는 발급자 개인 권한이 아닌 조직 자격증명입니다. API로 만든 계약·링크서명·템플릿은 전체 업무 범위에 속하며, 템플릿 조회·사용에는 모든 멤버가 사용할 수 있는 템플릿만 포함됩니다.

결재가 필요하면 API는 자동 상신하지 않고 에러를 반환합니다.

회사 도장은 Public API로 직접 추가할 수 없으며, 도장이 배치된 템플릿을 스노우싸인에서 미리 준비해 쓸 수 있습니다.

기본 흐름:

  1. 외부 서버가 POST /v1/embed-sessions를 X-API-Key로 호출합니다.
  2. 스노우싸인이 iframe_url을 반환합니다.
  3. 외부 서비스가 브라우저에 iframe_url을 내려 iframe을 표시합니다.
  4. 스노우싸인 iframe 안에서 계약 생성 화면이 실행됩니다.
  5. 생성/발송 결과는 snowsign.embed.* postMessage 이벤트로 parent window에 전달됩니다.

Embed Session 생성

http
POST /v1/embed-sessions
X-API-Key: YOUR_API_KEY
Content-Type: application/json
json
{
  "purpose": "contract_create",
  "allowed_origins": ["https://erp.example.com"],
  "flows": ["template_bulk"],
  "external_system": "customer-erp",
  "external_id": "ERP-2026-00123"
}

external_system + external_id 또는 reference_id는 같은 업무 요청의 iframe 세션이 중복 생성되지 않도록 하는 식별자로도 사용됩니다. 서로 다른 사용자가 같은 API key로 동시에 열 수 있도록 사용자/계약/주문 단위의 고유 값을 넣어주세요.

flows:

  • PDF 초안 작성: pdf_draft
  • PDF 작성 및 발송: pdf_send
  • 템플릿 초안 작성: template_draft
  • 템플릿 작성 및 발송: template_send
  • 템플릿 대량 발송: template_bulk
  • AI 문서 초안 작성: ai_draft
  • AI 문서 작성 및 발송: ai_send
  • 전체: all

전체 흐름을 허용하려면 flows: ["all"]만 전달합니다.

Response

json
{
  "success": true,
  "data": {
    "session_id": "embed-session-uuid",
    "iframe_url": "https://app.snowsign.jtsnowball.com/embed/contracts/new?...",
    "code_expires_at": "2026-06-27T12:00:00Z"
  }
}

계약서 API

외부 ERP/그룹웨어에서 PDF 문서를 스노우싸인 계약/템플릿 생성에 연결할 때는 업로드 세션을 사용합니다. API Key는 서버에만 보관하고, 브라우저 SDK에는 노출하지 마세요.

기본 흐름:

  1. ERP 서버가 POST /v1/uploads로 upload_id와 업로드 정보를 발급받습니다.
  2. 브라우저 또는 ERP 서버가 발급받은 업로드 정보로 PDF를 업로드합니다.
  3. ERP 서버가 document_upload_id와 필드 위치 정보를 계약/템플릿 생성 API에 전달합니다.
  4. 스노우싸인이 업로드된 PDF를 최종 검증한 뒤 계약서 또는 템플릿을 생성합니다.

계약 응답 공통 필드

필드포함 응답설명
title생성, 목록, 상세, 링크서명 완료 계약참여자에게 보이는 계약서 이름. 발송 후에는 바뀌지 않음
internal_title목록, 상세, 링크서명 완료 계약발송 후 조직이 바꾼 내부 이름. 참여자에게는 보이지 않으며, 바꾸지 않았으면 null
revision목록, 상세, 상태수정 차수와 상태 { number, state }. number는 상대방에게 보이는 차수(처음 발송본이 1), state는 requested(참여자가 수정 요청) 또는 null. requested이거나 수정본 결재 중(approval_status=pending)이면 서명이 일시 중지됨. 읽기 전용이며 수정은 웹에서 처리
responsible_permission_group목록, 상세계약의 관리 그룹 { uuid, name, path }
approval_status생성, 목록, 상세, 상태최신 결재 상태. 결재 요청이 없으면 null
dispatch_mode생성, 발송, 목록, 상세, 상태platform: 스노우싸인에서 발송, external: 서명 링크 직접 전달
scheduled_send_at생성, 발송, 목록, 상세, 상태예약 발송 시각. 예약되지 않았으면 null
schedule_failure_code생성, 발송, 목록, 상세, 상태예약 실행 실패 코드. 실패하지 않았으면 null
link_signing상세, 상태링크서명으로 생성된 계약에만 { id, name } 포함
participants[].attachment_requirements상세파일 요청과 제출 현황. 파일 메타데이터는 계약 완료 후 포함
participants[].email_delivery.failure_reason상세SMTP 원문과 수신자 주소를 제외한 표준 전달 실패 사유
participants[].delivery_channels상세플랫폼 계약의 발송 수단. 외부 전달은 null
participants[].alimtalk_delivery상세최근 알림톡 결과 { outcome, purpose, attempted_at, failure_reason }. outcome은 accepted·failed·unknown·skipped(서명 일시 중지 중이라 보내지 않은 리마인드). 발송 이력이 없으면 null

예약 실행 실패 코드는 approval_required, subscription_required, payment_past_due, quota_exceeded, authorization_failed, resource_invalid, system_error 중 하나입니다.

계약 생성 participants[] 공통 필드

필드타입필수설명
rolestring조건부역할 단축값. key, role_name을 직접 지정하지 않을 때 사용
keystring조건부참여자를 안정적으로 식별하는 값. PDF 계약의 signature_fields[].participant_key와 연결
role_namestring조건부참여자 역할명. 보통 role만 지정하면 됨
namestringY참여자 이름
emailstring 또는 null조건부이메일 발송을 선택하거나 외부 전달에 휴대전화번호가 없으면 필수
phonestring조건부알림톡·간편인증을 선택하거나 외부 전달에 이메일이 없으면 국내 010 휴대전화번호 필수
delivery_channelsstring[]N플랫폼 발송 수단. email, alimtalk 중 하나 이상 지정. 둘 다 발송하려면 ["email", "alimtalk"]. 외부 전달에서는 생략
securityobjectN비밀번호는 { "method": "password", "value": "..." }, 간편인증은 { "method": "identity_verification" }. 생략하면 링크의 연락처 확인 사용
localestringN이메일과 서명 화면 언어. ko, en, ja
attachment_requirementsarrayN참여자에게 요청할 파일. 최대 5개

파일 요청

PDF 계약의 participants[]와 템플릿의 signers[]에 attachment_requirements를 지정하면 서명자는 서명 화면에서 PDF·JPG(JPEG)·PNG 파일을 항목당 하나 제출할 수 있습니다. 항목은 최대 5개이며 다음 형식입니다.

json
{ "title": "신분증", "description": "주민번호 뒷자리를 가려 주세요.", "is_required": true }

템플릿에 저장한 파일 요청은 그 템플릿으로 만드는 계약에 자동 적용됩니다. 템플릿 기반 단건 계약시에는 attachment_requirements를 수정해 이번 계약의 요청만 변경할 수 있습니다. 생략하면 템플릿 설정을 그대로 사용하고, 새 배열을 보내면 그 내용으로 바꾸며, []를 보내면 파일을 요청하지 않습니다. 대량 발송/링크서명은 템플릿 설정을 모든 계약에 동일하게 적용합니다.

계약서 목록 조회

GET /v1/contracts

Query Parameters

파라미터타입필수설명
pageintegerN페이지 번호 (기본값: 1)
per_pageintegerN페이지당 항목 수 (기본값: 20, 최대: 100)
statusstringN상태 필터 (draft, scheduled, pending, in_progress, completed, cancelled, expired)

화면에서 보관한 계약은 그대로 나오고, 휴지통으로 옮긴 계약은 목록에서 빠지며 상세를 조회하면 404를 반환합니다.

Response

json
{
  "success": true,
  "data": [
    {
      "contract_id": "uuid-string",
      "title": "업무 위탁 계약서",
      "internal_title": null,
      "status": "in_progress",
      "revision": { "number": 1, "state": null },
      "dispatch_mode": "platform",
      "approval_status": null,
      "responsible_permission_group": { "uuid": "permission-group-uuid", "name": "전체 업무", "path": ["전체 업무"] },
      "email_issue": true,
      "email_issue_count": 1,
      "scheduled_send_at": null,
      "schedule_failure_code": null,
      "created_at": "2025-01-06T10:00:00Z",
      "sent_at": "2025-01-06T10:05:00Z",
      "completed_at": null
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_items": 45,
      "total_pages": 3
    }
  }
}

계약서 상세 조회

GET /v1/contracts/{contract_id}

Response

json
{
  "success": true,
  "data": {
    "contract_id": "uuid-string",
    "title": "업무 위탁 계약서",
    "internal_title": null,
    "description": "2025년 프로젝트 관련 업무 위탁 계약",
    "status": "in_progress",
    "revision": { "number": 2, "state": null },
    "dispatch_mode": "platform",
    "approval_status": null,
    "responsible_permission_group": { "uuid": "permission-group-uuid", "name": "전체 업무", "path": ["전체 업무"] },
    "email_issue": true,
    "email_issue_count": 1,
    "scheduled_send_at": null,
    "schedule_failure_code": null,
    "signing_order": "sequential",
    "participants": [
      {
        "participant_id": "participant-uuid-1",
        "name": "홍길동",
        "email": "hong@example.com",
        "phone": "010-1234-5678",
        "signing_order": 1,
        "status": "signed",
        "signed_at": "2025-01-06T14:30:00Z",
        "security_method": "identity_verification",
        "delivery_channels": ["email", "alimtalk"],
        "locale": "en",
        "email_delivery": {
          "status": "delivered",
          "attempted_at": "2025-01-06T10:05:00Z",
          "event_at": "2025-01-06T10:05:10Z",
          "failure_reason": null,
          "attempt_count": 1,
          "unresolved_issue": null
        }
      },
      {
        "participant_id": "participant-uuid-2",
        "name": "김철수",
        "email": "kim@example.com",
        "phone": null,
        "signing_order": 2,
        "status": "pending",
        "signed_at": null,
        "security_method": "password",
        "delivery_channels": ["email"],
        "locale": "ko",
        "email_delivery": {
          "status": "bounced",
          "attempted_at": "2025-01-06T10:05:00Z",
          "event_at": "2025-01-06T10:05:12Z",
          "failure_reason": "수신자 이메일 주소가 존재하지 않습니다. (5.1.1)",
          "attempt_count": 1,
          "unresolved_issue": {
            "status": "bounced",
            "event_at": "2025-01-06T10:05:12Z",
            "failure_reason": "수신자 이메일 주소가 존재하지 않습니다. (5.1.1)"
          }
        }
      }
    ],
    "variables": {
      "계약금액": "3,000,000원",
      "계약기간": "2026-04-01 ~ 2027-03-31"
    },
    "integrity_hash": null,
    "created_at": "2025-01-06T10:00:00Z",
    "sent_at": "2025-01-06T10:05:00Z",
    "completed_at": null,
    "cancelled_at": null,
    "cancelled_reason": null,
    "expires_at": "2025-01-31T23:59:59Z"
  }
}

dispatch_mode가 external인 경우, 참여자별 signing_urls와 expires_at을 추가로 확인할 수 있습니다.


계약서 상태 조회

GET /v1/contracts/{contract_id}/status

Response

json
{
  "success": true,
  "data": {
    "contract_id": "uuid-string",
    "status": "in_progress",
    "revision": { "number": 1, "state": null },
    "dispatch_mode": "platform",
    "approval_status": null,
    "email_issue": true,
    "email_issue_count": 1,
    "scheduled_send_at": null,
    "schedule_failure_code": null,
    "participants_status": {
      "total": 2,
      "signed": 1,
      "pending": 1
    }
  }
}

템플릿 계약서 생성

POST /v1/templates/{template_id}/create-contract

Request Body

필드타입필수설명
titlestringY계약서 제목
descriptionstringN계약서 설명
dispatch_modestringN계약서 전달 방식. 기본 platform. external이면 스노우싸인이 참여자에게 발송하지 않음
participantsarrayY위 공통 형식의 참여자 목록
variablesobjectN템플릿 변수 값. 텍스트 변수는 문자열, 날짜 변수는 ISO 날짜/연월 문자열, 체크박스 변수는 boolean, 숫자 변수는 숫자 또는 문자열, 주소 변수는 주소 객체
signing_orderstringN서명 순서 (템플릿 기본값 사용 시 생략)
send_immediatelybooleanNplatform은 기본값 false, true이면 즉시 발송. external은 생략하거나 true만 지정 가능
scheduled_send_atstringN예약 발송 시각. timezone을 포함한 ISO 8601 형식
messagestringN발송 시 참여자에게 전달할 메시지

participants[].role은 템플릿에 정의된 역할명과 일치해야 합니다. delivery_channels를 생략하면 역할의 기본 발송 수단 중 입력된 연락처로 보낼 수 있는 수단을 사용합니다. locale과 attachment_requirements는 생략 시 역할 설정을 따르며, 비밀번호 인증 역할에는 security.value를 전달해야 합니다.

variables 사용법

  • 동일한 변수명으로 여러개 배치할 수 있으며, 하나의 값을 전달하면 모두 동일하게 적용됩니다.
  • 텍스트 변수는 variables 객체에 { "변수명": "치환할 값" } 형식으로 전달합니다.
  • 날짜 변수는 date_precision이 day이면 YYYY-MM-DD, month이면 YYYY-MM 형식으로 전달합니다.
  • 체크박스 변수는 { "변수명": true } 또는 { "변수명": false }로 전달합니다.
  • 숫자 변수는 숫자(1234.5) 또는 "1,234.5" 같은 문자열로 전달합니다. 수식 변수는 서버가 계산하므로 값을 보내면 400입니다.
  • 주소 변수는 { "address_line1": "주소", "address_line2": "상세주소", "postal_code": "우편번호" } 객체로 전달합니다. 주소만 문자열로 전달할 수도 있습니다.

Request 예시

json
{
  "title": "홍길동 근로계약서",
  "send_immediately": true,
  "participants": [
    { "name": "홍길동", "email": "hong@example.com", "role": "근로자" }
  ],
  "variables": {
    "계약시작일": "2025-02-01",
    "개인정보동의": true,
    "급여": "3,500,000원"
  }
}

Response (201)

json
{
  "success": true,
  "data": {
    "contract_id": "contract-uuid",
    "title": "홍길동 근로계약서",
    "status": "pending",
    "approval_status": null,
    "scheduled_send_at": null,
    "schedule_failure_code": null,
    "sent_at": "2026-09-05T01:30:00"
  },
  "message": "계약서가 생성 및 발송되었습니다."
}

자체 문자·알림톡으로 서명 링크 보내기

위 요청에서 dispatch_mode를 external로 설정합니다. 참여자 연락처는 email, phone 중 하나 이상을 입력합니다. 스노우싸인은 입력된 연락처마다 signing_urls.email 또는 signing_urls.phone을 반환하며 참여자에게 메시지를 보내지 않습니다. 두 연락처를 모두 입력하면 두 링크가 모두 포함됩니다.

응답 필드 예시

json
{
  "data": {
    "contract_id": "contract-uuid",
    "status": "pending",
    "dispatch_mode": "external",
    "participants": [
      {
        "participant_id": "participant-uuid",
        "email": "hong@example.com",
        "phone": "01012345678",
        "security_method": "email",
        "signing_urls": {
          "email": "https://.../sign/token?verify=email",
          "phone": "https://.../sign/token?verify=phone"
        },
        "expires_at": "2026-10-05T01:30:00"
      }
    ]
  }
}

PDF 업로드 세션 생성

POST /v1/uploads

Request Body

필드타입필수설명
purposestringYcontract_document 또는 template_document
filenamestringY원본 파일명
content_typestringYapplication/pdf
size_bytesintegerY업로드 예정 파일 크기. 최대 50MB

Response

json
{
  "success": true,
  "data": {
    "upload_id": "upl_abc123",
    "upload_url": "https://...",
    "fields": {
      "key": "...",
      "Content-Type": "application/pdf"
    },
    "max_size_bytes": 52428800,
    "allowed_content_types": ["application/pdf"],
    "expires_at": "2026-06-11T04:00:00Z"
  }
}

정책

  • 업로드 세션은 10분 동안 유효합니다.
  • 응답의 upload_url과 fields는 PDF 업로드 요청에 그대로 사용합니다.

PDF 업로드 진단

POST /v1/uploads/{upload_id}/diagnostics

계약/템플릿 생성 전에 PDF 경고를 사용자에게 보여주고 싶은 경우에만 호출합니다. 계약/템플릿 생성 API는 이 API 호출 여부와 관계없이 업로드된 PDF를 다시 검증합니다.

Response

json
{
  "success": true,
  "data": {
    "upload_id": "upl_abc123",
    "pdf": {
      "upload_policy": "allow",
      "page_count": 2,
      "render_profile": "fontFace",
      "warnings": [],
      "errors": []
    }
  }
}

PDF 계약서 생성

POST /v1/contracts

업로드 PDF와 필드 위치 정보로 계약서를 생성합니다. 기본 전달 방식인 platform에서는 즉시 발송하거나 예약하지 않으면 초안으로 생성됩니다. external은 생성과 동시에 활성화되며 초안 생성과 예약 발송을 지원하지 않습니다.

Request Body 주요 필드

필드타입필수설명
titlestringY계약서 제목
document_upload_idstringY업로드 세션 ID
dispatch_modestringN링크 전달 방식. 기본 platform
send_immediatelybooleanNplatform은 기본값 false, true이면 즉시 발송. external은 생략하거나 true만 지정 가능
scheduled_send_atstringN예약 발송 시각. timezone을 포함한 ISO 8601 형식
participantsarrayY위 공통 형식의 참여자 목록
signature_fieldsarrayY입력칸/서명칸 위치 목록
variablesobjectN변수 필드 값
integrationobjectN외부 시스템 자유 metadata

signature_fields 좌표는 PDF.js getViewport({ scale: 1 }) 기준 pixel 좌표입니다. 원점은 페이지 좌상단이며, page_number는 1부터 시작합니다.

signature_fields 항목 주요 필드

일반 체크박스는 같은 참여자의 두 개 이상을 selection_group_key(64자 이하)로 묶을 수 있습니다. 구성원마다 selection_group_mode(at_least·exactly·at_most)와 selection_group_count(1~구성원 수 정수)를 동일하게 전달합니다. 그룹 필드는 개별 필수 여부 대신 그룹 조건을 적용하며 is_required=false로 저장됩니다. 그룹이 없으면 세 속성을 생략하거나 모두 null로 보냅니다. PDF 템플릿 생성·상세 조회도 같은 속성을 지원하고, 템플릿 기반 계약은 이를 상속합니다.

필드타입필수설명
participant 또는 participant_keystring조건부참여자 역할명 또는 참여자 key. type: "variable"에는 사용하지 않습니다.
typestringYsignature, stamp, name, phone, text, date, checkbox, address, variable
page_numberintegerYPDF 페이지 번호. 1부터 시작
position_x / position_ynumberYPDF.js pixel 좌표
width / heightnumberY입력칸 크기
position_unitstringNpixel만 지원
is_requiredbooleanN필수 입력 여부. 생략 시 true. signature/stamp/name은 항상 true, variable은 false, phone/text/date/checkbox/address만 false 지정 가능
font_sizeintegerN휴대폰/텍스트/날짜/주소/변수 텍스트 PDF 표시 폰트 크기. 1~72
text_alignstringN텍스트 정렬. left, center, right 중 하나. name, phone, text, date, address, 텍스트/숫자/날짜/주소 variable에 적용되며 서명/체크박스에는 저장되지 않습니다.
placeholder_textstringN텍스트 입력 안내 문구. 날짜 입력칸에는 저장하지 않습니다.
labelstringN100자 이하. 주소 입력칸은 주소 이름(address_display_part 참고), 그 밖의 입력칸은 내부 식별명
variable_namestring조건부type: "variable"일 때 필수
variable_value_typestringN변수 값 타입. text, number, checkbox, date, address 중 하나. 기본값 text
default_valuestringN텍스트 변수 기본값. 숫자 변수는 기본값 또는 =로 시작하는 수식(={공급가액}*0.1, {변수명} 참조와 + - * /·괄호)
date_precisionstringN날짜 입력/날짜 변수 정밀도. day 또는 month
date_format_patternstringN날짜 표시 형식. 예: YYYY년 MM월 DD일, YYYY-MM-DD, YYYY/MM. 숫자 변수에는 사용하지 않습니다.
number_formatobjectN숫자 변수의 표시 서식. decimals(0~6, 기본 0), thousands_separator(기본 true), rounding(half·up·down), korean_amount(decimals 0일 때만), unit(8자까지), unit_position(before·after). 모두 생략 가능
address_display_partstringN주소 입력칸·주소 변수의 표시 항목. full(기본, 주소와 상세주소)·address_line1·address_line2·postal_code. 같은 이름의 주소 변수와, 같은 참여자이면서 label이 같은 주소 입력칸은 값을 공유합니다(label이 없으면 참여자의 기본 주소).
fill_backgroundbooleanN날짜/변수 표시 시 PDF 배경을 흰색으로 가릴지 여부

Request 예시

json
{
  "title": "외주 계약서 - 홍길동",
  "document_upload_id": "upl_abc123",
  "signing_order": "parallel",
  "send_immediately": true,
  "message": "서명 부탁드립니다.",
  "participants": [
    {
      "role": "근로자",
      "name": "홍길동",
      "email": "hong@example.com",
      "phone": "010-1234-5678",
      "security": { "method": "identity_verification" },
      "delivery_channels": ["email", "alimtalk"],
      "locale": "ko"
    }
  ],
  "signature_fields": [
    {
      "participant": "근로자",
      "type": "signature",
      "page_number": 2,
      "position_x": 410,
      "position_y": 710,
      "width": 120,
      "height": 50,
      "position_unit": "pixel",
      "is_required": true
    },
    {
      "type": "variable",
      "variable_name": "contract_amount",
      "variable_value_type": "text",
      "page_number": 1,
      "position_x": 180,
      "position_y": 240,
      "width": 120,
      "height": 18,
      "fill_background": true,
      "text_align": "right"
    }
  ],
  "variables": {
    "contract_amount": "3,000,000원"
  },
  "integration": {
    "external_system": "customer-erp",
    "external_id": "ERP-2026-0001"
  }
}

Response (201)

json
{
  "success": true,
  "data": {
    "contract_id": "uuid-string",
    "title": "외주 계약서 - 홍길동",
    "status": "pending",
    "dispatch_mode": "platform",
    "approval_status": null,
    "sent_at": "2026-06-11T03:20:00Z"
  }
}

send_immediately=true와 scheduled_send_at 예약 시각은 함께 지정할 수 없습니다. platform에서는 둘 다 생략하면 초안으로 생성됩니다. external에서는 send_immediately를 생략하거나 true로 지정하고, 예약 발송 시각을 지정할 수 없습니다.

계약서 발송

POST /v1/contracts/{contract_id}/send

⚠️ 발송 시 월간 계약 사용량이 차감됩니다.

Request Body

필드타입필수설명
messagestringN참여자에게 전달할 메시지
scheduled_send_atstring 또는 nullN값 지정 시 예약 또는 변경, null이면 예약 취소. 필드 생략 시 즉시 발송

Response

json
{
  "success": true,
  "data": {
    "contract_id": "uuid-string",
    "status": "scheduled",
    "dispatch_mode": "platform",
    "scheduled_send_at": "2026-09-04T01:30:00",
    "schedule_failure_code": null,
    "sent_at": null
  },
  "message": "계약서 발송을 예약했습니다."
}

즉시 발송하려면 scheduled_send_at을 생략하고, 예약을 취소하려면 명시적으로 null을 전달합니다. 예약 시각은 현재보다 뒤이고 마감일보다 앞이어야 합니다.


계약서 취소

POST /v1/contracts/{contract_id}/cancel

완료·취소된 계약은 취소할 수 없으며 400 CONTRACT_STATUS_ERROR를 반환합니다.

Request Body

필드타입필수설명
reasonstringN취소 사유

Response

json
{
  "success": true,
  "data": {
    "contract_id": "uuid-string",
    "status": "cancelled"
  },
  "message": "계약서가 취소되었습니다."
}

리마인더 발송

POST /v1/contracts/{contract_id}/remind

서명 대기 중인 참여자에게 저장된 이메일·알림톡 수단으로 리마인더를 발송합니다. 서명이 일시 중지된 동안(revision 참고)에는 409 CONTRACT_SIGNING_PAUSED를 반환합니다.

Request Body

필드타입필수설명
messagestringN참여자에게 전달할 메시지
participant_uuidsarrayN특정 참여자에게만 발송할 참여자 UUID 목록

Response

json
{
  "success": true,
  "message": "리마인더가 발송되었습니다."
}

계약서 다운로드

GET /v1/contracts/{contract_id}/download

완료된 계약서 PDF의 다운로드 URL을 발급합니다. URL은 1시간 동안 유효합니다.

Response

json
{
  "success": true,
  "data": {
    "download_url": "https://...",
    "filename": "홍길동_업무위탁계약서.pdf",
    "expires_at": "2025-01-06T11:00:00Z"
  }
}

⚠️ 계약서 상태가 completed인 경우에만 다운로드 가능합니다.


제출 파일 조회 및 다운로드

GET /v1/contracts/{contract_id}/attachments

완료된 계약의 참여자별 파일 요청과 제출 파일 정보를 반환합니다. 제출 파일의 다운로드 URL은 1시간 동안 유효하며, 파일 요청이 없으면 빈 배열을 반환합니다.

Response

json
{
  "success": true,
  "data": [
    {
      "participant_id": "participant-uuid",
      "participant_name": "홍길동",
      "requirements": [
        {
          "uuid": "requirement-uuid",
          "title": "신분증",
          "description": "주민번호 뒷자리를 가려 주세요.",
          "is_required": true,
          "has_file": true,
          "file": {
            "upload_id": "upload-uuid",
            "filename": "id-card.jpg",
            "content_type": "image/jpeg",
            "size_bytes": 125000,
            "uploaded_at": "2026-06-12T12:00:00Z",
            "download_url": "https://...",
            "expires_at": "2026-06-12T13:00:00Z"
          }
        }
      ]
    }
  ]
}

계약 상태가 completed인 경우에만 사용할 수 있으며, 파일을 제출하지 않은 항목은 has_file: false, file: null로 반환됩니다.


감사추적인증서 다운로드

GET /v1/contracts/{contract_id}/audit-certificate

완료된 계약서의 감사추적인증서 PDF 다운로드 URL을 발급합니다.

Response

json
{
  "success": true,
  "data": {
    "download_url": "https://...",
    "filename": "홍길동_업무위탁계약서_감사추적인증서.pdf",
    "expires_at": "2025-01-06T11:00:00Z"
  }
}

계약서 일괄 다운로드

POST /v1/contracts/bulk-download

여러 계약서의 PDF 다운로드 URL을 한 번에 발급합니다.

Request Body

필드타입필수설명
contract_idsarrayY계약서 ID 목록 (최대 50건)

Request 예시

json
{
  "contract_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

Response

json
{
  "success": true,
  "data": [
    {
      "contract_id": "uuid-1",
      "download_url": "https://...",
      "filename": "홍길동_계약서.pdf",
      "error": null
    },
    {
      "contract_id": "uuid-2",
      "download_url": null,
      "filename": null,
      "error": "계약서가 아직 완료되지 않았습니다."
    }
  ]
}

감사추적인증서 일괄 다운로드

POST /v1/contracts/bulk-audit-certificates

여러 계약서의 감사추적인증서 다운로드 URL을 한 번에 발급합니다.

Request Body

필드타입필수설명
contract_idsarrayY계약서 ID 목록 (최대 50건)

Response:

json
{
  "success": true,
  "data": [
    {
      "contract_id": "uuid-1",
      "download_url": "https://...",
      "filename": "홍길동_감사추적인증서.pdf",
      "error": null
    },
    {
      "contract_id": "uuid-2",
      "download_url": null,
      "filename": null,
      "error": "계약서가 아직 완료되지 않았습니다."
    }
  ]
}

템플릿 API

PDF 템플릿 생성

POST /v1/templates

업로드 PDF와 역할/필드 위치 정보로 스노우싸인 템플릿을 생성합니다.

Request Body 주요 필드

필드타입필수설명
namestringY템플릿명
document_upload_idstringY업로드 세션 ID
signing_orderstringNparallel 또는 sequential
deadline_daysintegerN기본 마감 기한
signersarrayY역할 목록
signature_fieldsarrayY입력칸/서명칸 위치 목록
integrationobjectN외부 시스템 metadata

템플릿은 모든 멤버가 사용할 수 있는 전체 업무 범위로 생성됩니다.

대부분의 경우 템플릿 역할은 문자열 배열로 만들 수 있습니다. 역할 언어를 지정하려면 { "role": "...", "locale": "ko|en" } 형식을 사용하며 기본값은 ko입니다. 같은 역할명이 중복되면 key와 role_name을 명시하세요.

signature_fields 항목은 PDF 계약서 생성 API와 동일하게 is_required, text_align, font_size, 날짜 메타데이터, 변수 메타데이터를 사용할 수 있습니다. is_required는 phone/text/date/checkbox/address에서만 false 지정 가능하며, text_align은 left, center, right 중 하나이고 name, phone, text, date, address, 텍스트/숫자/날짜/주소 variable에 적용됩니다.

템플릿은 발송자 체크박스 변수 그룹도 별도로 지원합니다. type: "variable", variable_value_type: "checkbox"인 고유 variable_name 두 개 이상을 묶으며, 같은 변수의 반복 배치는 한 개로 집계합니다. 변수와 서명자 체크박스는 같은 그룹에 묶을 수 없습니다. 이 그룹은 전달한 변수 값으로 검증하며 서명자의 완료 조건과 구분합니다.

Request 예시

json
{
  "name": "표준 외주계약서",
  "document_upload_id": "upl_template_abc",
  "signing_order": "parallel",
  "deadline_days": 14,
  "signers": [{ "role": "근로자", "locale": "en" }],
  "signature_fields": [
    {
      "role": "근로자",
      "type": "signature",
      "page_number": 2,
      "position_x": 410,
      "position_y": 710,
      "width": 120,
      "height": 50,
      "position_unit": "pixel",
      "is_required": true
    },
    {
      "role": "근로자",
      "type": "date",
      "page_number": 1,
      "position_x": 180,
      "position_y": 240,
      "width": 120,
      "height": 24,
      "date_precision": "day",
      "date_format_pattern": "YYYY-MM-DD",
      "text_align": "center"
    }
  ],
  "integration": {
    "external_system": "customer-erp",
    "external_id": "ERP-TEMPLATE-001",
    "sdk_version": "1.0.0"
  }
}

Response (201)

json
{
  "success": true,
  "data": {
    "template_id": "uuid-string",
    "name": "표준 외주계약서"
  }
}

템플릿 목록 조회

GET /v1/templates

Query Parameters

파라미터타입필수설명
pageintegerN페이지 번호
per_pageintegerN페이지당 항목 수

Response

json
{
  "success": true,
  "data": [
    {
      "template_id": "uuid-string",
      "name": "근로계약서 양식",
      "description": "정규직 근로계약서 표준 양식",
      "category": "HR",
      "signing_order": "sequential",
      "deadline_days": 7,
      "can_create_link_signing": false,
      "signers": [
        { "role_name": "근로자", "signing_order": 1, "security_method": "easy_cert", "delivery_channels": ["email", "alimtalk"], "locale": "en" },
        { "role_name": "회사", "signing_order": 2, "security_method": "password", "delivery_channels": ["email"], "locale": "ko" }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_items": 5,
      "total_pages": 1
    }
  }
}

템플릿 상세 조회

GET /v1/templates/{template_id}

Response

json
{
  "success": true,
  "data": {
    "template_id": "uuid-string",
    "name": "근로계약서 양식",
    "description": "정규직 근로계약서 표준 양식",
    "category": "HR",
    "signing_order": "sequential",
    "deadline_days": 7,
    "can_create_link_signing": false,
    "signers": [
      { "uuid": "signer-uuid-1", "role_name": "근로자", "signing_order": 1, "security_method": "easy_cert", "delivery_channels": ["email", "alimtalk"], "locale": "en" },
      { "uuid": "signer-uuid-2", "role_name": "회사", "signing_order": 2, "security_method": "password", "delivery_channels": ["email"], "locale": "ko" }
    ],
    "signature_fields": [
      {
        "uuid": "field-uuid-1",
        "role_name": "근로자",
        "type": "signature",
        "page_number": 1,
        "position_x": 100.0,
        "position_y": 500.0,
        "width": 150.0,
        "height": 50.0,
        "is_required": true,
        "label": null,
        "display_order": 1,
        "date_precision": null,
        "date_format_pattern": null,
        "fill_background": null,
        "text_align": null
      }
    ],
    "variables": [
      {
        "name": "계약시작일",
        "label": "계약시작일",
        "value_type": "date",
        "default_value": null,
        "is_required": false,
        "date_precision": "day",
        "date_format_pattern": "YYYY년 MM월 DD일",
        "fill_background": true,
        "text_align": "center"
      },
      {
        "name": "개인정보동의",
        "label": "개인정보동의",
        "value_type": "checkbox",
        "default_value": null,
        "is_required": false,
        "date_precision": null,
        "date_format_pattern": null,
        "fill_background": false,
        "text_align": null
      },
      {
        "name": "급여",
        "label": "급여",
        "value_type": "text",
        "default_value": "3,000,000원",
        "is_required": false,
        "date_precision": null,
        "date_format_pattern": null,
        "number_format": null,
        "fill_background": false,
        "text_align": "right"
      }
    ]
  }
}

상세 응답 필드

필드설명
signers[].security_methodemail, password, easy_cert. 값이 없으면 email
signers[].delivery_channels역할 기반 계약의 기본 발송 수단
signers[].locale역할의 기본 이메일·서명 화면 언어
signers[].attachment_requirements역할에 저장된 파일 요청 기본값
signature_fields변수를 제외한 필드. 서명자 입력 필드와 회사 도장(organization_seal) 포함
signature_fields[].is_required서명·인감·이름은 항상 true; 휴대폰·텍스트·날짜·체크박스·주소는 저장값
variables동일한 변수명을 하나로 합친 변수 목록
variables[].is_required항상 false
signature_fields[].text_align, variables[].text_alignleft, center, right, null; 정렬 대상이 아니면 null
variables[].value_typetext, number, checkbox, date, address. 날짜는 날짜 표시 메타, 숫자는 number_format 포함. 수식 변수는 제외
can_create_link_signingPDF가 있고 서명자 역할이 정확히 하나이면 true

템플릿 원본 파일 다운로드

GET /v1/templates/{template_id}/download

템플릿 원본 PDF 파일의 임시 다운로드 URL을 반환합니다. URL은 발급 후 1시간 동안 유효합니다.

Response

json
{
  "success": true,
  "data": {
    "download_url": "https://s3.amazonaws.com/...",
    "filename": "근로계약서 양식.pdf",
    "expires_at": "2025-01-06T11:00:00+00:00"
  }
}

Errors: TEMPLATE_NOT_FOUND, TEMPLATE_FILE_NOT_FOUND


링크서명 API

링크서명 응답 공통 필드

필드포함 응답설명
responsible_permission_group생성, 목록, 상세링크와 생성 계약의 관리 그룹 { uuid, name }

링크서명 생성

POST /v1/link-signings

필드필수설명
template_uuid필수템플릿 조회 응답의 template_id
name필수링크서명 관리 이름
max_submissions필수최대 제출 수, 1 이상
description선택서명자 안내 문구
expires_at선택UTC ISO 8601. 예: 2026-12-31T14:59:59Z
require_identity_verification선택휴대폰 간편인증 요구 여부. 기본값 false
variables선택이 링크로 생성되는 계약에 공통 적용할 템플릿 변수 값
json
{
  "template_uuid": "template-uuid",
  "name": "2026 입사 동의서",
  "description": "내용을 확인하고 서명해주세요.",
  "max_submissions": 100,
  "expires_at": "2026-12-31T14:59:59Z",
  "require_identity_verification": false,
  "variables": {
    "회사명": "주식회사 스노우싸인"
  }
}

Response (201)

json
{
  "success": true,
  "data": {
    "link_signing_id": "link-signing-uuid",
    "name": "2026 입사 동의서",
    "description": "내용을 확인하고 서명해주세요.",
    "status": "active",
    "template": {
      "template_id": "template-uuid",
      "name": "입사 동의서"
    },
    "responsible_permission_group": { "uuid": "permission-group-uuid", "name": "전체 업무" },
    "link_url": "https://snowsign.jtsnowball.com/link-sign/...",
    "max_submissions": 100,
    "submission_count": 0,
    "expires_at": "2026-12-31T14:59:59",
    "require_identity_verification": false,
    "locale": "ko",
    "created_at": "2026-08-13T09:00:00",
    "updated_at": "2026-08-13T09:00:00"
  }
}

링크서명 조회 및 관리

메서드Endpoint요청설명
GET/v1/link-signings선택 query목록 조회
GET/v1/link-signings/{id}본문 없음상세와 생성 시 저장한 variables 조회
PATCH/v1/link-signings/{id}모든 필드 선택전달한 설정만 수정
POST/v1/link-signings/{id}/pause본문 없음active → paused
POST/v1/link-signings/{id}/resume본문 없음paused → active
POST/v1/link-signings/{id}/close본문 없음활성 또는 일시중지 링크 종료

목록 query는 모두 선택입니다.

Query설명
page페이지 번호. 기본값 1
per_page페이지당 항목 수. 기본값 20, 최대 100
statusactive, paused, closed, expired
search링크서명 이름 또는 템플릿명 검색
sortcreated_at:desc(기본), created_at:asc, expires_at:asc, submission_count:desc, name:asc

PATCH 요청 필드는 모두 선택이며 전달한 값만 변경합니다.

필드설명
name관리 이름
description서명자 안내 문구
max_submissions현재 제출 수보다 작을 수 없는 최대 제출 수
expires_atUTC ISO 8601 만료 일시
require_identity_verification휴대폰 간편인증 요구 여부

variables, template_uuid, status는 PATCH로 수정할 수 없습니다.

완료 계약 조회

GET /v1/link-signings/{link_signing_id}/contracts

요청 본문은 없습니다. page, per_page, search, sort query는 모두 선택이며 해당 링크에서 생성된 완료 계약만 반환합니다.

Query설명
page페이지 번호. 기본값 1
per_page페이지당 항목 수. 기본값 20, 최대 100
search계약서명(내부 이름 포함) 또는 서명자 이름·이메일·연락처 검색
sortcompleted_at:desc(기본), created_at:desc, signer_name:asc
json
{
  "success": true,
  "data": [
    {
      "contract_id": "contract-uuid",
      "title": "2026 입사 동의서",
      "internal_title": null,
      "status": "completed",
      "signer_name": "홍길동",
      "signer_email": "hong@example.com",
      "completed_at": "2026-08-13T10:00:00",
      "link_signing": {
        "id": "link-signing-uuid",
        "name": "2026 입사 동의서"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_items": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
}

contract_id는 기존 계약 상세·상태·완료 문서·감사추적인증서 API에서 사용할 수 있습니다. 일반 GET /v1/contracts 목록에는 링크서명 계약이 포함되지 않습니다.


에러 처리

에러 응답 형식

json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "에러 메시지"
  },
  "meta": {
    "timestamp": "2025-01-06T10:00:00Z"
  }
}

HTTP 상태 코드

코드설명
200성공
201생성 성공
400잘못된 요청
401인증 실패
403권한 없음 또는 사용량 초과
404리소스 없음
409현재 상태와 충돌 (예: 서명 일시 중지)
429요청 제한 초과
500서버 오류

주요 에러 코드

코드설명
API_KEY_REQUIREDAPI Key 누락
INVALID_API_KEY유효하지 않은 API Key
VALIDATION_ERROR요청 파라미터 검증 실패
QUOTA_EXCEEDED월간 사용량 한도 초과
UPLOAD_SESSION_NOT_FOUND업로드 세션을 찾을 수 없음
PDF_UPLOAD_REJECTED지원하지 않는 PDF
CONTRACT_NOT_FOUND계약서를 찾을 수 없음
TEMPLATE_NOT_FOUND템플릿을 찾을 수 없음
LINK_SIGNING_NOT_FOUND링크서명을 찾을 수 없음
INVALID_LINK_SIGNING_STATUS지원하지 않는 목록 상태
INVALID_PUBLIC_LINK_SIGNING_REQUEST링크서명 요청 필드 또는 값 오류
INVALID_CONTRACT_STATUS현재 상태에서 수행할 수 없는 작업
CONTRACT_SIGNING_PAUSED수정 요청·수정본 결재 중이라 서명이 일시 중지된 계약
INVALID_DISPATCH_MODE현재 전달 방식에서 수행할 수 없는 작업
EXTERNAL_DISPATCH_SCHEDULE_NOT_ALLOWED외부 전달 계약에 예약 발송을 요청함
APPROVAL_REQUIRED내부 앱에서 결재 후 발송해야 함

업로드 세션 제한

항목제한
사용 중인 업로드 세션API Key당 3개
사용 중인 업로드 세션 선언 용량API Key당 150MB
업로드 세션 유효 시간10분

제한 초과 시 429 상태 코드가 반환됩니다.


샘플 코드

cURL

bash
# 계약서 목록 조회
curl -X GET "https://api-snowsign.jtsnowball.com/public/v1/contracts" \
  -H "X-API-Key: YOUR_API_KEY"

# PDF 업로드 세션 생성
curl -X POST "https://api-snowsign.jtsnowball.com/public/v1/uploads" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"contract_document","filename":"contract.pdf","content_type":"application/pdf","size_bytes":1234567}'

# 계약서 발송
curl -X POST "https://api-snowsign.jtsnowball.com/public/v1/contracts/{contract_id}/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "계약서 검토 부탁드립니다."}'

Python

python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api-snowsign.jtsnowball.com/public/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# 계약서 목록 조회
response = requests.get(f"{BASE_URL}/contracts", headers=headers)
contracts = response.json()["data"]

# 계약서 발송
contract_id = "CONTRACT_ID"
response = requests.post(
    f"{BASE_URL}/contracts/{contract_id}/send",
    headers=headers,
    json={"message": "계약서 검토 부탁드립니다."}
)
print(response.json())

JavaScript (Node.js)

javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api-snowsign.jtsnowball.com/public/v1';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json'
};

// 계약서 목록 조회
const response = await fetch(`${BASE_URL}/contracts`, { headers });
const { data: contracts } = await response.json();

// 계약서 발송
const contractId = 'CONTRACT_ID';
await fetch(`${BASE_URL}/contracts/${contractId}/send`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ message: '계약서 검토 부탁드립니다.' })
});

부록

계약서 상태

상태설명
draft초안 - 아직 발송되지 않음
scheduled발송 예약 - 예약 시각을 기다리는 중
pending대기 중 - 발송됨, 서명 대기
in_progress진행 중 - 일부 참여자 서명 완료
completed완료 - 모든 참여자 서명 완료
cancelled취소됨
expired만료됨

참여자 상태

상태설명
pending서명 대기
viewed문서 열람
signed서명 완료
declined거절. 계약은 서명 대기로 남으며, 발송자가 수정본을 보내면 pending으로 돌아갑니다

서명 필드 타입

타입설명
signature서명란
name이름 필드
text텍스트 입력
date날짜 입력
checkbox체크박스
stamp인감 도장
variable템플릿 변수 (API로 값 주입, 서명자 입력 불가)

최종 수정: 2026-09-04 문서 버전: 1.9