API 참조
싸인딜 REST API, OAuth, MCP discovery 명세입니다. 실제 데이터 접근은 OAuth scope 또는 API key 로 보호됩니다. 이 페이지는 /openapi.json(버전 v1)에서 자동으로 만들었어요. 총 41개 요청이에요.
OpenAPI JSON 원본 · 인증은 Authorization: Bearer …(OAuth 토큰 또는 API 키)예요. *는 필수예요.
https://api.signdeal.kr— REST API and OAuth-adjacent API endpointshttps://mcp.signdeal.kr— MCP Streamable HTTP endpoint hosthttps://app.signdeal.kr— Human web app host
목차
- GET
/healthz - POST
/mcp - GET
/api/contracts - POST
/api/contracts - GET
/api/contracts/{id} - POST
/api/contracts/{id}/signers - POST
/api/contracts/{id}:ready - POST
/api/contracts/{id}:send - POST
/api/contracts/{id}:void - GET
/api/contracts/{id}/document - POST
/api/signers/{sid}/verify:start - POST
/api/signers/{sid}/verify:check - POST
/api/signers/{sid}/sign - POST
/api/signers/{sid}/decline - GET
/api/templates - POST
/api/templates - GET
/api/templates/{id} - PUT
/api/templates/{id}/fields - PUT
/api/templates/{id}/roles - GET
/api/templates/{id}/versions - POST
/api/documents - GET
/api/usage - GET
/api/contracts/{id}/pdf - GET
/api/contracts/{id}/deliveries/{trackingId} - GET
/api/integrations/webhooks - POST
/api/integrations/webhooks - DELETE
/api/integrations/webhooks/{id} - POST
/api/send - POST
/api/contracts:send_from_template - POST
/api/contracts:send_document - GET
/api/registry/tools - GET
/api/registry/tools/{name} - GET
/api/registry/categories - GET
/api/approvals - POST
/api/approvals/{id}/decide - GET
/oauth/authorize - POST
/oauth/token - POST
/oauth/register - POST
/oauth/revoke - POST
/oauth/introspect - GET
/ai/tools
요청 목록
GET/healthz
Health check
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/mcp
MCP Streamable HTTP JSON-RPC endpoint
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | JSON-RPC response | — |
401 | OAuth protected resource challenge | — |
GET/api/contracts
List contracts
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/api/contracts
Create contract draft metadata
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
201 | 성공 응답 | — |
GET/api/contracts/{id}
Get contract detail
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
404 | 성공 응답 | — |
POST/api/contracts/{id}/signers
Add signer
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
201 | 성공 응답 | — |
POST/api/contracts/{id}:ready
Mark draft ready
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/api/contracts/{id}:send
Dry-run or send signature request
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string | |
Idempotency-Key * | header | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
402 | Payment required | — |
POST/api/contracts/{id}:void
Void sent contract
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
GET/api/contracts/{id}/document
Get completed document metadata
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/api/signers/{sid}/verify:start
Start signer verification
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
sid * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/api/signers/{sid}/verify:check
Check signer verification
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
sid * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/api/signers/{sid}/sign
Record signer signature
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
sid * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/api/signers/{sid}/decline
Decline signing request
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
sid * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | templates 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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
name * | string | |
contract_type * | string | |
body_text | string | 글 양식 본문(document_ref 없을 때) |
category | string | |
document_ref | string | PDF 양식 — POST /api/documents 의 document_ref |
roles | array | [{id,label,side:"sender"|"recipient",order?}] (PDF 양식) |
fields | array | [{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 } | — |
404 | document_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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
fields * | array | |
roles | array |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | { template_id, unchanged, saved_version?, version, pages, roles, fields, layout_hash } | — |
403 | template_readonly | — |
404 | 성공 응답 | — |
422 | 엔진 검증 오류 | — |
PUT/api/templates/{id}/roles
Rename / reorder uploaded-PDF template roles (fields unchanged)
{ roles } — 수신 역할 수가 지금 칸 배치와 같아야 한다(아니면 roles_shape_mismatch). 새 판 + 감사. 저장된 역할은 이후 발송 서명자 role_id·라벨로 쓰인다.
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
roles * | array |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
403 | template_readonly | — |
404 | 성공 응답 | — |
422 | roles_invalid · roles_shape_mismatch | — |
GET/api/templates/{id}/versions
List template versions (immutable)
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
pdf_base64 * | string | |
file_name | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | { document_ref, sha256, pages, page_sizes_pt, bytes, reused:true } | — |
201 | { document_ref, sha256, pages, page_sizes_pt, bytes, reused:false } | — |
422 | pdf_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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
GET/api/contracts/{id}/pdf
Download contract PDF (final, or base with kind=base)
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string | |
kind | query | stringenum: base | base = 서명 전 원본(base_pdf). 생략 = 체결본(final_pdf, 없으면 base 로 폴백) |
strict_final | query | stringenum: 1 | 1 = 체결본이 없으면 base 로 폴백하지 않고 404 |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | — | |
404 | 성공 응답 | — |
GET/api/contracts/{id}/deliveries/{trackingId}
Delivery status (per recipient channel)
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string | |
trackingId * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
404 | 계약 없음 또는 tracking_id 불일치 | — |
GET/api/integrations/webhooks
List webhooks
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — 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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
url * | string | |
secret | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
201 | { integration_id } | — |
422 | webhook_config_invalid | — |
DELETE/api/integrations/webhooks/{id}
Delete webhook
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
template * | string | GET /api/templates 의 template_id |
to * | object | 받는 사람 1명. phone 또는 email 중 1개 필수. |
to.name * | string | |
to.phone | string | |
to.email | string | |
values | object | 양식 입력값. 키=fields[].key |
ref | string | 자사 식별자(영문·숫자·._:-, 128자 이하). 웹훅에 그대로 돌아온다. |
title | string | |
preview | booleandefault: false | true=발송하지 않고 채워진 값만 확인 |
expires_in_days | integerminimum: 1 · maximum: 30 · default: 7 |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | preview:true 일 때 미리보기 | — |
202 | contract_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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
Idempotency-Key * | header | string | 재시도 안전 멱등키(필수) |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
template_id * | string | GET /api/templates 의 template_id(내 조직 PDF 양식만) |
dry_run | booleandefault: true | true=미리보기+confirmation_token, false=실발송(토큰 필수) |
confirmation_token | string | dry_run 응답 토큰 — 실발송 시 필수(스냅샷 불일치·만료 시 거부) |
channel | stringdefault: "auto" | 발송 채널(auto=알림톡 우선→SMS 폴백) |
sign_mode | stringenum: parallel | sequential · default: "parallel" | |
title | string | 계약 제목(생략 시 양식 이름) |
expires_in_days | integerminimum: 1 · maximum: 30 · default: 7 | |
recipients * | array<object>minItems: 1 | |
recipients[].name * | string | |
recipients[].phone | string | 휴대폰(권장 — 본인확인 앵커). phone 또는 email 중 1개 필수 |
recipients[].email | string | |
field_values | object | 발신자(fill_by=sender) 필드 값 맵. 키=fields[].key 또는 한글 label. 수신자 필드는 서명 시 수신자가 입력. |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | dry_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-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
Idempotency-Key * | header | string | 재시도 안전 멱등키(필수) |
요청 본문
| 이름 | 타입·제약 | 설명 |
|---|---|---|
mode * | stringenum: sign | deliver_pdf | sign_pdf | |
document_kind | stringenum: employment_contract | certificate | company_form | agreement | other | sign=employment_contract · deliver_pdf=certificate · sign_pdf=company_form(기본)|agreement|employment_contract|other |
title * | stringmaxLength: 200 | |
body_markdown | string | mode=sign 전용 — 채워진 v2 마크다운 본문 |
roles | array | mode=sign — [{role_id,label,is_sender?}] · mode=sign_pdf — [{id,label,side:"sender"|"recipient",order?}] (sender ≤1, recipient ≥1) |
pdf_base64 | string | mode=deliver_pdf·sign_pdf — PDF(base64, 5MB 이하, 회전 없는 쪽) |
document_ref | string | mode=sign_pdf — 이미 올린 PDF 재사용 "sha256:<64hex>"(dry_run 응답의 document_ref). pdf_base64 와 둘 중 하나 |
fields | array<object>maxItems: 60 | mode=sign_pdf — 서명·도장·입력 칸. 좌표는 쪽 크기 대비 0~1 비율·왼쪽 위 원점(TemplateFieldBox). sender text 칸은 value 필수 |
fields[].type * | stringenum: signature | seal | date | text | checkbox | |
fields[].role * | string | |
fields[].page * | integerminimum: 1 | |
fields[].x * | numberminimum: 0 · maximum: 1 | |
fields[].y * | numberminimum: 0 · maximum: 1 | |
fields[].w * | numberminimum: 0.01 · maximum: 1 | |
fields[].h * | numberminimum: 0.008 · maximum: 1 | |
fields[].key | string | |
fields[].label | string | |
fields[].required | boolean | |
fields[].value | stringmaxLength: 500 | |
preview_document | stringenum: pdf | mode=sign_pdf + dry_run — 발신 칸을 얹은 미리보기 PDF 를 돌려준다 |
certificate_no | string | mode=deliver_pdf 필수 — 발급번호(감사 기록) |
subject | object | 문서 당사자(근로자·증명 대상자) 이름·휴대폰 — recipients[0] 과 정확히 같아야 하고, mode=sign 은 본문 수신 역할 서명란에 이름이 있어야 한다(오발송 방지). sign·deliver_pdf 필수, sign_pdf 는 employment_contract 일 때 필수(그 밖은 주면 대조) |
recipients * | array<object>minItems: 1 | |
channel | stringdefault: "auto" | |
client_ref | string | 외부 원장 키(영문·숫자·._:-, 128자 이하) |
dry_run | booleandefault: true | |
confirmation_token | string | |
expires_in_days | integerminimum: 1 · maximum: 30 · default: 7 | |
include_seal | booleandefault: true | mode=sign — false 면 사업주 자동 서명을 직인 없이 회사명 텍스트로 |
employer_seal_image | string | mode=sign·sign_pdf(선택) — 발신 시스템에 등록된 회사 전자인감 이미지. data:image/png;base64,… 또는 data:image/jpeg;base64,… (매직바이트 검증, 디코드 300KB 이하, 그 밖은 422 employer_seal_image_invalid/_too_large). 있으면 사업주 자동 직인에 이 이미지를 그대로 쓰고, 없으면 싸인딜 등록 직인 → 회사명 생성 도장 순. 확인 토큰 지문에 포함되므로 dry_run 과 confirm 에 같은 값을 보내야 한다. |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | dry_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 * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
GET/api/registry/categories
Tool categories
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
GET/api/approvals
List HITL approvals
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/api/approvals/{id}/decide
Approve or reject HITL request
매개변수
| 이름 | 위치 | 타입 | 설명 |
|---|---|---|---|
X-Org-Id | header | string | 선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다. |
id * | path | string |
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
GET/oauth/authorize
OAuth authorization endpoint
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
302 | Login/consent redirect | — |
POST/oauth/token
OAuth token endpoint
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |
POST/oauth/register
Dynamic client registration
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
201 | 성공 응답 | — |
POST/oauth/revoke
OAuth token revocation
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | Revoked or ignored | — |
POST/oauth/introspect
OAuth token introspection
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | RFC 7662 active token response | — |
GET/ai/tools
AI-readable Tool Registry alias
응답
| 상태 | 설명 | 본문 속성 |
|---|---|---|
200 | 성공 응답 | — |