API 레퍼런스 | 페이싸인
v1REST · JSON

PAYSIGN 문서 관리 API

템플릿 정보 조회, 수신인 정보 및 상태 조회, 문서의 저장 및 발송, 문서 상태 조회 등의 기능을 고객사 솔루션과 연동하기 위한 API입니다.

  • HTTP 기반의 REST API 프로토콜에 기반합니다.
  • 본문의 기본 형식은 JSON을 이용합니다.
  • 문자코드는 UTF-8을 사용합니다.
  • 기본적으로 대소문자를 구분하는 것을 원칙으로 합니다.

인증 헤더

모든 요청에는 발급받은 Api-IdAuthorization 헤더가 필요합니다. PAYSIGN 홈페이지 로그인 후 설정 → API 사용 요청에서 신청하고, 승인되면 설정 → API 사용 정보에서 확인할 수 있습니다.

  • 사용 요청시 API에 접속할 IP주소(공인IP)를 최소 1개 이상 등록합니다. 등록한 IP에서만 접속이 가능합니다.
  • API 토큰과 접속 IP는 필요에 따라 변경 가능합니다. (API 아이디는 변경 불가)

접속 서버

항목
접속 호스트https://www.paysign.co.kr
서버 IP주소175.126.82.238
접속 포트443

공통 응답 코드

API 성공·실패 여부는 기본적으로 HTTP Status code를 이용합니다. 세부 응답코드와 메시지는 Response Body에서 JSON 형식으로 제공합니다.

HTTP Statuscodemessage
200요청 성공
400E000DB 오류
401E110API 아이디가 누락되었습니다
401E111잘못된 API 아이디입니다.
401E120API 토큰값이 누락되었습니다.
401E121잘못된 API 토큰입니다.
401E122허용되지 않은 IP에서 접속하였습니다.
401E210회원정보가 없습니다.
402E900충전금액 부족
406E100요청 본문 데이터의 JSON형식이 잘못되었습니다.
500E100서버 내부 오류
501E100잘못된 API경로입니다.

문서 상태 코드

코드상태
TEMP임시보관
RESERVED예약 중
WAIT발송 준비
SENT발송 완료
FAILED발송 실패
SENT_PARTIAL일부 발송
READ읽음
COMPLETED서명 완료
COMPLETED_PARTIAL일부 서명
EXPIRED기한 만료

수신인 상태 코드

코드상태
TEMP임시보관
RESERVED예약 중
FAILED발송실패
WAIT발송준비 (발송시점에는 성공여부 확인 불가)
SENT발송완료
RECEIVED문서수신
READ문서열람
COMPLETED서명완료
EXPIRED기한만료
SENT_EXPIRED발송 후 기한만료
RECEIVED_EXPIRED수신 후 기한만료
READ_EXPIRED열람 후 기한만료

증명서 발급 상태 코드

코드상태
COMPLETED발급 완료
WAIT발급 대기중
FAILED발급 실패
NOREQ증명서 발급요청을 하지 않음
Authentication
Api-Id: {API아이디}
Authorization: Bearer {API토큰}
Content-Type: application/json; charset=UTF-8
Base URL
https://www.paysign.co.kr
오류 응답
{
  "code": "E500",
  "message": "요청하신 템플릿이 없습니다."
}

환경 설정

API를 사용할 서버의 환경설정 값을 조회합니다.

환경 설정 조회인증 필요

API를 사용할 서버의 환경설정 값을 조회합니다.

문서 작성 시 사용할 수 있는 서명만료 기한(expire_list)과 문서 분류(doc_categories)를 함께 내려줍니다.

Response Body

expire_listExpireKey array필수

문서 작성시 vexpire_in에 입력할 수 있는 값 목록

remain_doc_countint

발송가능 문서 건수 (미사용)

remain_pointint필수

보유포인트

doc_categoriesDocCategory array필수

문서 작성시 사용할 분류 목록

ExpireKey object

타입길이설명
keyint5문서생성시 vexpire_in 항목에 입력할 수 있는 값
commentstring10설명

DocCategory object

타입길이설명
seqstring20문서생성시 doc_category_seq 항목에 입력할 수 있는 값
category_namestring20분류명
category_codestring20분류코드
display_orderstring10화면표시 순서
use_buttonstring1수신인이 제출하는 버튼 존재 여부 (Y/N)
button_labelstring20제출 버튼 레이블
GET/api/v1/configShell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/config' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
200 · Response
{
  "expire_list": [
    { "key": 24, "comment": "1 일" },
    { "key": 48, "comment": "2 일" },
    { "key": 3000, "comment": "5 개월" },
    { "key": 4361, "comment": "6 개월" }
  ],
  "remain_doc_count": 100,
  "doc_categories": [
    {
      "seq": "1",
      "category_name": "계약서",
      "category_code": "CONTRACT",
      "display_order": "10",
      "use_button": "Y",
      "button_label": "확인"
    },
    {
      "seq": "6",
      "category_name": "동의서",
      "category_code": "AGREEMENT",
      "display_order": "50",
      "use_button": "N",
      "button_label": null
    }
  ]
}

문서 템플릿

접속한 계정에서 사용 가능한 문서 템플릿 정보를 조회합니다.

문서 템플릿 조회인증 필요

접속한 계정에서 사용가능한 문서 템플릿 정보를 조회합니다.

템플릿번호를 명시하면 해당 템플릿에 대한 정보만 리턴 받고, 템플릿번호를 생략하면 모든 템플릿 정보 목록을 리턴 받습니다.

참고템플릿을 생성하거나 변경하는 작업은 API에서 사용이 불가능합니다. PAYSIGN 홈페이지에 로그인 후 템플릿 보관함에서 미리 제작해야 합니다.

Query Parameters

pageint · 길이 11

시작 페이지 (기본값 : 1)

sizeint · 길이 11

페이지당 항목 수 (기본값 : 100)

Response Body

listTemplate object array필수

템플릿 데이터 배열

has_next_pageboolean필수

다음 목록이 있는지 여부

Template object

타입길이설명
seqstring20템플릿을 구분하는 일련번호
titlestring256템플릿 제목
enableboolean1사용 가능 여부
vdoc_typechar1템플릿 내용 형식 (H:HTML, M:마크다운)
template_typechar1템플릿 종류 (B:폼빌더, E:에디터)
datetime_createint10생성 일시 (unixtime)
datetime_modifyint10최종 수정 일시 (unixtime)
category_namestring20템플릿 종류
sender_fieldSender field array템플릿에 정의된 발송 변수 정보

Sender field object

타입길이설명
text_idstring128발송변수로 사용하는 템플릿 위젯 ID
field_typestring10위젯 종류 (일반, 링크URL, 첨부파일, 청구금액)
field_emptystring10문서 발송시 값이 없는 경우 위젯 처리 방식 (hide, empty)
labelstring128발송변수 위젯의 레이블, 레이블이 없는 경우 위젯 ID

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E500요청하신 템플릿이 없습니다.
400E502템플릿이 비어 있습니다.
400E503템플릿 정보 파싱 중 오류가 발생하였습니다.
GET/api/v1/template/[:템플릿번호]Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/template/:템플릿번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
200 · Response
{
  "has_next_page": false,
  "list": {
    "seq": "12345678901234567890",
    "title": "납부 청구서 템플릿 샘플",
    "enable": true,
    "vdoc_type": "H",
    "template_type": "B",
    "datetime_create": 1649321902,
    "datetime_modify": 1649833299,
    "build_completed": true,
    "category_name": "청구서",
    "sender_field": [
      {
        "field_id": "text_2",
        "label": "금액",
        "field_type": "일반",
        "field_empty": "hide"
      },
      {
        "field_id": "text_3",
        "label": "지로번호(체크번호)",
        "field_type": "일반",
        "field_empty": "empty"
      }
    ]
  }
}

전자 문서 생성/수정인증 필요

저장할 문서의 템플릿 정보와 수신인 정보를 JSON 구조로 전달합니다.

신규문서 생성 : API 호출시 URL에 문서번호를 생략합니다.

기존문서 수정 : API 호출시 URL에 수정하고자 하는 문서의 문서번호를 명시합니다. 수정시에는 Request Body의 전체 필드가 선택사항입니다.

참고template_seq / content 둘 중 하나는 반드시 있어야 합니다.
참고content 사용시 service_type이 S210, S211인 html 문서의 경우 64KB 이하만 가능합니다.
참고content 항목의 내용에는 doc_type 값이 H 인 경우는 html 내용을 base64로 인코딩, U 인 경우 pdf 파일 내용을 base64로 인코딩 하여 저장합니다.
참고S510 : 등기우편 / S210 : 서명동의 / S211 : 카카오 등기 발송입니다.
참고S210, S211은 알림톡으로 발송 할 수 없습니다. (send_method = B 사용 필요)
참고분류일련번호가 지정된 경우 분류명은 무시됩니다. 분류명과 분류일련번호는 /api/v1/config API의 doc_categories 항목을 참조하시기 바랍니다.
참고template_seq 없이 content를 사용하는 경우 use_button 이 'N' 인 분류만 사용 가능합니다.

Request Body

vsubjectstring · 길이 250필수

문서 제목

template_seqstring · 길이 20조건부

발송할 문서 템플릿 번호

contentstring조건부

발송할 문서 본문 내용

service_typestring · 길이 4

S510, S210, S211 중 하나

doc_typestring · 길이 1

content 에 저장된 본문 문서 형태 — H: HTML (기본값), U: PDF

doc_category_seqint · 길이 10조건부

분류일련번호 (template_seq 가 지정되지 않은 경우 사용)

doc_category_namestring · 길이 10조건부

분류명 (template_seq 가 지정되지 않은 경우 사용)

use_doc_repositoryboolean

공인전자문서센터 저장 여부

send_methodchar · 길이 1

B : 카카오 전자문서 발송(기본값) / K : 알림톡 발송

qrcode_sendint · 길이 2

QRCODE 발송 여부, 기본값 0 (0:일반 발송, 1:QRCODE 발송, 10:QRCODE 마감)

vexpire_inint · 길이 4조건부

발송 후 서명만료 기한 (단위:시간). 환경설정 API의 expire_list key 값만 사용 가능. 0 또는 생략하면 vexpire_at 사용

vexpire_atstring · 길이 13조건부

서명만료 일시. yyyy-mm-dd hh:00:00 또는 yyyy-mm-dd hh 형식. 카카오 전자문서 발송시 최대 6개월

is_reservedboolean

예약 발송 여부. qrcode_send=0 이 아닌 경우 무시

reserved_datestring · 길이 16조건부

예약 발송시 발송 시각. 년-월-일 시:분 / 10분 단위. is_reserved=true 인 경우 필수

send_seperateboolean

분할 발송 여부. qrcode_send=0 이 아닌 경우 무시

seperate_numint · 길이 5

분할 발송시 한번에 발송할 수신인 수. 100명 단위, 최대 500

seperate_minuteint · 길이 3

분할 발송시 발송 간격 (단위:분). 10분 단위, 최대 120

receiversReceiver array조건부

문서 수신인 목록. qrcode_send=1 이 아닌 경우 필수

sender_filesSender file array

발송변수에서 사용할 첨부파일. qrcode_send=0 이 아닌 경우 무시

need_verificationboolean

알림톡 발송시 수신인 인증 필요 여부 (기본값 : true)

webhook_urlstring

문서 수신인의 상태가 변경될 때 상태 정보를 받을 URL

descriptionstring

알림톡 중간에 표시되는 설명 문구 (최대 400자)

Response Body

doc_seqstring · 길이 20필수

저장된 문서의 문서번호

qrcodestring

qrcode_send 값이 0이 아닌 경우 발송용 QRCODE 이미지 파일을 base64 인코딩하여 전달

receiversReceiver array필수

저장된 수신인 정보

Receiver object

타입길이설명
namestring32카카오에 가입된 수신인 실명 · 필수
phonestring13수신 휴대폰 번호. 010-1234-5678 또는 01012345678 · 필수
birthstring10수신인 생년월일. send_method=B 인 경우 필수. yyyy-mm-dd 또는 yyyymmdd
payloadstring32수신인 정보 페이로드 (최대 32글자)
sender_dataSender data array템플릿에 지정되어 있는 발송변수 실데이터
contentstring본문 파일 (Base64 Encoding). doc_type=U 이고 수신인마다 본문이 다를 경우 사용

Sender data object

타입길이설명
field_idstring256템플릿에 명시된 발송변수 위젯 field_id 값 · 필수
valuestring256위젯에 표시할 값 · 필수

Sender file object

타입길이설명
filenamestring256첨부된 파일명 · 필수
contenttextN/A파일 내용을 BASE64로 인코딩하여 저장 · 필수

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E100문서 발송 데이터 일반 오류
400E200템플릿 관련 오류
400E300수신인 정보 관련 오류
400E400발송 변수 관련 오류
PUT/api/v1/document/[:문서번호]Shell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/document/:문서번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{ }'
200 · Response
{
  "doc_seq": "12345678901234567890",
  "receivers": [
    {
      "seq": "12345678901234567891",
      "name": "홍길동",
      "phone": "010-1111-2222",
      "birthday": "1993-12-16",
      "payload": "123456789ABCDEFG"
    },
    {
      "seq": "12345678901234567892",
      "name": "이몽룡",
      "phone": "010-1234-1234",
      "birthday": "2001-12-17",
      "payload": ""
    }
  ]
}

전자 문서 조회인증 필요

작성된 전자 문서의 정보를 조회합니다.

문서번호를 명시하면 명시된 문서번호에 해당하는 문서정보만 리턴하고, 문서번호를 생략하면 최근 생성된 문서순으로 문서 목록을 리턴합니다.

Query Parameters

pageint · 길이 11

시작 페이지 (기본값 : 1)

sizeint · 길이 11

페이지당 항목 수 (기본값 : 100)

Response Body

listDocument object array · 길이 N/A필수

문서 정보 배열

has_next_pageboolean · 길이 N/A필수

다음 목록이 있는지 여부

Document object

타입길이설명
seqstring20문서 번호
vstatestring20문서 상태 (문서 상태 코드표 참고)
vsubjectstring256문서 제목
vsizeint문서 크기
vdatetimeint생성 일시 (unixtime)
vlastmodifiedint최종 변경 일시 (unixtime)
vdatetime_requestint발송 요청 일시 (unixtime)
vdatetime_completedint최종 승인 일시 (unixtime)
vreceiver_countint수신인 수
vdoc_typechar1문서 형태 (M:마크다운, H:HTML, F:첨부파일, B:폼빌더, U:PDF 파일)
vtemplate_typechar1템플릿 종류 (B:폼빌더, E:에디터)
vtemplate_seqstring20템플릿 번호
contentstring발송 문서 본문 (템플릿 없이 발송한 경우에만)
vexpire_inint문서 서명 만료 시간 (0이면 vexpire_at 적용, 단위:시간)
vexpire_atdatetime문서 서명 만료 일시 (공백이면 vexpire_in 적용)
deletedboolean삭제 여부 (휴지통의 문서이면 true)
datetime_deleteint삭제 일시 (timestamp)
send_seperateboolean분할 발송 여부
seperate_numint분할 발송시 한번에 발송할 수신인 수
seperate_minuteint분할 발송시 발송 간격 (단위:분), 10분 단위
is_reservedboolean예약 발송 여부
reserved_datestring19예약 발송일 경우 예약 시각 (년-월-일 시:분:초)
category_namestring20문서 분류
use_doc_repositoryboolean공인전자문서센터 저장 여부
qrcode_sendintQRCODE 발송 여부 (0:일반발송, 1:QRCODE 발송, 10:QRCODE 마감)
qrcodestringqrcode_send가 0이 아닌 경우, 발송용 QRCODE 이미지를 base64로 인코딩하여 전달

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E500요청하신 문서가 없습니다.
GET/api/v1/document/[:문서번호]Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/document/:문서번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
200 · Response
{
  "has_next_page": false,
  "list": [
    {
      "seq": "12345678901234567890",
      "vstate": "RESERVED",
      "vsubject": "API 테스트 문서의 제목입니다.",
      "vsize": 180900,
      "vdatetime": 1656308355,
      "vlastmodified": 1660020720,
      "vdatetime_request": 1690689600,
      "vdatetime_completed": 0,
      "vreceiver_count": 2,
      "vdoc_type": "B",
      "vtemplate_type": "B",
      "vtemplate_seq": "12345678901234567890",
      "vexpire_in": 168,
      "vexpire_at": "2023-07-30 13:00:00",
      "deleted": false,
      "datetime_delete": 0,
      "send_seperate": true,
      "seperate_num": 100,
      "seperate_minute": 30,
      "is_reserved": true,
      "reserved_date": "2023-07-30 13:00:00",
      "category_name": "기타",
      "use_doc_repository": true
    }
  ]
}

전자 문서 발송인증 필요

저장된 전자문서를 발송요청 합니다.

Response Body

total_receiver_countint필수

발송요청한 수신인 수

successed_receiver_countint필수

발송요청에 성공한 수신인 수

failed_receiver_countint필수

발송요청에 실패한 수신인 수

failed_messagestring · 길이 255

발송요청 실패 건이 있을 때 실패 메시지

send_typestring · 길이 10필수

발송 방법 — INSTANT : 즉시발송, RESERVED : 예약발송

receiver_stateReceiver state array필수

수신인 개별 발신 요청 결과 배열

Receiver state object

타입길이설명
successboolean발송 요청 성공 여부
errmsgstring255발송 요청 실패시 오류 메시지
statestring10발송 요청 상태 (수신인 상태코드 참고)
userUser object발송한 수신인 정보

User object

타입길이설명
seqstring20수신인 번호
phonestring15수신인 전화번호
namestring32수신인 이름
birthdaystring10수신인 생년월일
tx_idstring40수신인 고유 문서 전달 번호 (미 발송시에는 공백)
payloadstring32전달한 페이로드 (최대 32글자)

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E500발송할 문서 번호가 없습니다.
400E200발송할 문서가 없습니다.
400E201이미 발송하신 문서입니다.
400E305발송할 수신인이 없습니다.
POST/api/v1/document/:문서번호Shell · cURL
curl --location --request POST \
  'https://www.paysign.co.kr/api/v1/document/:문서번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
200 · Response
{
  "total_receiver_count": 2,
  "successed_receiver_count": 2,
  "failed_receiver_count": 0,
  "failed_message": "",
  "send_type": "RESERVED",
  "receiver_state": [
    {
      "success": true,
      "errmsg": "",
      "state": "RESERVED",
      "user": {
        "seq": "12345678901234567891",
        "phone": "010-1111-2222",
        "name": "홍길동",
        "birthday": "1993-07-16",
        "tx_id": "",
        "payload": "abcdefjkgkajdkflasdjk"
      }
    }
  ]
}

예약 발송 취소인증 필요

예약발송 등록된 문서의 예약을 취소합니다. 발송이 시작된 이후에는 취소가 불가능합니다.

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E100지정된 문서가 없습니다.
400E300문서번호가 없거나 잘못된 형식입니다.
400E600이미 발송이 시작된 문서입니다.
400E601예약된 문서가 아닙니다.
DELETE/api/v1/document_reserve/:문서번호Shell · cURL
curl --location --request DELETE \
  'https://www.paysign.co.kr/api/v1/document_reserve/:문서번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'

수신인 정보 조회인증 필요

특정 문서의 수신인 정보와 상태를 조회합니다.

URL의 문서번호는 문서 저장시 리턴 받은 문서의 일련번호를 지정합니다.

수신인번호를 생략하면 지정된 문서의 모든 수신자 정보를 조회하고, 수신인번호를 지정하면 지정된 수신인의 정보만 조회합니다.

Response Body

listReceiver object array · 길이 N/A필수

수신인 정보 배열

has_next_pageboolean필수

다음 목록이 있는지 여부

Receiver object

타입길이설명
seqstring20수신인 번호
doc_seqstring20문서 번호
phonestring15수신인 전화번호
namestring32수신인 이름
birthdaystring10수신인 생년월일
send_methodstring1발송방법 (B:카카오 전자문서, P:카카오 페이, D:카카오 페이 내문서함, E:이메일, S:SMS, K:카카오 알림톡)
sender_dataSender data array발송시 입력하였던 발송 변수
tx_idstring40수신인 고유 문서 전달번호 (미 발송시에는 공백)
payloadstring32수신인 페이로드

Sender data object

타입길이설명
field_idstring256템플릿에 명시된 발송변수 위젯 field_id 값
valuestring256위젯에 표시할 값
field_typestring10위젯 종류 (일반, 링크URL, 첨부파일, 청구금액)
field_emptystring10문서 발송시 값이 없는 경우 위젯 처리 방식 (hide, empty)
labelstring128발송변수 위젯의 레이블, 레이블이 없는 경우 위젯 ID

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E400해당 문서가 없습니다.
400E500요청하신 수신인이 없습니다.
GET/api/v1/receiver/:문서번호/[:수신인번호]Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/receiver/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
200 · Response
{
  "has_next_page": false,
  "list": [
    {
      "seq": "12345678901234567890",
      "doc_seq": "98765432109876543210",
      "name": "홍길동",
      "phone": "010-1111-1234",
      "birthday": "1996-02-16",
      "send_method": "B",
      "tx_id": "B-f2d81811a88b1844ef4cdf65462aaaaa",
      "payload": "abcdefghijklmnop1234567890",
      "sender_data": [
        {
          "field_id": "text_2",
          "value": "123,456",
          "field_type": "일반",
          "field_empty": "hide",
          "label": "금액"
        }
      ]
    }
  ]
}

수신인 상태 조회인증 필요

대량의 수신인 정보와 상태를 조회합니다.

요청 본문에 조회할 수신인 번호를 최대 100건까지 요청하여 한꺼번에 조회 가능합니다.

최대 요청가능한 수신인 번호 개수를 초과하면 최대 개수만큼 나눠서 여러 번 요청해 주시기 바랍니다.

Request Body

receiversstring array필수

수신인번호 배열 (최대 100건)

Response Body

receiver_stateReceiver state object array · 길이 N/A필수

요청시 수신인 번호를 명시했을 경우

Receiver state object

타입길이설명
seqstring20수신인 번호
doc_seqstring20문서 번호
statestring10발송 요청 상태 (수신인 상태코드 참고)
errmsgstring255발송 실패시 오류 메시지
sent_atint발송 시각 (unixtime)
request_atint수신 시각 (unixtime)
viewed_atint열람 시각 (unixtime)
completed_atint서명 완료 시각 (unixtime)
expired_atint서명 만료 시각 (unixtime)
generated_pdf_atintPDF문서 생성 시각 (unixtime)
generated_tsa_atint시점확인 타임스탬프 생성 시각 (unixtime)
saved_repository_atint공인전자문서센터 등록 시각 (unixtime)
filled_templateboolean수신인이 템플릿에 데이터 입력 완료 여부
datetime_filledint템플릿에 데이터 입력 완료 시각 (unixtime)
pdf_sizeint생성된 PDF문서 파일 크기 (PDF문서가 없는 경우는 0 반환)
tx_idstring40수신인 고유 문서 전달 번호 (미 발송시는 공백)
payloadstring32수신인 페이로드

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E301요청하신 수신인 목록이 없습니다.
400E500최대 조회 가능 수신인 수를 초과하였습니다.
PUT/api/v1/receiver_stateShell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/receiver_state' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "receivers": [
    "1234567890",
    "1234567891",
    "1234567892",
    "1234567893"
  ]
}
200 · Response
{
  "receivers_state": [
    {
      "seq": "1234567890",
      "doc_seq": "98765432101245",
      "state": "READ",
      "errmsg": "",
      "tx_id": "B-f2d81811a88b1844ef4cdf65462aaaaa",
      "payload": "abcdefghijklmn1234567890",
      "sent_at": 1648175578,
      "request_at": 1648175578,
      "viewed_at": 1648175708,
      "completed_at": 0,
      "expired_at": 0,
      "filled_template": false,
      "datetime_filled": 0,
      "generated_pdf_at": 0,
      "generated_tsa_at": 0,
      "saved_repository_at": 0
    },
    {
      "seq": "1234567891",
      "doc_seq": "98765432101245",
      "state": "COMPLETED",
      "errmsg": "",
      "tx_id": "B-f2d81811a88b1844ef4cdf65462acccd",
      "payload": "",
      "sent_at": 1648175553,
      "request_at": 1648175553,
      "viewed_at": 1648175578,
      "completed_at": 1648175708,
      "expired_at": 0,
      "filled_template": true,
      "datetime_filled": 1648175708,
      "generated_pdf_at": 1648175716,
      "generated_tsa_at": 1648175749,
      "saved_repository_at": 1648175918
    }
  ]
}

수신인 추가 / 정보 변경인증 필요

URL Path에 수신인 번호 지정시에는 미발송 또는 발송 실패한 특정 수신인의 이름, 휴대폰번호, 생년월일, 발송변수 값을 수정합니다.

URL Path에 수신인 번호 미지정시에는 지정된 전자문서에 수신인을 추가 합니다.

참고수신인 정보 변경은 수신인의 상태코드가 TEMP, RESERVED, FAILED 인 경우에만 사용 가능합니다.

Request Body

namestring · 길이 32필수

카카오페이에 가입된 수신인 실명

phonestring · 길이 13필수

수신인 휴대폰 번호. 010-1234-5678 또는 01012345678

birthstring · 길이 10

수신인 생년월일. send_method=B 또는 send_method=P 인 문서의 수신인인 경우 필수

payloadstring · 길이 32

수신인 페이로드

sender_dataSender data array

템플릿에 지정되어 있는 발송변수 실데이터. 생략시 발송변수를 변경하지 않습니다.

Response Body

seqstring · 길이 20필수

수신인 번호

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301수신인 번호가 없습니다.
400E100지정된 문서가 없습니다.
400E101요청하신 수신인이 없습니다.
400E102이미 발송한 수신인 입니다.
400E110수신인 이름이 없습니다.
400E111수신인 전화번호가 없습니다.
400E112수신인 생년월일이 없습니다.
PUT/api/v1/receiver/:문서번호/[:수신인번호]Shell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/receiver/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "name": "홍길동",
  "phone": "010-1234-5678",
  "birth": "1995-12-16",
  "payload": "abcdefghijklmnop1234567890",
  "sender_data": [
    { "field_id": "text_1", "value": "123-456789" },
    { "field_id": "text2", "value": "상품 1" }
  ]
}
200 · Response
{
  "seq": "12345678901234567890"
}

발송 실패 문서 재발송인증 필요

발송 실패한 특정 수신인에게 문서를 재발송 합니다.

발송실패 원인을 파악 후 필요에 따라 수신인 정보 변경 API를 이용하여 수신인의 정보를 변경 후 재발송 합니다.

참고수신인의 상태코드가 TEMP, RESERVED, FAILED, WAIT 인 경우에만 사용 가능합니다.
참고Response body는 전자문서 발송 API와 동일합니다.

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301수신인 번호가 없습니다.
400E100지정된 문서가 없습니다.
400E101요청하신 수신인이 없습니다.
400E102이미 발송한 수신인 입니다.
400E103발송한 적 없는 문서입니다.
POST/api/v1/receiver/:문서번호/:수신인번호Shell · cURL
curl --location --request POST \
  'https://www.paysign.co.kr/api/v1/receiver/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'

수신인 삭제인증 필요

전자문서에서 특정 수신인의 정보를 삭제합니다.

이미 전자문서가 발송된 수신인의 정보를 삭제하면 수신인이 전자문서를 열람할 수 없고 열람시 화면에 오류메시지가 출력됩니다.

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없거나 잘못된 형식입니다.
400E301수신인 번호가 없거나 잘못된 형식입니다.
400E100지정된 문서가 없습니다.
400E101지정된 수신인이 없습니다.
400E102이미 발송한 수신인 입니다.
400E103발송한 적 없는 문서입니다.
DELETE/api/v1/receiver/:문서번호/:수신인번호Shell · cURL
curl --location --request DELETE \
  'https://www.paysign.co.kr/api/v1/receiver/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'

PDF 문서 등록

PAYSIGN에서 생성된 문서가 아닌 일반 PDF문서를 PAYSIGN에 등록하여 관리합니다.

PDF 문서 등록인증 필요

PAYSIGN에서 생성된 문서가 아닌 일반 PDF문서를 PAYSIGN에 등록하여 관리할 수 있도록 합니다.

문서 등록은 REST API를 통해서만 가능합니다.

Request Body

vsubjectstring · 길이 128필수

등록할 문서 제목

use_doc_repositoryboolean

공인전자문서센터 등록 여부

category_namestring · 길이 10

문서분류명

requested_atstring · 길이 32

문서 생성일 (YYYY-MM-DD hh:mm:ss). 생략시 현재 시각으로 등록

completed_atstring · 길이 32

문서 완료일 (YYYY-MM-DD hh:mm:ss). 생략시 현재 시각으로 등록

receiversReceiver data object array필수

수신인 및 PDF 정보 배열

Response Body

doc_seqstring · 길이 20필수

문서 일련번호

receiversReceiver object array필수

등록된 수신인 정보

Receiver data object

타입길이설명
namestring32수신인 이름 · 필수
phonestring12수신인 휴대폰 번호 · 필수
birthstring8수신인 생년월일 (YYYYMMDD 형식)
payloadstring32수신인 페이로드
contentstringN/APDF파일을 Base64 인코딩하여 저장 · 필수

Receiver object (응답)

타입길이설명
seqstring20수신인 일련번호
namestring32수신인 이름
phonestring12수신인 휴대폰 번호
birthstring8수신인 생년월일 (YYYYMMDD 형식)
payloadstring32수신인 페이로드

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E100등록할 문서의 정보 오류
400E300수신인 정보 오류
400E900문서등록 중 예외 상황 발생
PUT/api/v1/regdocShell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/regdoc' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "vsubject": "PDF 문서 등록 API 테스트 2",
  "use_doc_repository": false,
  "webhook_url": null,
  "category_name": "계약서",
  "payload": null,
  "requested_at": "2026-01-01 12:30:25",
  "completed_at": "2026-03-01 12:30:25",
  "receivers": [
    {
      "name": "이양규",
      "phone": "01035558614",
      "birth": "19731216",
      "payload": null,
      "content": "JVBERi0xLjUNCiXi48/TDQo..."
    }
  ]
}
200 · Response
{
  "doc_seq": "1775115063738847362",
  "receivers": [
    {
      "seq": "1775115063746234958",
      "name": "홍길동",
      "phone": "010-1234-5678",
      "birthday": "1996-01-16",
      "payload": ""
    }
  ]
}

문서 보기 URL

임시 저장된 문서나 서명 완료된 문서를 열람할 수 있는 전용 링크를 생성합니다.

문서 열람용 임시 URL 생성인증 필요

임시 저장된 문서나 서명 완료된 문서를 열람할 수 있는 전용 링크를 생성하여 반환합니다.

웹브라우저에서 반환 받은 URL로 접속하면 페이싸인 사이트에 로그인 하지 않고 작성된 문서를 열람할 수 있습니다.

참고임시 URL 생성 후 5분이 지나면 해당 URL은 사용할 수 없습니다. (timeout 으로 조정 가능)

Query Parameters

timeoutint

열람 URL 사용가능 시간 (생략가능). 기본값 5, 최소 1, 최대 60 (단위: 분)

Response Body

linkstring · 길이 N/A필수

접속 URL

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없거나 잘못된 형식입니다.
400E301수신인 번호가 없거나 잘못된 형식입니다.
400E500요청하신 문서가 없습니다.
400E501요청하신 수신인이 없습니다.
400E600링크 정보 저장 중 DB오류가 발생하였습니다.
GET/api/v1/view/:문서번호/:수신인번호Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/view/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
200 · Response
{
  "link": "http://host.server.co.kr/user/link.php?key=2jh4g5j2hg3jc2h3j23jhd3jdg"
}

수신인 데이터 조회

서명 완료된 문서에 수신인이 작성한 데이터와 PDF를 가져옵니다.

수신인 작성 데이터 조회인증 필요

서명 완료된 문서에 수신인이 작성한 데이터를 조회합니다.

수신인 상태 조회 API에서 filled_template 값을 true로 리턴 받은 수신인의 문서만 조회가 가능하고 그 이외에는 수신인 작성 데이터가 존재하지 않기 때문에 오류(E600)를 반환합니다.

Response Body

filled_dataFilled data object array · 길이 N/A필수

수신인이 문서에 입력한 데이터 목록

uploaded_filesFile data object array · 길이 N/A필수

수신인이 문서에 첨부한 파일 목록

signed_imagesFile data object array · 길이 N/A필수

수신인이 문서에 서명한 이미지 목록

Filled data object

타입길이설명
keystring128수신인 입력도구 위젯의 필드명 (필드ID가 아님)
valuestringN/A위젯 입력필드에 수신인이 입력한 데이터 (다중선택(체크박스)의 선택값은 \n으로 구분)

File data object

타입길이설명
keystring128수신인 입력도구 위젯의 필드명 (필드ID가 아님)
filenamestring64파일명
contenttextN/A파일 내용을 BASE64로 인코딩하여 저장
codestring20파일관련 오류코드 (정상시 공백) — READ_FAIL / NOT_FOUND
messagestring128오류 발생시 오류메세지

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301수신인 번호가 없습니다.
400E500요청하신 수신인 정보가 없습니다.
400E600수신인이 데이터 입력을 완료하지 않았습니다.
GET/api/v1/receiver_data/:문서번호/:수신인번호Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/receiver_data/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
200 · Response
{
  "filled_data": [
    { "key": "동의_1", "value": "Y" },
    { "key": "텍스트_1", "value": "2022-03-25" },
    { "key": "텍스트_2", "value": "홍길동" }
  ],
  "uploaded_files": [
    {
      "key": "파일첨부_1",
      "content": "UgAAAzMAAAIgCAYAAACx...",
      "code": "",
      "message": ""
    },
    {
      "key": "파일첨부_2",
      "content": "",
      "code": "READ_FAIL",
      "message": "업로드 된 파일을 읽기 실패하였습니다."
    }
  ],
  "signed_images": [
    {
      "key": "서명_1",
      "content": "iVBORw0KGgoAAAANS...",
      "code": "",
      "message": ""
    }
  ]
}

PDF 문서 다운로드인증 필요

서명 완료된 문서를 PDF 파일로 다운로드 받습니다.

수신인 상태 조회 API에서 generated_tsa_at 값이 0이 아닌 상태에서만 다운로드 가능합니다. (시점확인 서비스 계약을 하지 않은 경우에는 generated_pdf_at 값이 0이 아닌 경우 가능)

참고HTTP Status code가 정상(200)일 때는 PDF 파일의 내용을 Binary로 리턴합니다. 다른 API와 달리 본문이 JSON이 아닌 PDF 내용 그대로 출력됩니다.
참고HTTP Status code가 200이 아닐 경우 JSON 형식의 오류 메시지를 전송합니다.

Response

정상(200)일 때는 PDF 파일 내용을 Binary로 반환합니다. 다른 API와 달리 본문이 JSON이 아니며, 일반 파일 다운로드와 같은 방식의 응답입니다.

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301수신인 번호가 없습니다.
400E500요청하신 수신인 정보가 없습니다.
400E600수신인이 데이터 입력을 완료하지 않았습니다.
400E601PDF파일이 생성되지 않았습니다.
400E602시점확인이 완료되지 않았습니다.
400E603PDF파일이 없습니다.
400E604PDF파일을 읽을 수 없습니다.
GET/api/v1/pdf/:문서번호/:수신인번호Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/pdf/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
오류 응답 예시
{
  "code": "E500",
  "message": "요청하신 수신인이 없습니다."
}

유통증명서 발급

전자문서 유통증명서란, 공인전자주소를 통하여 전자문서가 송신 또는 수신되거나 열람 사실이 포함된 정보(유통정보)를 「전자문서 및 전자거래 기본법」 제22조제1항에 따른 전담기관(정보통신산업진흥원)이 대통령령으로 정하는 방법과 절차에 따라 발급한 증명서입니다.

유통증명서 발급 요청인증 필요

발송 완료된 카카오 전자문서에 대한 유통증명서 발급을 요청합니다.

수신인 일련번호를 전달하지 않는 경우에는 해당 문서 내의 수신인 중 발급 가능한 모든 수신인의 유통증명서를 요청합니다.

참고카카오 전자문서가 아닌 다른 발송방법(알림톡 등)으로 발송된 문서에 대해서는 오류코드가 반환됩니다.
참고문서 발송이 정상적으로 완료되었더라도 전담기관 시스템에 유통 정보가 적재되기 전까지는 유통증명서를 발급할 수 없습니다. 유통 정보는 수신자가 공인전자주소를 등록한 경우 약 1시간 이내에 적재됩니다.
참고발급된 유통증명서는 30일간 서버에 보관되며 보관기간이 지나면 자동 삭제됩니다. 보관기간이 지난 유통증명서를 다운로드 하려면 재요청이 필요합니다.

Request Body

reasonstring · 길이 200필수

증명서 발급 목적 (최대 200자)

receiversstring array

수신인번호 배열 (최대 1000건)

webhook_urlstring

증명서 발급 웹훅 URL

Response Body

resultResult data array · 길이 N/A필수

증명서 발급 요청 결과 배열

Result data object

타입길이설명
successboolean요청 성공 여부
receiver_seqstring20요청한 수신인 일련번호
codestring4오류 발생시 오류코드
messagestring255오류 발생시 오류메시지

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E200요청하신 문서가 없습니다.
400E300문서 번호가 없습니다.
400E301문서 번호가 잘못된 형식입니다.
400E310발급 목적이 없습니다.
400E311발급 목적 글자수가 초과되었습니다.
400E312올바르지 않은 웹훅 URL입니다.

수신인별 발급 요청 결과(Result data)의 오류 코드

codemessage
E501요청하신 수신인이 없습니다.
E600발송이 완료되지 않은 수신인 입니다.
E601카카오 전자문서로 발송되지 않은 수신인 입니다.
E602유통정보 미등록 문서 입니다.
E609증명서 발급대상이 아닙니다.
PUT/api/v1/distributions_cert/:문서번호Shell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/distributions_cert/:문서번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "reason": "발송 문서 증명",
  "receivers": [
    "12345678901234567890",
    "12345678901234567891"
  ]
}
200 · Response
{
  "result": [
    {
      "receiver_seq": "1745399546316953513",
      "success": true,
      "code": "",
      "message": ""
    },
    {
      "receiver_seq": "1745399546316953514",
      "success": false,
      "code": "E600",
      "message": "발송이 완료되지 않은 수신인"
    }
  ]
}

유통증명서 발급 상태 조회인증 필요

유통증명서 발급 요청이 성공한 수신인에 대해 발급 상태를 조회합니다.

Request Body

receiversstring array필수

수신인번호 배열 (최대 1000건)

Response Body

cert_stateState data array · 길이 N/A필수

증명서 발급 요청 결과 배열

State data object

타입길이설명
statestring9발급상태 (COMPLETED / WAIT / FAILED / NOREQ)
receiver_seqstring20요청한 수신인 일련번호
codestring7오류 발생시 오류코드 (state가 FAILED일 경우)
messagestring255오류 발생시 오류메시지 (state가 FAILED일 경우)
request_atint요청시각 (unixtime), 미요청시 0
register_atint발급시각 (unixtime), 미발급시 0
filesizeint증명서 파일 크기, 미발급시 0

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300요청하신 수신인 번호가 없습니다.
400E301최대 조회 가능 수신인 수를 초과하였습니다.

발급 오류 코드 (발급상태 코드가 FAILED일 경우)

codemessage
E500증명서 발급요청을 하지 않은 수신인입니다.
E400_00필수값 누락
E404_00요청 정보를 찾을 수 없습니다. 문서를 찾을 수 없습니다.
E404_01유통 정보가 적재되지 않았습니다.
E429_00최대 요청 횟수 초과
E503_00서버 점검 중으로 서비스 이용이 불가능합니다. KISA 서버 점검 중입니다.
PUT/api/v1/distributions_cert_stateShell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/distributions_cert_state' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "receivers": [
    "12345678901234567890",
    "12345678901234567891"
  ]
}
200 · Response
{
  "cert_state": [
    {
      "receiver_seq": "1745399546316953513",
      "state": "COMPLETED",
      "request_at": 1747986430,
      "register_at": 1747987801,
      "filesize": 36442,
      "code": "",
      "message": ""
    },
    {
      "receiver_seq": "1745399546316953515",
      "state": "FAILED",
      "request_at": 1747986430,
      "register_at": 0,
      "filesize": 0,
      "code": "E404_00",
      "message": "요청 정보를 찾을 수 없습니다."
    }
  ]
}

유통증명서 다운로드인증 필요

발급 완료된 증명서를 PDF 파일로 다운로드 받습니다.

증명서 발급 상태가 COMPLETED 인 경우에만 다운로드 가능하며 그 이외에는 E600 오류가 반환됩니다.

참고HTTP Status code가 정상(200)일 때는 PDF 파일의 내용을 Binary로 리턴합니다.

Response

정상(200)일 때는 PDF 파일 내용을 Binary로 반환합니다. 다른 API와 달리 본문이 JSON이 아니며, 일반 파일 다운로드와 같은 방식의 응답입니다.

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301문서 번호가 잘못된 형식입니다.
400E302수신인 번호가 없습니다.
400E303수신인 번호가 잘못된 형식입니다.
400E500요청하신 문서가 없습니다.
400E501요청하신 수신인이 없습니다.
400E520증명서를 요청하지 않은 수신인입니다.
400E523발급된 증명서 파일이 없습니다.
400E600증명서 발급이 완료되지 않았습니다.
400E604증명서 파일을 읽을 수 없습니다.
GET/api/v1/distributions_cert/:문서번호/:수신인번호Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/distributions_cert/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
오류 응답 예시
{
  "code": "E520",
  "message": "증명서를 요청하지 않은 수신인입니다."
}

공인전자문서 증명서 발급

공인전자문서 증명서란, 국가에서 인증받은 전자문서 보관기관인 공인전자문서센터에 저장된 전자문서로 안전한 보관 및 내용변경이 없는 원본임을 증명하는 문서입니다.

공인전자문서 증명서 발급 요청인증 필요

공인전자문서센터에 저장된 문서의 증명서 발급을 요청합니다.

수신인 일련번호를 전달하지 않는 경우에는 해당 문서 내의 수신인 중 발급 가능한 모든 수신인의 공인전자문서 증명서를 요청합니다.

참고발급된 공인전자문서 증명서는 30일간 서버에 보관되며 보관기간이 지나면 자동 삭제됩니다.

Request Body

reasonstring · 길이 200필수

증명서 발급 목적 (최대 200자)

receiversstring array

수신인번호 배열 (최대 1000건)

webhook_urlstring

증명서 발급 웹훅 URL

Response Body

resultResult data array · 길이 N/A필수

증명서 발급 요청 결과 배열

Result data object

타입길이설명
successboolean요청 성공 여부
receiver_seqstring20요청한 수신인 일련번호
codestring4오류 발생시 오류코드
messagestring255오류 발생시 오류메시지

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E200요청하신 문서가 없습니다.
400E300문서 번호가 없습니다.
400E310발급 목적이 없습니다.
400E311발급 목적 글자수가 초과되었습니다.
400E312올바르지 않은 웹훅 URL입니다.

수신인별 발급 요청 결과(Result data)의 오류 코드

codemessage
E600공인전자문서센터를 사용할 수 없습니다.
E601공인전자문서센터 미등록 문서입니다.
E602공인전자문서센터에 저장되지 않은 수신인입니다.
PUT/api/v1/document_cert/:문서번호Shell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/document_cert/:문서번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "reason": "전자문서 원본 증명",
  "receivers": [
    "12345678901234567890",
    "12345678901234567891"
  ]
}
200 · Response
{
  "result": [
    {
      "receiver_seq": "1745399546316953513",
      "success": true,
      "code": "",
      "message": ""
    },
    {
      "receiver_seq": "1745399546316953514",
      "success": false,
      "code": "E602",
      "message": "공인전자문서센터에 저장되지 않은 수신인입니다."
    }
  ]
}

공인전자문서 증명서 발급 상태 조회인증 필요

공인전자문서 증명서 발급 요청이 성공한 수신인에 대해 발급 상태를 조회합니다.

Request Body

receiversstring array필수

수신인번호 배열 (최대 1000건)

Response Body

cert_stateState data array · 길이 N/A필수

증명서 발급 요청 결과 배열

State data object

타입길이설명
statestring9발급상태 (COMPLETED / WAIT / FAILED / NOREQ)
receiver_seqstring20요청한 수신인 일련번호
codestring7오류 발생시 오류코드 (state가 FAILED일 경우)
messagestring255오류 발생시 오류메시지 (state가 FAILED일 경우)
request_atint요청시각 (unixtime), 미요청시 0
register_atint발급시각 (unixtime), 미발급시 0
filesizeint증명서 파일 크기, 미발급시 0

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300요청하신 수신인 번호가 없습니다.
400E301최대 조회 가능 수신인 수를 초과하였습니다.

발급 오류 코드 (발급상태 코드가 FAILED일 경우)

codemessage
E500증명서 발급요청을 하지 않은 수신인입니다.
ESYS파일시스템 오류
ED00증명서 발급 실패
ED98증명서 발급 오류 (Exception)
ED99원본 문서 조회 실패
PUT/api/v1/document_cert_stateShell · cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/document_cert_state' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "receivers": [
    "12345678901234567890",
    "12345678901234567891"
  ]
}
200 · Response
{
  "cert_state": [
    {
      "receiver_seq": "1745399546316953513",
      "state": "COMPLETED",
      "request_at": 1747986430,
      "register_at": 0,
      "filesize": 0,
      "code": "",
      "message": ""
    },
    {
      "receiver_seq": "1745399546316953515",
      "state": "FAILED",
      "request_at": 1747986430,
      "register_at": 0,
      "filesize": 0,
      "code": "ED99",
      "message": "요청 문서ID에 해당하는 원본문서를 검색할 수 없습니다."
    }
  ]
}

공인전자문서 증명서 다운로드인증 필요

발급 완료된 증명서를 PDF 파일로 다운로드 받습니다.

증명서 발급 상태가 COMPLETED 인 경우에만 다운로드 가능하며 그 이외에는 E600 오류가 반환됩니다.

참고HTTP Status code가 정상(200)일 때는 PDF 파일의 내용을 Binary로 리턴합니다.

Response

정상(200)일 때는 PDF 파일 내용을 Binary로 반환합니다. 다른 API와 달리 본문이 JSON이 아니며, 일반 파일 다운로드와 같은 방식의 응답입니다.

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301문서 번호가 잘못된 형식입니다.
400E302수신인 번호가 없습니다.
400E303수신인 번호가 잘못된 형식입니다.
400E500요청하신 문서가 없습니다.
400E501요청하신 수신인이 없습니다.
400E505공인전자문서센터에 등록하지 않은 문서입니다.
400E506공인전자문서센터에 등록되지 않은 수신인입니다.
400E520증명서를 요청하지 않은 수신인입니다.
400E523발급된 증명서 파일이 없습니다.
400E600증명서 발급이 완료되지 않았습니다.
400E604증명서 파일을 읽을 수 없습니다.
GET/api/v1/document_cert/:문서번호/:수신인번호Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/document_cert/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
오류 응답 예시
{
  "code": "E520",
  "message": "증명서를 요청하지 않은 수신인입니다."
}

감사추적 증명서 발급

문서 발송부터 완료까지의 진행 이력을 기록한 전자증명서입니다. 발급 신청 과정은 없고 다운로드 요청을 하면 현재 상태의 추적 증명서를 즉시 다운로드 받을 수 있습니다.

감사추적 증명서 다운로드인증 필요

지정된 수신인에 대한 증명서를 PDF 파일로 다운로드 받습니다.

참고발급 신청 과정 없이 즉시 다운로드 가능합니다.
참고HTTP Status code가 정상(200)일 때는 PDF 파일의 내용을 Binary로 리턴합니다.

Response

정상(200)일 때는 PDF 파일 내용을 Binary로 반환합니다. 다른 API와 달리 본문이 JSON이 아니며, 일반 파일 다운로드와 같은 방식의 응답입니다.

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301문서 번호가 잘못된 형식입니다.
400E302수신인 번호가 없습니다.
400E303수신인 번호가 잘못된 형식입니다.
400E500요청하신 문서가 없습니다.
400E501요청하신 수신인이 없습니다.
400E502증명서 파일 생성에 실패하였습니다.
400E604생성된 증명서 파일을 읽을 수 없습니다.
GET/api/v1/trace_cert/:문서번호/:수신인번호Shell · cURL
curl --location --request GET \
  'https://www.paysign.co.kr/api/v1/trace_cert/:문서번호/:수신인번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json'
오류 응답 예시
{
  "code": "E500",
  "message": "요청하신 문서가 없습니다."
}

독촉알림 발송

문서를 수신 후 열람하지 않은 수신인 또는 열람 후 완료하지 않은 수신인에게 문서를 열람 또는 완료하기를 알리는 별도의 문자 메시지를 전송합니다.

독촉알림 발송인증 필요

미열람 또는 미완료 수신인에게 독촉 알림을 발송합니다.

참고발송완료 후 미열람 또는 미완료 수신인 중 만료시간이 1시간 이상 남은 수신인에게만 발송되며 LMS(장문 SMS)로 발송됩니다.

Request Body

receiversstring array필수

수신인번호 배열 (최대 100건)

Response Body

countint필수

발송한 건수

read_chaseup_countint필수

열람 촉 건수

submit_chaseup_countint필수

완료 독촉 건수

sent_receiver_seq_listarray필수

발송한 수신인 일련번호 배열

응답 코드

공통 응답 코드 이외에 아래 코드가 있습니다.

HTTP Statuscodemessage
400E300문서 번호가 없습니다.
400E301문서 번호가 잘못된 형식입니다.
400E302수신인 번호가 없습니다.
400E200해당문서가 없습니다.
400E556독촉알림 발송 템플릿파일을 열 수 없습니다.(시스템오류)
POST/api/v1/chaseup/:문서번호Shell · cURL
curl --location --request POST \
  'https://www.paysign.co.kr/api/v1/chaseup/:문서번호' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{...'
Request Body
{
  "receivers": [
    "1234567890",
    "1234567891",
    "1234567892"
  ]
}
200 · Response
{
  "count": 3,
  "read_chaseup_count": 2,
  "submit_chaseup_count": 1,
  "sent_receiver_seq_list": [
    "1234567890",
    "1234567891",
    "1234567892"
  ]
}

웹훅 URL

문서 수신인의 상태가 변경되거나 증명서 발급이 끝나면 지정한 URL로 상태 정보를 전달합니다. 웹훅 URL은 http 또는 https 프로토콜만 지원합니다.

필수수신인 상태정보를 처리하는 고객사의 웹훅 수신 페이지에서는 정상 처리시 반드시 OK (따옴표 제외)를 결과 페이지에 표시해야 합니다. OK 이외의 결과 또는 공백 등은 수신측 페이지 오류로 간주하고 최대 7일간 재전송을 시도합니다.

문서 상태 웹훅 파라미터

아래 파라미터를 query string (GET)으로 전달합니다. 비동기식으로 전송하므로 순서는 보장하지 않습니다. 예를 들어 SENT가 READ보다 늦게 수신될 수 있습니다.

변수명설명
typereceiver_state 값 고정
doc_seq문서 일련번호
receiver_seq수신인 일련번호
receiver_state상태 코드
message발송 실패시 오류메시지

증명서 발급 웹훅 파라미터

변수명설명
type증명서 종류 (DIST : 유통증명서, ORGDOC : 공인전자문서 증명서)
doc_seq문서 일련번호
receiver_seq수신인 일련번호
cert_state상태 코드
request_at발급요청일 (unixtime stamp)
message발급 실패시 오류메시지

증명서 웹훅 상태 코드

코드상태
FAILED발급 실패
COMPLETED발급 완료
EXPIRED보유 기한만료
문서 상태 웹훅 호출 예
GET https://{웹훅URL}
  ?type=receiver_state
  &doc_seq=1234
  &receiver_seq=5678
  &receiver_state=READ
증명서 웹훅 호출 예
GET https://{웹훅URL}
  ?type=DIST
  &doc_seq=1234
  &receiver_seq=5678
  &cert_state=COMPLETED
수신 페이지 응답
OK

언어별 호출 예제

호출하는 API에 따라 GET · PUT · POST · DELETE 중 알맞은 메서드를 지정하세요. 모든 요청에는 Api-IdAuthorization 헤더가 필요합니다.

참고아래 예제의 {발급받은 API아이디} · {발급받은 API토큰} 자리에 실제 발급값을 넣어 사용합니다.
cURL
curl --location --request PUT \
  'https://www.paysign.co.kr/api/v1/document/{문서번호}' \
  --header 'Api-Id: {발급받은 API아이디}' \
  --header 'Authorization: Bearer {발급받은 API토큰}' \
  --header 'Content-Type: application/json' \
  --data '{"vsubject":"계약서"}'
PHP · cURL
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://www.paysign.co.kr/api/v1/document/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => 'PUT',
  CURLOPT_POSTFIELDS     => json_encode($body),
  CURLOPT_HTTPHEADER     => [
    'Api-Id: {발급받은 API아이디}',
    'Authorization: Bearer {발급받은 API토큰}',
    'Content-Type: application/json',
  ],
]);
$res = curl_exec($ch);
curl_close($ch);
Java · OkHttp
OkHttpClient client = new OkHttpClient();
RequestBody body = RequestBody.create(
    json, MediaType.parse("application/json"));
Request request = new Request.Builder()
    .url("https://www.paysign.co.kr/api/v1/document/")
    .put(body)
    .addHeader("Api-Id", "{발급받은 API아이디}")
    .addHeader("Authorization", "Bearer {발급받은 API토큰}")
    .addHeader("Content-Type", "application/json")
    .build();
Response response = client.newCall(request).execute();
C# · RestSharp
var client = new RestClient(
    "https://www.paysign.co.kr/api/v1/document/");
var request = new RestRequest(Method.PUT);
request.AddHeader("Api-Id", "{발급받은 API아이디}");
request.AddHeader("Authorization", "Bearer {발급받은 API토큰}");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", json,
    ParameterType.RequestBody);
IRestResponse response = client.Execute(request);