싸인딜

개발자 문서

API로 계약 보내기, 5분이면 됩니다

OAuth 연동도, 미리보기 단계도, 멱등키 헤더도 필요 없습니다. API 키 하나와 요청 한 번으로 고객에게 서명 요청이 나갑니다.

시작하기

  1. 가입하고 사업자 인증을 마칩니다인증 전에는 실제 발송이 막힙니다. preview 요청은 인증 전에도 됩니다.
  2. API 키를 만듭니다로그인 후 app.signdeal.kr/app/mcp에서 발급합니다. 키는 만든 직후 한 번만 보입니다.
  3. 보낼 양식을 고릅니다GET /api/templates에서 api_sendable: true인 양식을 찾고, 각 양식의 quick_send_example을 그대로 복사해도 됩니다.
  4. 요청을 한 번 보냅니다아래 예시를 그대로 붙여 넣으세요.

요청 한 번으로 발송

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자 이상 직접 만든 랜덤 문자열" }'
// 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가 고정이라면 키 설정에서 켜면 다른 곳에서 훔쳐 써도 막힙니다.
개인정보휴대폰 번호는 암호화해 저장하고, 웹훅에는 가린 번호만 보냅니다.

키는 서버에만 두세요. 키가 있으면 우리 회사 이름으로 계약을 보낼 수 있습니다. 웹 페이지 스크립트나 모바일 앱에 넣지 말고, 유출됐다면 키 관리 화면에서 바로 삭제하세요.

알아 둘 점

오류가 났을 때

{ "error": { "type": "validation_error", "code": "missing_required",
             "message": "필수 항목이 비어 있습니다: employee_name",
             "request_id": "req_…", "retryable": false } }
HTTPcode할 일
401tenant_unresolved키가 틀렸거나 삭제됨, 또는 허용하지 않은 IP입니다.
402payment_required무료 건수와 크레딧이 모두 소진됐습니다. 충전하세요.
403org_unverified사업자 인증을 마치세요.
404—없는 양식이거나 내 회사가 쓸 수 없는 양식입니다.
409idempotency_conflict같은 ref에 다른 내용을 보냈습니다.
422missing_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"

전체 명세는 OpenAPI와 AI 개발 문서에 있습니다.