개발자 문서
API로 계약 보내기, 5분이면 됩니다
OAuth 연동도, 미리보기 단계도, 멱등키 헤더도 필요 없습니다. API 키 하나와 요청 한 번으로 고객에게 서명 요청이 나갑니다.
시작하기
- 가입하고 사업자 인증을 마칩니다인증 전에는 실제 발송이 막힙니다.
preview요청은 인증 전에도 됩니다. - API 키를 만듭니다로그인 후 app.signdeal.kr/app/mcp에서 발급합니다. 키는 만든 직후 한 번만 보입니다.
- 보낼 양식을 고릅니다
GET /api/templates에서api_sendable: true인 양식을 찾고, 각 양식의quick_send_example을 그대로 복사해도 됩니다. - 요청을 한 번 보냅니다아래 예시를 그대로 붙여 넣으세요.
요청 한 번으로 발송
POST https://api.signdeal.kr/api/send
curl -X POST https://api.signdeal.kr/api/send \
-H "Authorization: Bearer $SIGNDEAL_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": "tpl_xxxxxxxx",
"to": { "name": "홍길동", "phone": "010-1234-5678" },
"values": { "company_name": "(주)예시", "fee": "1000000" },
"ref": "order-20261026-0001"
}'
Node.js
const res = await fetch('https://api.signdeal.kr/api/send', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SIGNDEAL_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
template: 'tpl_xxxxxxxx',
to: { name: '홍길동', phone: '010-1234-5678' },
values: { company_name: '(주)예시', fee: '1000000' },
ref: 'order-20261026-0001',
}),
});
const sent = await res.json(); // 202 { contract_id, tracking_id, status, ... }
Python
import os, requests
res = requests.post(
"https://api.signdeal.kr/api/send",
headers={"Authorization": f"Bearer {os.environ['SIGNDEAL_KEY']}"},
json={
"template": "tpl_xxxxxxxx",
"to": {"name": "홍길동", "phone": "010-1234-5678"},
"values": {"company_name": "(주)예시", "fee": "1000000"},
"ref": "order-20261026-0001",
},
timeout=30,
)
sent = res.json()
| 항목 | 필수 | 설명 |
|---|---|---|
template | 예 | 양식 ID. GET /api/templates의 template_id |
to | 예 | 받는 사람 1명. name과 phone 또는 email |
values | 양식별 | 양식에 채울 값. 키는 fields[].key |
ref | 아니오 | 자사 주문번호 등 식별자. 웹훅에 그대로 돌아옵니다. 영문·숫자와 ._:-, 128자 이하 |
title | 아니오 | 계약 제목. 비우면 양식 이름 |
preview | 아니오 | true면 발송 없이 채워진 값만 돌려줍니다 |
expires_in_days | 아니오 | 서명 기한 1~30일, 기본 7일 |
응답
202 Accepted
{
"contract_id": "ctr_…",
"tracking_id": "…",
"client_ref": "order-20261026-0001",
"status": "sent",
"channel_used": "kakao_alimtalk",
"billing": { "kind": "free", "free_used": 1, "free_quota": 100 },
"delivery_status_url": "/api/contracts/ctr_…/deliveries/…"
}
받는 사람에게 카카오 알림톡(실패 시 문자)으로 서명 링크가 갑니다. 서명자는 앱 설치나 가입이 필요 없습니다.
같은 요청을 두 번 보내도 한 번만 나갑니다
네트워크가 끊겨 다시 보내도 중복 발송되지 않습니다. ref가 같으면 같은 계약으로 보고 처음 결과를 돌려줍니다(응답에 idempotent_replay: true). ref를 안 보내면 내용(양식, 받는 사람, 값, 제목)으로 같은 요청인지 판단합니다.
같은 내용을 일부러 다시 보내야 한다면 다른 ref를 넣으세요. 같은 ref에 다른 내용을 보내면 409 idempotency_conflict로 거절됩니다.
서명 완료 알림 받기
웹훅을 한 번 등록해 두면 서명이 끝났을 때 서버로 알려 드립니다.
curl -X POST https://api.signdeal.kr/api/integrations/webhooks \
-H "Authorization: Bearer $SIGNDEAL_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://api.example.co.kr/hooks/signdeal",
"secret": "32자 이상 직접 만든 랜덤 문자열" }'
- 이벤트:
contract.sentcontract.completedcontract.declinedcontract.voided - 본문에 보낸
ref가contract.client_ref로 들어 있어 자사 주문과 바로 연결됩니다. - 진짜 싸인딜이 보낸 요청인지
x-signdeal-signature: sha256=…헤더로 확인하세요. 받은 본문 원본에 시크릿으로 HMAC-SHA256을 계산한 값입니다. - 완료되면
GET /api/contracts/{contract_id}/pdf?strict_final=1로 서명 완료본을 받습니다.
// Node.js — 웹훅 서명 확인
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (req.get('x-signdeal-signature') !== expected) return res.sendStatus(401);
보안은 필요한 만큼만 남겼습니다
| 항목 | 지금 방식 |
|---|---|
| 인증 | Authorization: Bearer sk_… 한 가지입니다. 어느 회사의 요청인지는 이 키로만 판단합니다. |
| 발송 확인 | 따로 요구하지 않습니다. 요청을 보내는 것이 곧 발송 승인입니다. 서버 안에서는 확인 토큰 검증과 1회 사용 처리를 그대로 거칩니다. |
| 사업자 인증 | 유지됩니다. 인증 전에는 실제 발송이 되지 않습니다. |
| IP 제한 | 선택입니다. 서버 IP가 고정이라면 키 설정에서 켜면 다른 곳에서 훔쳐 써도 막힙니다. |
| 개인정보 | 휴대폰 번호는 암호화해 저장하고, 웹훅에는 가린 번호만 보냅니다. |
키는 서버에만 두세요. 키가 있으면 우리 회사 이름으로 계약을 보낼 수 있습니다. 웹 페이지 스크립트나 모바일 앱에 넣지 말고, 유출됐다면 키 관리 화면에서 바로 삭제하세요.
알아 둘 점
- 한 번에 받는 사람은 1명입니다. 서명자가 3명 이상인 양식은
api_sendable: false이며 웹앱에서 보내야 합니다. - 전자서명이 법적으로 제한되는 양식(보증 등)은
451 electronic_not_allowed로 거절됩니다. - 가입 시 무료 100건이 있고 이후 선불 크레딧을 씁니다. 서명하는 사람은 무료입니다. 소진되면
402가 옵니다. - 별도 테스트 키는 아직 없습니다. 값이 맞는지 확인하려면
"preview": true로 먼저 보내 보세요. 발송도 과금도 일어나지 않습니다. - 발송 요청은 요청 한도가 있을 수 있습니다.
429가 오면 잠시 뒤 다시 보내세요.
오류가 났을 때
{ "error": { "type": "validation_error", "code": "missing_required",
"message": "필수 항목이 비어 있습니다: employee_name",
"request_id": "req_…", "retryable": false } }
| HTTP | code | 할 일 |
|---|---|---|
| 401 | tenant_unresolved | 키가 틀렸거나 삭제됨, 또는 허용하지 않은 IP입니다. |
| 402 | payment_required | 무료 건수와 크레딧이 모두 소진됐습니다. 충전하세요. |
| 403 | org_unverified | 사업자 인증을 마치세요. |
| 404 | — | 없는 양식이거나 내 회사가 쓸 수 없는 양식입니다. |
| 409 | idempotency_conflict | 같은 ref에 다른 내용을 보냈습니다. |
| 422 | missing_required 등 | error.field가 가리키는 항목을 고치세요. |
AI에서 바로 쓰기
Claude, Codex 같은 AI 도구는 MCP로 연결합니다. 같은 API 키를 쓰고, AI가 만든 계약은 발송 전에 사람이 미리보고 승인하는 단계를 유지합니다.
claude mcp add --transport http signdeal https://mcp.signdeal.kr/mcp \
--header "Authorization: Bearer $SIGNDEAL_KEY"