{"openapi":"3.1.0","info":{"title":"SignDeal API","version":"v1","description":"싸인딜 REST API, OAuth, MCP discovery 명세입니다. 실제 데이터 접근은 OAuth scope 또는 API key 로 보호됩니다."},"servers":[{"url":"https://api.signdeal.kr","description":"REST API and OAuth-adjacent API endpoints"},{"url":"https://mcp.signdeal.kr","description":"MCP Streamable HTTP endpoint host"},{"url":"https://app.signdeal.kr","description":"Human web app host"}],"externalDocs":{"description":"AI Documentation","url":"https://signdeal.kr/docs/ai"},"security":[{"OAuth2":["contract:read","contract:draft","contract:send","document:read"]},{"ApiKeyBearer":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://auth.signdeal.kr/oauth/authorize","tokenUrl":"https://auth.signdeal.kr/oauth/token","scopes":{"contract:read":"계약 목록과 상태를 조회합니다.","contract:draft":"계약 초안 생성, 서명자 추가, 서명필드 배치를 수행합니다.","contract:send":"명시적 승인 후 서명 요청을 발송합니다.","document:read":"체결 완료 문서 메타데이터와 다운로드 URL을 조회합니다."}}}},"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"sk_live or oat"}}},"paths":{"/healthz":{"get":{"summary":"Health check","responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/mcp":{"post":{"summary":"MCP Streamable HTTP JSON-RPC endpoint","security":[{"OAuth2":["contract:read","contract:draft","contract:send","document:read"]},{"ApiKeyBearer":[]}],"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"OAuth protected resource challenge","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts":{"get":{"summary":"List contracts","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"summary":"Create contract draft metadata","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}}],"responses":{"201":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts/{id}":{"get":{"summary":"Get contract detail","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts/{id}/signers":{"post":{"summary":"Add signer","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts/{id}:ready":{"post":{"summary":"Mark draft ready","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts/{id}:send":{"post":{"summary":"Dry-run or send signature request","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts/{id}:void":{"post":{"summary":"Void sent contract","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts/{id}/document":{"get":{"summary":"Get completed document metadata","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/signers/{sid}/verify:start":{"post":{"summary":"Start signer verification","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"sid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/signers/{sid}/verify:check":{"post":{"summary":"Check signer verification","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"sid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/signers/{sid}/sign":{"post":{"summary":"Record signer signature","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"sid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/signers/{sid}/decline":{"post":{"summary":"Decline signing request","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"sid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/templates":{"get":{"summary":"List templates (with field schema + send example)","description":"시스템 표준양식 + 내 조직 템플릿 목록. PDF 업로드 양식은 fields[](key/label/data_type/required/fill_by/pii)와 send_example(POST /api/contracts:send_from_template 복붙용 요청 예시)을 함께 반환 — AI 에이전트는 이걸로 필드 키·JSON 양식을 파악한다.","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}}],"responses":{"200":{"description":"templates with fields[] and send_example for engine=pdf","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"summary":"Create template","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}}],"responses":{"201":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/send":{"post":{"summary":"Send a contract in one call (API key only)","description":"가장 짧은 발송. Authorization: Bearer sk_… 와 본문 하나면 끝난다 — dry_run·confirmation_token·Idempotency-Key 불필요. 서버가 내부에서 미리보기와 확인 토큰을 처리한다. template 은 GET /api/templates 에서 api_sendable=true 인 양식(내 PDF 양식, HR 양식, 서명자 2명 구성의 시스템 양식). ref 를 주면 그 값으로, 안 주면 내용 지문으로 중복 발송을 막는다. preview:true 면 발송 없이 미리보기만 반환.","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template","to"],"properties":{"template":{"type":"string","description":"GET /api/templates 의 template_id"},"to":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}},"description":"받는 사람 1명. phone 또는 email 중 1개 필수."},"values":{"type":"object","additionalProperties":{"type":"string"},"description":"양식 입력값. 키=fields[].key"},"ref":{"type":"string","description":"자사 식별자(영문·숫자·._:-, 128자 이하). 웹훅에 그대로 돌아온다."},"title":{"type":"string"},"preview":{"type":"boolean","default":false,"description":"true=발송하지 않고 채워진 값만 확인"},"expires_in_days":{"type":"integer","minimum":1,"maximum":30,"default":7}}}}}},"responses":{"200":{"description":"preview:true 일 때 미리보기","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"contract_id, tracking_id, status, billing, delivery","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts:send_from_template":{"post":{"summary":"Send from my PDF template (data-merge, dry_run → confirm)","description":"내 조직이 업로드한 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.","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"재시도 안전 멱등키(필수)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template_id","recipients"],"properties":{"template_id":{"type":"string","description":"GET /api/templates 의 template_id(내 조직 PDF 양식만)"},"dry_run":{"type":"boolean","default":true,"description":"true=미리보기+confirmation_token, false=실발송(토큰 필수)"},"confirmation_token":{"type":"string","description":"dry_run 응답 토큰 — 실발송 시 필수(스냅샷 불일치·만료 시 거부)"},"channel":{"type":"string","default":"auto","description":"발송 채널(auto=알림톡 우선→SMS 폴백)"},"sign_mode":{"type":"string","enum":["parallel","sequential"],"default":"parallel"},"title":{"type":"string","description":"계약 제목(생략 시 양식 이름)"},"expires_in_days":{"type":"integer","minimum":1,"maximum":30,"default":7},"recipients":{"type":"array","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"phone":{"type":"string","description":"휴대폰(권장 — 본인확인 앵커). phone 또는 email 중 1개 필수"},"email":{"type":"string"}}}},"field_values":{"type":"object","additionalProperties":{"type":"string"},"description":"발신자(fill_by=sender) 필드 값 맵. 키=fields[].key 또는 한글 label. 수신자 필드는 서명 시 수신자가 입력."}}}}}},"responses":{"200":{"description":"dry_run preview(resolved_fields, confirmation_token) 또는 발송 결과(contract_id, sign_links)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/contracts:send_document":{"post":{"summary":"Send a finished document (sign | deliver_pdf | sign_pdf, dry_run → confirm)","description":"발신 시스템이 완성한 문서를 그대로 발송. 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 로 멱등 재생.","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"재시도 안전 멱등키(필수)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode","title","recipients"],"properties":{"mode":{"type":"string","enum":["sign","deliver_pdf","sign_pdf"]},"document_kind":{"type":"string","enum":["employment_contract","certificate","company_form","agreement","other"],"description":"sign=employment_contract · deliver_pdf=certificate · sign_pdf=company_form(기본)|agreement|employment_contract|other"},"title":{"type":"string","maxLength":200},"body_markdown":{"type":"string","description":"mode=sign 전용 — 채워진 v2 마크다운 본문"},"roles":{"type":"array","description":"mode=sign — [{role_id,label,is_sender?}] · mode=sign_pdf — [{id,label,side:\"sender\"|\"recipient\",order?}] (sender ≤1, recipient ≥1)"},"pdf_base64":{"type":"string","description":"mode=deliver_pdf·sign_pdf — PDF(base64, 5MB 이하, 회전 없는 쪽)"},"document_ref":{"type":"string","description":"mode=sign_pdf — 이미 올린 PDF 재사용 \"sha256:<64hex>\"(dry_run 응답의 document_ref). pdf_base64 와 둘 중 하나"},"fields":{"type":"array","maxItems":60,"description":"mode=sign_pdf — 서명·도장·입력 칸. 좌표는 쪽 크기 대비 0~1 비율·왼쪽 위 원점(TemplateFieldBox). sender text 칸은 value 필수","items":{"type":"object","required":["type","role","page","x","y","w","h"],"properties":{"type":{"type":"string","enum":["signature","seal","date","text","checkbox"]},"role":{"type":"string"},"page":{"type":"integer","minimum":1},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0.01,"maximum":1},"h":{"type":"number","minimum":0.008,"maximum":1},"key":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"value":{"type":"string","maxLength":500}}}},"preview_document":{"type":"string","enum":["pdf"],"description":"mode=sign_pdf + dry_run — 발신 칸을 얹은 미리보기 PDF 를 돌려준다"},"certificate_no":{"type":"string","description":"mode=deliver_pdf 필수 — 발급번호(감사 기록)"},"subject":{"type":"object","required":["name","phone"],"description":"문서 당사자(근로자·증명 대상자) 이름·휴대폰 — recipients[0] 과 정확히 같아야 하고, mode=sign 은 본문 수신 역할 서명란에 이름이 있어야 한다(오발송 방지). sign·deliver_pdf 필수, sign_pdf 는 employment_contract 일 때 필수(그 밖은 주면 대조)"},"recipients":{"type":"array","minItems":1,"items":{"type":"object","required":["name"]}},"channel":{"type":"string","default":"auto"},"client_ref":{"type":"string","description":"외부 원장 키(영문·숫자·._:-, 128자 이하)"},"dry_run":{"type":"boolean","default":true},"confirmation_token":{"type":"string"},"expires_in_days":{"type":"integer","minimum":1,"maximum":30,"default":7},"include_seal":{"type":"boolean","default":true,"description":"mode=sign — false 면 사업주 자동 서명을 직인 없이 회사명 텍스트로"},"employer_seal_image":{"type":"string","description":"mode=sign·sign_pdf(선택) — 발신 시스템에 등록된 회사 전자인감 이미지. data:image/png;base64,… 또는 data:image/jpeg;base64,… (매직바이트 검증, 디코드 300KB 이하, 그 밖은 422 employer_seal_image_invalid/_too_large). 있으면 사업주 자동 직인에 이 이미지를 그대로 쓰고, 없으면 싸인딜 등록 직인 → 회사명 생성 도장 순. 확인 토큰 지문에 포함되므로 dry_run 과 confirm 에 같은 값을 보내야 한다."}}}}}},"responses":{"200":{"description":"dry_run preview + confirmation_token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"발송 결과(contract_id, status, final_pdf_available 등)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:\n- `invalid_json` — 본문이 JSON 이 아님\n- `invalid_body` — 본문이 JSON 객체가 아님","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:\n- `tenant_unresolved` — Bearer 토큰(sk_/oat_)이 없거나 무효","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:\n- `org_unverified` (확정 단계) — 조직에 이메일·휴대폰 인증을 마친 사용자가 없음\n- `payment_method_required` (확정 단계) — 무료·충전 발송권 모두 소진","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:\n- `insufficient_scope` — 토큰에 contract:send 권한 없음","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:\n- `document_not_found` [sign_pdf] — document_ref 의 PDF 가 이 조직에 없음(다른 조직 포함)\n- `not_found` (확정 단계) — 대상 리소스 없음(도메인 not_found — 다른 조직 은폐 포함)","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:\n- `document_ref_mismatch` [sign_pdf] — 저장된 PDF 해시가 document_ref 와 다름\n- `storage_unavailable` [sign_pdf] (확정 단계) — 문서 저장소(R2) 바인딩 없음\n- `idempotency_conflict` (확정 단계) — 같은 client_ref 또는 Idempotency-Key 가 다른 요청 내용에 이미 쓰임\n- `idempotency_incomplete` (확정 단계) — 같은 client_ref 의 이전/동시 요청이 아직 끝나지 않음(retryable)\n- `sender_unresolved` (확정 단계) — 조직 발신자(대표 사용자)를 찾을 수 없음\n- `sender_phone_required` [deliver_pdf] (확정 단계) — 조직 대표 사용자의 휴대폰 미등록\n- `billing_failed` (확정 단계) — 정산 단계 예기치 않은 오류(원상복구됨 · retryable)\n- `invalid_state` (확정 단계) — 계약 상태가 발송할 수 없는 상태(도메인)\n- `illegal_transition` (확정 단계) — 허용되지 않는 상태 전이(도메인)","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"오류 봉투 { error: { type, code, message, request_id, retryable, field? } }. code:\n- `idempotency_key_required` — Idempotency-Key 헤더 없음\n- `body_too_large` — 본문 JSON 이 7,300,000자 초과\n- `field_required` — 필수 문자열 없음(title · sign 의 body_markdown · deliver_pdf/sign_pdf 의 pdf_base64) — field 로 구분\n- `title_invalid` — title 공백이거나 200자 초과\n- `client_ref_invalid` — client_ref 가 영문·숫자·._:- 128자 이하가 아님\n- `expires_in_days_invalid` — expires_in_days 가 1~30 정수가 아님\n- `too_many_items` — recipients 500명 초과\n- `recipient_invalid` — 수신자 이름 없음/100자 초과 또는 휴대폰·이메일 둘 다 없음\n- `recipient_phone_invalid` — 수신자 휴대폰 형식 오류\n- `recipient_email_invalid` — 수신자 이메일 형식 오류\n- `recipients_required` — recipients 0명\n- `mode_invalid` — mode 가 sign·deliver_pdf·sign_pdf 가 아님\n- `document_kind_invalid` — mode 와 맞지 않는 document_kind\n- `subject_required` [sign·deliver_pdf·sign_pdf] — subject(이름 2자 이상·휴대폰) 없음/형식 오류 — sign_pdf 는 employment_contract 이거나 subject 를 보낸 경우\n- `single_recipient_required` [sign·deliver_pdf·sign_pdf] — 수신자 2명 이상(sign·deliver_pdf 항상 · sign_pdf 는 employment_contract)\n- `recipients_roles_mismatch` [sign·sign_pdf] — 수신 역할 수와 recipients 수가 다름 / recipients[].role 이 역할과 1:1 이 아님\n- `employer_seal_image_invalid` [sign·sign_pdf] — employer_seal_image 가 PNG/JPEG data URL 이 아님(매직바이트)\n- `employer_seal_image_too_large` [sign·sign_pdf] — employer_seal_image 디코드 300KB 초과\n- `employer_seal_image_not_applicable` [deliver_pdf·sign_pdf] — deliver_pdf 에 보냄 / sign_pdf 인데 발신 역할(side:sender) 없음\n- `preview_document_invalid` — preview_document 가 sign_pdf 의 \"pdf\" 가 아님\n- `preview_requires_dry_run` [sign_pdf] — preview_document:\"pdf\" 와 dry_run:false 를 함께 보냄\n- `roles_invalid` [sign·sign_pdf] — roles 개수·role id 형식·라벨·중복·발신 역할 수 오류(sign: is_sender 정확히 1 · sign_pdf: sender ≤1·recipient ≥1)\n- `field_too_long` [sign] — body_markdown 200,000자 초과\n- `unresolved_placeholder` [sign] — 본문에 {{sig|seal|date:role}} 외의 {{…}} 가 남음\n- `role_undeclared` [sign] — 본문 토큰의 역할이 roles 에 없음\n- `date_token_duplicate` [sign] — 같은 역할의 {{date:role}} 가 2번 이상\n- `role_signature_missing` [sign] — 역할의 {{sig:role}}·{{seal:role}} 가 본문에 없음\n- `recipient_contract_mismatch` [sign·sign_pdf] — subject 와 수신자 이름·휴대폰이 다름 / sign 은 본문 수신 역할 서명란에 subject 이름이 없음\n- `channel_invalid` [deliver_pdf] — channel 이 'sms'·'auto' 가 아님\n- `recipient_document_mismatch` [deliver_pdf] — subject 와 수령인 이름·휴대폰이 다름\n- `certificate_no_required` [deliver_pdf] — certificate_no 없음\n- `certificate_no_invalid` [deliver_pdf] — certificate_no 형식·길이 오류\n- `pdf_too_large` [deliver_pdf·sign_pdf] — PDF 5MB 초과(base64 길이 또는 디코드 바이트)\n- `pdf_invalid` [deliver_pdf·sign_pdf] — base64 아님 / 디코드 불가 / %PDF- 머리글 없음 / 손상·암호화로 읽기 실패\n- `pdf_no_pages` [deliver_pdf·sign_pdf] — PDF 쪽 수 0\n- `document_source_ambiguous` [sign_pdf] — pdf_base64 와 document_ref 를 둘 다 보냄\n- `document_ref_invalid` [sign_pdf] — document_ref 가 \"sha256:<64 hex>\" 가 아님\n- `pdf_rotated` [sign_pdf] — 회전(/Rotate)된 쪽이 있는 PDF\n- `recipient_role_required` [sign_pdf] — recipients[].role 을 일부만 넣음\n- `fields_required` [sign_pdf] — fields 가 비었거나 배열이 아님\n- `too_many_fields` [sign_pdf] — 칸 60개 초과\n- `field_invalid` [sign_pdf] — 칸이 객체가 아님 / x·y·w·h 숫자 아님 / dataType·fontSize(4~24)·align 오류\n- `field_type_invalid` [sign_pdf] — type 이 signature·seal·date·text·checkbox 가 아님\n- `role_unknown` [sign_pdf] — 칸의 role 이 roles 에 없음\n- `field_side_mismatch` [sign_pdf] — 칸의 side 가 역할의 side 와 다름\n- `field_out_of_page` [sign_pdf] — page 가 1~쪽수 밖 / x,y<0 또는 x+w>1 또는 y+h>1(0~1 왼쪽 위 비율)\n- `field_too_small` [sign_pdf] — 너비 0.01 · 높이 0.008 미만\n- `field_type_not_allowed` [sign_pdf] — 발신 역할에 checkbox 칸\n- `field_key_invalid` [sign_pdf] — key 가 영문 소문자로 시작하는 소문자·숫자·_ 40자 이하가 아님\n- `field_key_duplicate` [sign_pdf] — 같은 key 2번\n- `field_value_not_allowed` [sign_pdf] — 발신 text 칸이 아닌 곳에 value\n- `field_value_invalid` [sign_pdf] — value 가 문자열이 아니거나 500자 초과\n- `field_value_required` [sign_pdf] — 발신 text 칸에 value 없음(빈칸 발송 방지)\n- `field_overlap` [sign_pdf] — 다른 역할의 칸끼리 겹침\n- `missing_signature_field` [sign_pdf] — 수신 역할에 signature·seal 칸이 없음\n- `confirmation_required` (확정 단계) — confirmation_token 없음·만료·위조·이미 사용\n- `confirmation_payload_mismatch` (확정 단계) — 미리보기 뒤 요청 내용(sign_pdf 는 칸·역할·문서 layout_hash 포함)이 바뀜\n- `invalid_input` [sign_pdf] (확정 단계) — 계약 생성 시 받는 사람/역할 수 불일치(도메인)\n- `sender_signature_unavailable` [sign_pdf] (확정 단계) — 발신 서명·도장 칸 이미지를 만들지 못함(employer_seal_image 없고 기본 서명 렌더 실패)\n- `merge_render_failed` [sign_pdf] (확정 단계) — 발신 text 값(한글)을 PDF 에 굽지 못함(문서 렌더 일시 오류)\n- `no_deliverable_recipient` (확정 단계) — 전달 가능한 수신 채널(휴대폰·이메일·설정) 없음","content":{"application/json":{"schema":{"type":"object"}}}}},"x-signdeal-error-codes":[{"status":401,"code":"tenant_unresolved","modes":["all"],"when":"Bearer 토큰(sk_/oat_)이 없거나 무효"},{"status":403,"code":"insufficient_scope","modes":["all"],"when":"토큰에 contract:send 권한 없음"},{"status":422,"code":"idempotency_key_required","modes":["all"],"when":"Idempotency-Key 헤더 없음"},{"status":400,"code":"invalid_json","modes":["all"],"when":"본문이 JSON 이 아님"},{"status":400,"code":"invalid_body","modes":["all"],"when":"본문이 JSON 객체가 아님"},{"status":422,"code":"body_too_large","modes":["all"],"when":"본문 JSON 이 7,300,000자 초과"},{"status":422,"code":"field_required","modes":["all"],"when":"필수 문자열 없음(title · sign 의 body_markdown · deliver_pdf/sign_pdf 의 pdf_base64) — field 로 구분"},{"status":422,"code":"title_invalid","modes":["all"],"when":"title 공백이거나 200자 초과"},{"status":422,"code":"client_ref_invalid","modes":["all"],"when":"client_ref 가 영문·숫자·._:- 128자 이하가 아님"},{"status":422,"code":"expires_in_days_invalid","modes":["all"],"when":"expires_in_days 가 1~30 정수가 아님"},{"status":422,"code":"too_many_items","modes":["all"],"when":"recipients 500명 초과"},{"status":422,"code":"recipient_invalid","modes":["all"],"when":"수신자 이름 없음/100자 초과 또는 휴대폰·이메일 둘 다 없음"},{"status":422,"code":"recipient_phone_invalid","modes":["all"],"when":"수신자 휴대폰 형식 오류"},{"status":422,"code":"recipient_email_invalid","modes":["all"],"when":"수신자 이메일 형식 오류"},{"status":422,"code":"recipients_required","modes":["all"],"when":"recipients 0명"},{"status":422,"code":"mode_invalid","modes":["all"],"when":"mode 가 sign·deliver_pdf·sign_pdf 가 아님"},{"status":422,"code":"document_kind_invalid","modes":["all"],"when":"mode 와 맞지 않는 document_kind"},{"status":422,"code":"subject_required","modes":["sign","deliver_pdf","sign_pdf"],"when":"subject(이름 2자 이상·휴대폰) 없음/형식 오류 — sign_pdf 는 employment_contract 이거나 subject 를 보낸 경우"},{"status":422,"code":"single_recipient_required","modes":["sign","deliver_pdf","sign_pdf"],"when":"수신자 2명 이상(sign·deliver_pdf 항상 · sign_pdf 는 employment_contract)"},{"status":422,"code":"recipients_roles_mismatch","modes":["sign","sign_pdf"],"when":"수신 역할 수와 recipients 수가 다름 / recipients[].role 이 역할과 1:1 이 아님"},{"status":422,"code":"employer_seal_image_invalid","modes":["sign","sign_pdf"],"when":"employer_seal_image 가 PNG/JPEG data URL 이 아님(매직바이트)"},{"status":422,"code":"employer_seal_image_too_large","modes":["sign","sign_pdf"],"when":"employer_seal_image 디코드 300KB 초과"},{"status":422,"code":"employer_seal_image_not_applicable","modes":["deliver_pdf","sign_pdf"],"when":"deliver_pdf 에 보냄 / sign_pdf 인데 발신 역할(side:sender) 없음"},{"status":422,"code":"preview_document_invalid","modes":["all"],"when":"preview_document 가 sign_pdf 의 \"pdf\" 가 아님"},{"status":422,"code":"preview_requires_dry_run","modes":["sign_pdf"],"when":"preview_document:\"pdf\" 와 dry_run:false 를 함께 보냄"},{"status":422,"code":"roles_invalid","modes":["sign","sign_pdf"],"when":"roles 개수·role id 형식·라벨·중복·발신 역할 수 오류(sign: is_sender 정확히 1 · sign_pdf: sender ≤1·recipient ≥1)"},{"status":422,"code":"field_too_long","modes":["sign"],"when":"body_markdown 200,000자 초과"},{"status":422,"code":"unresolved_placeholder","modes":["sign"],"when":"본문에 {{sig|seal|date:role}} 외의 {{…}} 가 남음"},{"status":422,"code":"role_undeclared","modes":["sign"],"when":"본문 토큰의 역할이 roles 에 없음"},{"status":422,"code":"date_token_duplicate","modes":["sign"],"when":"같은 역할의 {{date:role}} 가 2번 이상"},{"status":422,"code":"role_signature_missing","modes":["sign"],"when":"역할의 {{sig:role}}·{{seal:role}} 가 본문에 없음"},{"status":422,"code":"recipient_contract_mismatch","modes":["sign","sign_pdf"],"when":"subject 와 수신자 이름·휴대폰이 다름 / sign 은 본문 수신 역할 서명란에 subject 이름이 없음"},{"status":422,"code":"channel_invalid","modes":["deliver_pdf"],"when":"channel 이 'sms'·'auto' 가 아님"},{"status":422,"code":"recipient_document_mismatch","modes":["deliver_pdf"],"when":"subject 와 수령인 이름·휴대폰이 다름"},{"status":422,"code":"certificate_no_required","modes":["deliver_pdf"],"when":"certificate_no 없음"},{"status":422,"code":"certificate_no_invalid","modes":["deliver_pdf"],"when":"certificate_no 형식·길이 오류"},{"status":422,"code":"pdf_too_large","modes":["deliver_pdf","sign_pdf"],"when":"PDF 5MB 초과(base64 길이 또는 디코드 바이트)"},{"status":422,"code":"pdf_invalid","modes":["deliver_pdf","sign_pdf"],"when":"base64 아님 / 디코드 불가 / %PDF- 머리글 없음 / 손상·암호화로 읽기 실패"},{"status":422,"code":"pdf_no_pages","modes":["deliver_pdf","sign_pdf"],"when":"PDF 쪽 수 0"},{"status":422,"code":"document_source_ambiguous","modes":["sign_pdf"],"when":"pdf_base64 와 document_ref 를 둘 다 보냄"},{"status":422,"code":"document_ref_invalid","modes":["sign_pdf"],"when":"document_ref 가 \"sha256:<64 hex>\" 가 아님"},{"status":404,"code":"document_not_found","modes":["sign_pdf"],"when":"document_ref 의 PDF 가 이 조직에 없음(다른 조직 포함)"},{"status":409,"code":"document_ref_mismatch","modes":["sign_pdf"],"when":"저장된 PDF 해시가 document_ref 와 다름"},{"status":422,"code":"pdf_rotated","modes":["sign_pdf"],"when":"회전(/Rotate)된 쪽이 있는 PDF"},{"status":422,"code":"recipient_role_required","modes":["sign_pdf"],"when":"recipients[].role 을 일부만 넣음"},{"status":422,"code":"fields_required","modes":["sign_pdf"],"when":"fields 가 비었거나 배열이 아님"},{"status":422,"code":"too_many_fields","modes":["sign_pdf"],"when":"칸 60개 초과"},{"status":422,"code":"field_invalid","modes":["sign_pdf"],"when":"칸이 객체가 아님 / x·y·w·h 숫자 아님 / dataType·fontSize(4~24)·align 오류"},{"status":422,"code":"field_type_invalid","modes":["sign_pdf"],"when":"type 이 signature·seal·date·text·checkbox 가 아님"},{"status":422,"code":"role_unknown","modes":["sign_pdf"],"when":"칸의 role 이 roles 에 없음"},{"status":422,"code":"field_side_mismatch","modes":["sign_pdf"],"when":"칸의 side 가 역할의 side 와 다름"},{"status":422,"code":"field_out_of_page","modes":["sign_pdf"],"when":"page 가 1~쪽수 밖 / x,y<0 또는 x+w>1 또는 y+h>1(0~1 왼쪽 위 비율)"},{"status":422,"code":"field_too_small","modes":["sign_pdf"],"when":"너비 0.01 · 높이 0.008 미만"},{"status":422,"code":"field_type_not_allowed","modes":["sign_pdf"],"when":"발신 역할에 checkbox 칸"},{"status":422,"code":"field_key_invalid","modes":["sign_pdf"],"when":"key 가 영문 소문자로 시작하는 소문자·숫자·_ 40자 이하가 아님"},{"status":422,"code":"field_key_duplicate","modes":["sign_pdf"],"when":"같은 key 2번"},{"status":422,"code":"field_value_not_allowed","modes":["sign_pdf"],"when":"발신 text 칸이 아닌 곳에 value"},{"status":422,"code":"field_value_invalid","modes":["sign_pdf"],"when":"value 가 문자열이 아니거나 500자 초과"},{"status":422,"code":"field_value_required","modes":["sign_pdf"],"when":"발신 text 칸에 value 없음(빈칸 발송 방지)"},{"status":422,"code":"field_overlap","modes":["sign_pdf"],"when":"다른 역할의 칸끼리 겹침"},{"status":422,"code":"missing_signature_field","modes":["sign_pdf"],"when":"수신 역할에 signature·seal 칸이 없음"},{"status":409,"code":"storage_unavailable","modes":["sign_pdf"],"when":"문서 저장소(R2) 바인딩 없음","confirm_only":true},{"status":422,"code":"confirmation_required","modes":["all"],"when":"confirmation_token 없음·만료·위조·이미 사용","confirm_only":true},{"status":422,"code":"confirmation_payload_mismatch","modes":["all"],"when":"미리보기 뒤 요청 내용(sign_pdf 는 칸·역할·문서 layout_hash 포함)이 바뀜","confirm_only":true},{"status":409,"code":"idempotency_conflict","modes":["all"],"when":"같은 client_ref 또는 Idempotency-Key 가 다른 요청 내용에 이미 쓰임","confirm_only":true},{"status":409,"code":"idempotency_incomplete","modes":["all"],"when":"같은 client_ref 의 이전/동시 요청이 아직 끝나지 않음(retryable)","confirm_only":true},{"status":402,"code":"org_unverified","modes":["all"],"when":"조직에 이메일·휴대폰 인증을 마친 사용자가 없음","confirm_only":true},{"status":409,"code":"sender_unresolved","modes":["all"],"when":"조직 발신자(대표 사용자)를 찾을 수 없음","confirm_only":true},{"status":409,"code":"sender_phone_required","modes":["deliver_pdf"],"when":"조직 대표 사용자의 휴대폰 미등록","confirm_only":true},{"status":422,"code":"invalid_input","modes":["sign_pdf"],"when":"계약 생성 시 받는 사람/역할 수 불일치(도메인)","confirm_only":true},{"status":422,"code":"sender_signature_unavailable","modes":["sign_pdf"],"when":"발신 서명·도장 칸 이미지를 만들지 못함(employer_seal_image 없고 기본 서명 렌더 실패)","confirm_only":true},{"status":422,"code":"merge_render_failed","modes":["sign_pdf"],"when":"발신 text 값(한글)을 PDF 에 굽지 못함(문서 렌더 일시 오류)","confirm_only":true},{"status":422,"code":"no_deliverable_recipient","modes":["all"],"when":"전달 가능한 수신 채널(휴대폰·이메일·설정) 없음","confirm_only":true},{"status":402,"code":"payment_method_required","modes":["all"],"when":"무료·충전 발송권 모두 소진","confirm_only":true},{"status":409,"code":"billing_failed","modes":["all"],"when":"정산 단계 예기치 않은 오류(원상복구됨 · retryable)","confirm_only":true},{"status":409,"code":"invalid_state","modes":["all"],"when":"계약 상태가 발송할 수 없는 상태(도메인)","confirm_only":true},{"status":409,"code":"illegal_transition","modes":["all"],"when":"허용되지 않는 상태 전이(도메인)","confirm_only":true},{"status":404,"code":"not_found","modes":["all"],"when":"대상 리소스 없음(도메인 not_found — 다른 조직 은폐 포함)","confirm_only":true}]}},"/api/registry/tools":{"get":{"summary":"Tool registry","responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/registry/tools/{name}":{"get":{"summary":"Tool registry item","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/registry/categories":{"get":{"summary":"Tool categories","responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/approvals":{"get":{"summary":"List HITL approvals","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/approvals/{id}/decide":{"post":{"summary":"Approve or reject HITL request","parameters":[{"name":"X-Org-Id","in":"header","required":false,"description":"선택(인증 아님) — org 는 Bearer 토큰에서 도출됩니다.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/oauth/authorize":{"get":{"summary":"OAuth authorization endpoint","responses":{"302":{"description":"Login/consent redirect"}}}},"/oauth/token":{"post":{"summary":"OAuth token endpoint","responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/oauth/register":{"post":{"summary":"Dynamic client registration","responses":{"201":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/oauth/revoke":{"post":{"summary":"OAuth token revocation","responses":{"200":{"description":"Revoked or ignored"}}}},"/oauth/introspect":{"post":{"summary":"OAuth token introspection","responses":{"200":{"description":"RFC 7662 active token response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/ai/tools":{"get":{"summary":"AI-readable Tool Registry alias","responses":{"200":{"description":"성공 응답","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}}}