싸인딜 개발자

API 참조

싸인딜 REST API, OAuth, MCP discovery 명세입니다. 실제 데이터 접근은 OAuth scope 또는 API key 로 보호됩니다. 이 페이지는 /openapi.json(버전 v1)에서 자동으로 만들었어요. 총 41개 요청이에요.

OpenAPI JSON 원본 · 인증은 Authorization: Bearer …(OAuth 토큰 또는 API 키)예요. *는 필수예요.

목차

요청 목록

GET/healthz

Health check

응답

상태설명본문 속성
200성공 응답—

POST/mcp

MCP Streamable HTTP JSON-RPC endpoint

응답

상태설명본문 속성
200JSON-RPC response—
401OAuth protected resource challenge—

GET/api/contracts

List contracts

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

응답

상태설명본문 속성
200성공 응답—

POST/api/contracts

Create contract draft metadata

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

응답

상태설명본문 속성
201성공 응답—

GET/api/contracts/{id}

Get contract detail

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
200성공 응답—
404성공 응답—

POST/api/contracts/{id}/signers

Add signer

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
201성공 응답—

POST/api/contracts/{id}:ready

Mark draft ready

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
200성공 응답—

POST/api/contracts/{id}:send

Dry-run or send signature request

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring
Idempotency-Key *headerstring

응답

상태설명본문 속성
200성공 응답—
402Payment required—

POST/api/contracts/{id}:void

Void sent contract

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
200성공 응답—

GET/api/contracts/{id}/document

Get completed document metadata

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
200성공 응답—

POST/api/signers/{sid}/verify:start

Start signer verification

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
sid *pathstring

응답

상태설명본문 속성
200성공 응답—

POST/api/signers/{sid}/verify:check

Check signer verification

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
sid *pathstring

응답

상태설명본문 속성
200성공 응답—

POST/api/signers/{sid}/sign

Record signer signature

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
sid *pathstring

응답

상태설명본문 속성
200성공 응답—

POST/api/signers/{sid}/decline

Decline signing request

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
sid *pathstring

응답

상태설명본문 속성
200성공 응답—

GET/api/templates

List templates (with field schema + send example)

시스템 표준양식 + 내 조직 템플릿 목록. PDF 업로드 양식은 fields[](key/label/data_type/required/fill_by/pii)와 send_example(POST /api/contracts:send_from_template 복붙용 요청 예시)을 함께 반환 — AI 에이전트는 이걸로 필드 키·JSON 양식을 파악한다.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

응답

상태설명본문 속성
200templates with fields[] and send_example for engine=pdf—

POST/api/templates

Create template (text body, or uploaded PDF via document_ref)

{ name, contract_type, body_text?, category? } → 글 양식. document_ref("sha256:<hex>" — POST /api/documents 응답)가 있으면 { name, contract_type, document_ref, roles?, fields?, category? } → 업로드 PDF 양식(칸·역할 = 서명칸 엔진 검증 · 값 저장 안 함 · 판 1 + 감사). 오류: document_ref_invalid · document_not_found(404, 다른 조직 포함) · roles_invalid · role_unknown · field_out_of_page · field_overlap · missing_signature_field · field_value_not_allowed 등 엔진 code(GET /api/contracts:send_document 오류 표와 같은 이름).

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

요청 본문

이름타입·제약설명
name *string
contract_type *string
body_textstring글 양식 본문(document_ref 없을 때)
categorystring
document_refstringPDF 양식 — POST /api/documents 의 document_ref
rolesarray[{id,label,side:"sender"|"recipient",order?}] (PDF 양식)
fieldsarray[{type,role,page,x,y,w,h,key?,label?,required?}] 0~1·왼쪽 위 (PDF 양식 · value 금지)

응답

상태설명본문 속성
201{ template_id, name, contract_type } 또는 PDF 양식 { template_id, engine:"pdf", document_ref, layout }—
404document_not_found—
422엔진·입력 검증 오류—

GET/api/templates/{id}

Get template detail (fields, send example, PDF layout)

양식 상세. 시스템 HR 양식은 값 목록(fields)·quick_send_example, 업로드 PDF 양식은 이름 붙은 text 칸(fields)과 layout{ version, pages, roles[{id,label,side,order?}], fields[{type,role,page,x,y,w,h,key?,label?,required?,fill_by}], layout_hash } — PUT /fields 와 같은 꼴.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
200성공 응답—
404성공 응답—

PUT/api/templates/{id}/fields

Replace uploaded-PDF template fields (new immutable version)

{ fields, roles? } — 서명칸 엔진 검증(좌표 0~1·왼쪽 위·쪽 1부터·≤60칸). 양식에는 값을 저장하지 않는다(value → field_value_not_allowed). 바뀌면 새 판(template_versions) + 감사 template.version_created, 같으면 unchanged:true. 시스템 양식 403 template_readonly · PDF 양식 아님 422 template_not_pdf.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

요청 본문

이름타입·제약설명
fields *array
rolesarray

응답

상태설명본문 속성
200{ template_id, unchanged, saved_version?, version, pages, roles, fields, layout_hash }—
403template_readonly—
404성공 응답—
422엔진 검증 오류—

PUT/api/templates/{id}/roles

Rename / reorder uploaded-PDF template roles (fields unchanged)

{ roles } — 수신 역할 수가 지금 칸 배치와 같아야 한다(아니면 roles_shape_mismatch). 새 판 + 감사. 저장된 역할은 이후 발송 서명자 role_id·라벨로 쓰인다.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

요청 본문

이름타입·제약설명
roles *array

응답

상태설명본문 속성
200성공 응답—
403template_readonly—
404성공 응답—
422roles_invalid · roles_shape_mismatch—

GET/api/templates/{id}/versions

List template versions (immutable)

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
200{ template_id, current_version, versions[{version,source,field_count,pdf_sha256,created_at}] }—
404성공 응답—

POST/api/documents

Upload a PDF → document_ref

multipart/form-data(file) 또는 JSON { pdf_base64, file_name? }. 5MB(pdf_too_large) · %PDF-/읽기(pdf_invalid) · 1~30쪽(pdf_no_pages·pdf_too_many_pages) · 회전 쪽(pdf_rotated). 같은 조직이 이미 올린 같은 PDF 는 200 reused:true(다시 저장 안 함), 새로 저장하면 201. document_ref 는 POST /api/contracts:send_document(mode sign_pdf)·POST /api/templates 에 쓴다. 스코프 contract:draft.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

요청 본문

이름타입·제약설명
pdf_base64 *string
file_namestring

응답

상태설명본문 속성
200{ document_ref, sha256, pages, page_sizes_pt, bytes, reused:true }—
201{ document_ref, sha256, pages, page_sizes_pt, bytes, reused:false }—
422pdf_too_large · pdf_invalid · pdf_no_pages · pdf_too_many_pages · pdf_rotated · field_required—

GET/api/usage

Usage, free quota, credit balance, org_verified

발송 사용량·가입 무료 건수(1회성) 잔여·충전 잔여·next_send_price_krw·requires_purchase + org_verified(false 면 발송이 402 org_unverified).

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

응답

상태설명본문 속성
200성공 응답—

GET/api/contracts/{id}/pdf

Download contract PDF (final, or base with kind=base)

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring
kindquerystring
enum: base
base = 서명 전 원본(base_pdf). 생략 = 체결본(final_pdf, 없으면 base 로 폴백)
strict_finalquerystring
enum: 1
1 = 체결본이 없으면 base 로 폴백하지 않고 404

응답

상태설명본문 속성
200PDF—
404성공 응답—

GET/api/contracts/{id}/deliveries/{trackingId}

Delivery status (per recipient channel)

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring
trackingId *pathstring

응답

상태설명본문 속성
200성공 응답—
404계약 없음 또는 tracking_id 불일치—

GET/api/integrations/webhooks

List webhooks

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

응답

상태설명본문 속성
200{ data:[{ integration_id, url, events, status, … }] }—

POST/api/integrations/webhooks

Register webhook (HMAC-SHA256 X-SignDeal-Signature: sha256=<hex>)

{ url, secret? } — 이벤트 contract.sent·contract.completed·contract.declined·contract.voided. 잘못된 설정은 422 webhook_config_invalid. 스코프 contract:send.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

요청 본문

이름타입·제약설명
url *string
secretstring

응답

상태설명본문 속성
201{ integration_id }—
422webhook_config_invalid—

DELETE/api/integrations/webhooks/{id}

Delete webhook

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
204삭제됨—
404성공 응답—

POST/api/send

Send a contract in one call (API key only)

가장 짧은 발송. Authorization: Bearer sk_… 와 본문 하나면 끝난다 — dry_run·confirmation_token·Idempotency-Key 불필요. 서버가 내부에서 미리보기와 확인 토큰을 처리한다. template 은 GET /api/templates 에서 api_sendable=true 인 양식(내 PDF 양식, HR 양식, 서명자 2명 구성의 시스템 양식). ref 를 주면 그 값으로, 안 주면 내용 지문으로 중복 발송을 막는다. preview:true 면 발송 없이 미리보기만 반환.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

요청 본문

이름타입·제약설명
template *stringGET /api/templates 의 template_id
to *object받는 사람 1명. phone 또는 email 중 1개 필수.
to.name *string
to.phonestring
to.emailstring
valuesobject양식 입력값. 키=fields[].key
refstring자사 식별자(영문·숫자·._:-, 128자 이하). 웹훅에 그대로 돌아온다.
titlestring
previewboolean
default: false
true=발송하지 않고 채워진 값만 확인
expires_in_daysinteger
minimum: 1 · maximum: 30 · default: 7

응답

상태설명본문 속성
200preview:true 일 때 미리보기—
202contract_id, tracking_id, status, billing, delivery—

POST/api/contracts:send_from_template

Send from my PDF template (data-merge, dry_run → confirm)

내 조직이 업로드한 PDF 양식(engine=pdf)으로 단일 호출 발송. 2단계 안전 흐름: ① dry_run:true(기본) → resolved_fields 미리보기 + confirmation_token 반환(부작용 없음) ② 같은 본문 + dry_run:false + confirmation_token → 실발송. field_values 의 키는 GET /api/templates 의 fields[].key(또는 한글 label). 타 조직 템플릿은 404.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
Idempotency-Key *headerstring재시도 안전 멱등키(필수)

요청 본문

이름타입·제약설명
template_id *stringGET /api/templates 의 template_id(내 조직 PDF 양식만)
dry_runboolean
default: true
true=미리보기+confirmation_token, false=실발송(토큰 필수)
confirmation_tokenstringdry_run 응답 토큰 — 실발송 시 필수(스냅샷 불일치·만료 시 거부)
channelstring
default: "auto"
발송 채널(auto=알림톡 우선→SMS 폴백)
sign_modestring
enum: parallel | sequential · default: "parallel"
titlestring계약 제목(생략 시 양식 이름)
expires_in_daysinteger
minimum: 1 · maximum: 30 · default: 7
recipients *array<object>
minItems: 1
recipients[].name *string
recipients[].phonestring휴대폰(권장 — 본인확인 앵커). phone 또는 email 중 1개 필수
recipients[].emailstring
field_valuesobject발신자(fill_by=sender) 필드 값 맵. 키=fields[].key 또는 한글 label. 수신자 필드는 서명 시 수신자가 입력.

응답

상태설명본문 속성
200dry_run preview(resolved_fields, confirmation_token) 또는 발송 결과(contract_id, sign_links)—

POST/api/contracts:send_document

Send a finished document (sign | deliver_pdf | sign_pdf, dry_run → confirm)

발신 시스템이 완성한 문서를 그대로 발송. mode=sign: 값이 채워진 마크다운(body_markdown, 허용 토큰은 {{sig|seal|date:role}} 뿐 — 그 밖의 {{…}} 는 422) + roles[](is_sender 1개) → 발신 역할 자동 직인 후 서명 요청. mode=deliver_pdf: pdf_base64(%PDF-, 5MB 이하) → 받은 PDF 를 그대로 체결 정본으로 보존하고 completed 로 기록, 수령인 1명에게 열람 링크(SMS) 전달. mode=sign_pdf: 올린 PDF 그대로(pdf_base64 ≤5MB 또는 document_ref "sha256:…") + roles[{id,label,side:sender|recipient,order?}] + fields[{type:signature|seal|date|text|checkbox, role, page(1부터), x,y,w,h(0~1·왼쪽 위 원점), key?, label?, required?, value?(sender text)}](≤60) → 발신 칸은 PDF 에 얹고(값·직인) 수신 역할에 서명 요청. 용지 밖 field_out_of_page · 다른 역할 칸 겹침 field_overlap · 수신 역할 서명칸 없음 missing_signature_field. dry_run 응답의 layout_hash 가 확인표에 묶인다(미리보기 뒤 칸을 바꾸면 다시 dry_run). preview_document:"pdf" 면 미리보기 PDF. dry_run(기본 true) → confirmation_token → 실발송. client_ref 로 멱등 재생.

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
Idempotency-Key *headerstring재시도 안전 멱등키(필수)

요청 본문

이름타입·제약설명
mode *string
enum: sign | deliver_pdf | sign_pdf
document_kindstring
enum: employment_contract | certificate | company_form | agreement | other
sign=employment_contract · deliver_pdf=certificate · sign_pdf=company_form(기본)|agreement|employment_contract|other
title *string
maxLength: 200
body_markdownstringmode=sign 전용 — 채워진 v2 마크다운 본문
rolesarraymode=sign — [{role_id,label,is_sender?}] · mode=sign_pdf — [{id,label,side:"sender"|"recipient",order?}] (sender ≤1, recipient ≥1)
pdf_base64stringmode=deliver_pdf·sign_pdf — PDF(base64, 5MB 이하, 회전 없는 쪽)
document_refstringmode=sign_pdf — 이미 올린 PDF 재사용 "sha256:<64hex>"(dry_run 응답의 document_ref). pdf_base64 와 둘 중 하나
fieldsarray<object>
maxItems: 60
mode=sign_pdf — 서명·도장·입력 칸. 좌표는 쪽 크기 대비 0~1 비율·왼쪽 위 원점(TemplateFieldBox). sender text 칸은 value 필수
fields[].type *string
enum: signature | seal | date | text | checkbox
fields[].role *string
fields[].page *integer
minimum: 1
fields[].x *number
minimum: 0 · maximum: 1
fields[].y *number
minimum: 0 · maximum: 1
fields[].w *number
minimum: 0.01 · maximum: 1
fields[].h *number
minimum: 0.008 · maximum: 1
fields[].keystring
fields[].labelstring
fields[].requiredboolean
fields[].valuestring
maxLength: 500
preview_documentstring
enum: pdf
mode=sign_pdf + dry_run — 발신 칸을 얹은 미리보기 PDF 를 돌려준다
certificate_nostringmode=deliver_pdf 필수 — 발급번호(감사 기록)
subjectobject문서 당사자(근로자·증명 대상자) 이름·휴대폰 — recipients[0] 과 정확히 같아야 하고, mode=sign 은 본문 수신 역할 서명란에 이름이 있어야 한다(오발송 방지). sign·deliver_pdf 필수, sign_pdf 는 employment_contract 일 때 필수(그 밖은 주면 대조)
recipients *array<object>
minItems: 1
channelstring
default: "auto"
client_refstring외부 원장 키(영문·숫자·._:-, 128자 이하)
dry_runboolean
default: true
confirmation_tokenstring
expires_in_daysinteger
minimum: 1 · maximum: 30 · default: 7
include_sealboolean
default: true
mode=sign — false 면 사업주 자동 서명을 직인 없이 회사명 텍스트로
employer_seal_imagestringmode=sign·sign_pdf(선택) — 발신 시스템에 등록된 회사 전자인감 이미지. data:image/png;base64,… 또는 data:image/jpeg;base64,… (매직바이트 검증, 디코드 300KB 이하, 그 밖은 422 employer_seal_image_invalid/_too_large). 있으면 사업주 자동 직인에 이 이미지를 그대로 쓰고, 없으면 싸인딜 등록 직인 → 회사명 생성 도장 순. 확인 토큰 지문에 포함되므로 dry_run 과 confirm 에 같은 값을 보내야 한다.

응답

상태설명본문 속성
200dry_run preview + confirmation_token—
202발송 결과(contract_id, status, final_pdf_available 등)—
400오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `invalid_json` — 본문이 JSON 이 아님 - `invalid_body` — 본문이 JSON 객체가 아님—
401오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `tenant_unresolved` — Bearer 토큰(sk_/oat_)이 없거나 무효—
402오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `org_unverified` (확정 단계) — 조직에 이메일·휴대폰 인증을 마친 사용자가 없음 - `payment_method_required` (확정 단계) — 무료·충전 발송권 모두 소진—
403오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `insufficient_scope` — 토큰에 contract:send 권한 없음—
404오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `document_not_found` [sign_pdf] — document_ref 의 PDF 가 이 조직에 없음(다른 조직 포함) - `not_found` (확정 단계) — 대상 리소스 없음(도메인 not_found — 다른 조직 은폐 포함)—
409오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `document_ref_mismatch` [sign_pdf] — 저장된 PDF 해시가 document_ref 와 다름 - `storage_unavailable` [sign_pdf] (확정 단계) — 문서 저장소(R2) 바인딩 없음 - `idempotency_conflict` (확정 단계) — 같은 client_ref 또는 Idempotency-Key 가 다른 요청 내용에 이미 쓰임 - `idempotency_incomplete` (확정 단계) — 같은 client_ref 의 이전/동시 요청이 아직 끝나지 않음(retryable) - `sender_unresolved` (확정 단계) — 조직 발신자(대표 사용자)를 찾을 수 없음 - `sender_phone_required` [deliver_pdf] (확정 단계) — 조직 대표 사용자의 휴대폰 미등록 - `billing_failed` (확정 단계) — 정산 단계 예기치 않은 오류(원상복구됨 · retryable) - `invalid_state` (확정 단계) — 계약 상태가 발송할 수 없는 상태(도메인) - `illegal_transition` (확정 단계) — 허용되지 않는 상태 전이(도메인)—
422오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code: - `idempotency_key_required` — Idempotency-Key 헤더 없음 - `body_too_large` — 본문 JSON 이 7,300,000자 초과 - `field_required` — 필수 문자열 없음(title · sign 의 body_markdown · deliver_pdf/sign_pdf 의 pdf_base64) — field 로 구분 - `title_invalid` — title 공백이거나 200자 초과 - `client_ref_invalid` — client_ref 가 영문·숫자·._:- 128자 이하가 아님 - `expires_in_days_invalid` — expires_in_days 가 1~30 정수가 아님 - `too_many_items` — recipients 500명 초과 - `recipient_invalid` — 수신자 이름 없음/100자 초과 또는 휴대폰·이메일 둘 다 없음 - `recipient_phone_invalid` — 수신자 휴대폰 형식 오류 - `recipient_email_invalid` — 수신자 이메일 형식 오류 - `recipients_required` — recipients 0명 - `mode_invalid` — mode 가 sign·deliver_pdf·sign_pdf 가 아님 - `document_kind_invalid` — mode 와 맞지 않는 document_kind - `subject_required` [sign·deliver_pdf·sign_pdf] — subject(이름 2자 이상·휴대폰) 없음/형식 오류 — sign_pdf 는 employment_contract 이거나 subject 를 보낸 경우 - `single_recipient_required` [sign·deliver_pdf·sign_pdf] — 수신자 2명 이상(sign·deliver_pdf 항상 · sign_pdf 는 employment_contract) - `recipients_roles_mismatch` [sign·sign_pdf] — 수신 역할 수와 recipients 수가 다름 / recipients[].role 이 역할과 1:1 이 아님 - `employer_seal_image_invalid` [sign·sign_pdf] — employer_seal_image 가 PNG/JPEG data URL 이 아님(매직바이트) - `employer_seal_image_too_large` [sign·sign_pdf] — employer_seal_image 디코드 300KB 초과 - `employer_seal_image_not_applicable` [deliver_pdf·sign_pdf] — deliver_pdf 에 보냄 / sign_pdf 인데 발신 역할(side:sender) 없음 - `preview_document_invalid` — preview_document 가 sign_pdf 의 "pdf" 가 아님 - `preview_requires_dry_run` [sign_pdf] — preview_document:"pdf" 와 dry_run:false 를 함께 보냄 - `roles_invalid` [sign·sign_pdf] — roles 개수·role id 형식·라벨·중복·발신 역할 수 오류(sign: is_sender 정확히 1 · sign_pdf: sender ≤1·recipient ≥1) - `field_too_long` [sign] — body_markdown 200,000자 초과 - `unresolved_placeholder` [sign] — 본문에 {{sig|seal|date:role}} 외의 {{…}} 가 남음 - `role_undeclared` [sign] — 본문 토큰의 역할이 roles 에 없음 - `date_token_duplicate` [sign] — 같은 역할의 {{date:role}} 가 2번 이상 - `role_signature_missing` [sign] — 역할의 {{sig:role}}·{{seal:role}} 가 본문에 없음 - `recipient_contract_mismatch` [sign·sign_pdf] — subject 와 수신자 이름·휴대폰이 다름 / sign 은 본문 수신 역할 서명란에 subject 이름이 없음 - `channel_invalid` [deliver_pdf] — channel 이 'sms'·'auto' 가 아님 - `recipient_document_mismatch` [deliver_pdf] — subject 와 수령인 이름·휴대폰이 다름 - `certificate_no_required` [deliver_pdf] — certificate_no 없음 - `certificate_no_invalid` [deliver_pdf] — certificate_no 형식·길이 오류 - `pdf_too_large` [deliver_pdf·sign_pdf] — PDF 5MB 초과(base64 길이 또는 디코드 바이트) - `pdf_invalid` [deliver_pdf·sign_pdf] — base64 아님 / 디코드 불가 / %PDF- 머리글 없음 / 손상·암호화로 읽기 실패 - `pdf_no_pages` [deliver_pdf·sign_pdf] — PDF 쪽 수 0 - `document_source_ambiguous` [sign_pdf] — pdf_base64 와 document_ref 를 둘 다 보냄 - `document_ref_invalid` [sign_pdf] — document_ref 가 "sha256:<64 hex>" 가 아님 - `pdf_rotated` [sign_pdf] — 회전(/Rotate)된 쪽이 있는 PDF - `recipient_role_required` [sign_pdf] — recipients[].role 을 일부만 넣음 - `fields_required` [sign_pdf] — fields 가 비었거나 배열이 아님 - `too_many_fields` [sign_pdf] — 칸 60개 초과 - `field_invalid` [sign_pdf] — 칸이 객체가 아님 / x·y·w·h 숫자 아님 / dataType·fontSize(4~24)·align 오류 - `field_type_invalid` [sign_pdf] — type 이 signature·seal·date·text·checkbox 가 아님 - `role_unknown` [sign_pdf] — 칸의 role 이 roles 에 없음 - `field_side_mismatch` [sign_pdf] — 칸의 side 가 역할의 side 와 다름 - `field_out_of_page` [sign_pdf] — page 가 1~쪽수 밖 / x,y<0 또는 x+w>1 또는 y+h>1(0~1 왼쪽 위 비율) - `field_too_small` [sign_pdf] — 너비 0.01 · 높이 0.008 미만 - `field_type_not_allowed` [sign_pdf] — 발신 역할에 checkbox 칸 - `field_key_invalid` [sign_pdf] — key 가 영문 소문자로 시작하는 소문자·숫자·_ 40자 이하가 아님 - `field_key_duplicate` [sign_pdf] — 같은 key 2번 - `field_value_not_allowed` [sign_pdf] — 발신 text 칸이 아닌 곳에 value - `field_value_invalid` [sign_pdf] — value 가 문자열이 아니거나 500자 초과 - `field_value_required` [sign_pdf] — 발신 text 칸에 value 없음(빈칸 발송 방지) - `field_overlap` [sign_pdf] — 다른 역할의 칸끼리 겹침 - `missing_signature_field` [sign_pdf] — 수신 역할에 signature·seal 칸이 없음 - `confirmation_required` (확정 단계) — confirmation_token 없음·만료·위조·이미 사용 - `confirmation_payload_mismatch` (확정 단계) — 미리보기 뒤 요청 내용(sign_pdf 는 칸·역할·문서 layout_hash 포함)이 바뀜 - `invalid_input` [sign_pdf] (확정 단계) — 계약 생성 시 받는 사람/역할 수 불일치(도메인) - `sender_signature_unavailable` [sign_pdf] (확정 단계) — 발신 서명·도장 칸 이미지를 만들지 못함(employer_seal_image 없고 기본 서명 렌더 실패) - `merge_render_failed` [sign_pdf] (확정 단계) — 발신 text 값(한글)을 PDF 에 굽지 못함(문서 렌더 일시 오류) - `no_deliverable_recipient` (확정 단계) — 전달 가능한 수신 채널(휴대폰·이메일·설정) 없음—

GET/api/registry/tools

Tool registry

응답

상태설명본문 속성
200성공 응답—

GET/api/registry/tools/{name}

Tool registry item

매개변수

이름위치타입설명
name *pathstring

응답

상태설명본문 속성
200성공 응답—

GET/api/registry/categories

Tool categories

응답

상태설명본문 속성
200성공 응답—

GET/api/approvals

List HITL approvals

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.

응답

상태설명본문 속성
200성공 응답—

POST/api/approvals/{id}/decide

Approve or reject HITL request

매개변수

이름위치타입설명
X-Org-Idheaderstring선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.
id *pathstring

응답

상태설명본문 속성
200성공 응답—

GET/oauth/authorize

OAuth authorization endpoint

응답

상태설명본문 속성
302Login/consent redirect—

POST/oauth/token

OAuth token endpoint

응답

상태설명본문 속성
200성공 응답—

POST/oauth/register

Dynamic client registration

응답

상태설명본문 속성
201성공 응답—

POST/oauth/revoke

OAuth token revocation

응답

상태설명본문 속성
200Revoked or ignored—

POST/oauth/introspect

OAuth token introspection

응답

상태설명본문 속성
200RFC 7662 active token response—

GET/ai/tools

AI-readable Tool Registry alias

응답

상태설명본문 속성
200성공 응답—