DEVELOPERS

SignPen API

문서 업로드부터 서명 요청 발송, 상태 조회, 감사추적 인증서가 붙은 체결본 다운로드까지. 대시보드에서 하는 일을 모두 REST API 로 할 수 있어요.

STARTER 이상 · 테스트 키 무료REST · JSONHMAC 서명 웹훅Idempotency-Key 지원임베드 서명
대시보드에서 API 키 발급무료 계정 만들기

1API 키 발급

대시보드 → 설정 → API 키에서 키를 만듭니다. 키는 처음 한 번만 보여 주니 안전한 곳에 보관하세요. 모든 요청에 Authorization: Bearer sp_live_… 헤더를 붙입니다.

export SIGNPEN_KEY="sp_live_여기에_발급받은_키"
curl https://signpen.app/api/v1/me -H "Authorization: Bearer $SIGNPEN_KEY"

2파일 올리고 서명 요청 보내기

PDF(또는 JPG·PNG)를 올려 id 를 받고, 받는 사람과 서명란 위치를 넣어 "send": true 로 바로 발송합니다. 좌표는 페이지 대비 비율(0~1), 원점은 왼쪽 위입니다.

# ① 파일 업로드 → {"id": "f_..."}
curl -X POST https://signpen.app/api/v1/files \
  -H "Authorization: Bearer $SIGNPEN_KEY" \
  -F "file=@근로계약서.pdf"

# ② 서명 요청 발송 (1건 차감 · 취소/만료 시 자동 환급)
curl -X POST https://signpen.app/api/v1/envelopes \
  -H "Authorization: Bearer $SIGNPEN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contract-E0012" \
  -d '{
    "title": "근로계약서 — 이하늘",
    "documents": [{ "file_id": "f_..." }],
    "recipients": [{ "key": "worker", "name": "이하늘", "email": "sky@example.com" }],
    "fields": [
      { "page": 1, "type": "signature", "recipient": "worker", "x": 0.62, "y": 0.86, "w": 0.25, "h": 0.06 },
      { "page": 1, "type": "date", "recipient": "worker", "x": 0.62, "y": 0.82, "w": 0.2, "h": 0.025 }
    ],
    "expires_in_days": 7,
    "send": true
  }'

3웹훅으로 결과 받기

엔드포인트를 등록하면 envelope.completed 같은 이벤트를 POST 로 보내 드립니다. 응답의 secret 으로 SignPen-Signature 헤더를 검증하세요. 체결되면 GET /envelopes/{id}/completed 로 체결본 PDF 를 받습니다.

curl -X POST https://signpen.app/api/v1/webhooks \
  -H "Authorization: Bearer $SIGNPEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/signpen", "events": ["envelope.completed", "envelope.declined"] }'

# 검증: v1 == hex(HMAC-SHA256(secret, t + "." + 원문 본문)), t 는 5분 이내
# SignPen-Signature: t=1760000000,v1=5f2b...
요청 한도API 키당 분당 120회. 초과하면 429 를 돌려줍니다.
과금서명 요청 발송 1건 = 1건 차감. 서명자 10명까지 동일, 조회·다운로드는 무료.
오류 형식{"error":{"code","message"}} 메시지는 한국어로 옵니다.

API 레퍼런스

오른쪽 위 Authorize 에 API 키를 넣으면 이 화면에서 바로 호출해 볼 수 있습니다.

openapi.json 내려받기 →
API 레퍼런스를 불러오는 중…