전자서명 API,
5분 만에 연동

https://api.moram.net/signplug/v1

# 개발/QA (KG이니시스 본인확인 테스트, 과금 없음)
Authorization: Bearer sp_test_xxxxxxxxxxxxxxxxxxxxx

# 운영 (KG이니시스 본인확인, 과금)
Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxxxxxx

{
  "session_token": "wsh_Us0GyhIY4IrAXfwlO1uUZhnclHTboxGP",
  "hosted_url": "https://signplug.moram.net/start?session_token=wsh_Us0GyhIY4IrAXfwlO1uUZhnclHTboxGP",
  "environment": "test",
  "expires_at": "2026-05-15T13:00:00.000Z"
}

{
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "waiting",
  "created_at": "2026-04-23T10:00:00Z",
  "expires_at": "2026-04-26T10:00:00Z",
  "converted_pdf_url": null,
  "signing_urls": [
    {
      "name": "홍길동",
      "participant_index": 0,
      "url": "https://sign.moram.net/signplug/s/TOKEN"
    }
  ]
}

{
  "account_id": "9f2c7c3e-1111-4444-9999-1c4f7a8b9d10",
  "source_object_key": "pending-sources/018f6f3a-5f7e-7c9a-b111-6b4a7f3c9d22.pdf",
  "bucket_name": "signplug-documents",
  "file_type": "pdf",
  "original_filename": "contract.pdf",
  "storage_provider": "s3",
  "expires_at": "2026-05-20T10:00:00.000Z",
  "size": 123456,
  "sha256": "e3b0c44298fc1c149afb..."
}

curl "https://api.moram.net/signplug/v1/documents?page=1&limit=20&status=completed" \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

{
  "documents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "공급계약서 2026-04",
      "status": "completed",
      "environment": "live",
      "source_file_type": "pdf",
      "created_at": "2026-04-23T10:00:00.000Z",
      "expires_at": "2026-04-26T10:00:00.000Z",
      "completed_at": "2026-04-23T11:42:10.000Z"
    },
    {
      "id": "0b1c2d3e-4f56-7890-abcd-ef1234567891",
      "title": "비밀유지서약서",
      "status": "waiting",
      "environment": "live",
      "source_file_type": "docx",
      "created_at": "2026-04-22T09:00:00.000Z",
      "expires_at": "2026-04-25T09:00:00.000Z",
      "completed_at": null
    }
  ],
  "total": 47,
  "page": 1,
  "limit": 20
}

curl https://api.moram.net/signplug/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

{
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "공급계약서 2026-04",
  "status": "in_progress",
  "created_at": "2026-04-23T10:00:00.000Z",
  "completed_at": null,
  "metadata": { "order_id": "12345" },
  "participants": [
    { "name": "홍길동", "status": "signed",   "signed_at": "2026-04-23T10:14:32.000Z" },
    { "name": "김영희", "status": "verified", "signed_at": null }
  ]
}

{
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_hash": "8b1a9953c4611296a827abf8c47804d7...",
  "events": [
    {
      "event_type": "document.viewed",
      "timestamp": "2026-04-23T10:08:15.000Z",
      "participant_name": "홍길동",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "verification_method": null
    },
    {
      "event_type": "document.verified",
      "timestamp": "2026-04-23T10:09:01.000Z",
      "participant_name": "홍길동",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "verification_method": "portone_inicis_unified"
    },
    {
      "event_type": "document.signed",
      "timestamp": "2026-04-23T10:14:32.000Z",
      "participant_name": "홍길동",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "verification_method": "canvas"
    }
  ]
}

{
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "cancelled",
  "cancelled_at": "2026-04-23T15:42:10.000Z"
}

https://sign.moram.net/signplug/s/<TOKEN>

안녕하세요, [회사명]입니다.
"[문서 제목]" 전자서명 요청을 보내드립니다.

▶ 서명하러 가기: https://sign.moram.net/signplug/s/abcd1234...

· KG이니시스 통합본인인증 완료 후 서명할 수 있습니다.
· 링크는 발송일로부터 72시간 동안 유효합니다.

curl -X POST https://api.moram.net/signplug/v1/webhooks \
  -H "Authorization: Bearer sp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/signplug",
    "events": ["document.created", "document.signed", "document.completed"],
    "timeout_seconds": 10
  }'

curl -X DELETE https://api.moram.net/signplug/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

POST https://yourapp.com/webhooks/signplug
Content-Type: application/json
X-SignPlug-Delivery-Id: 018f6f3a-5f7e-7c9a-b111-6b4a7f3c9d22
X-SignPlug-Event: document.completed
X-SignPlug-Signature: t=2026-04-23T15:42:10.000Z,v1=...
X-SignPlug-Timestamp: 2026-04-23T15:42:10.000Z

{
  "event_type": "document.completed",
  "event_key": "document.completed:a1b2c3d4-e5f6-7890-abcd-ef1234567890:018f6f3a",
  "occurred_at": "2026-04-23T15:42:10.000Z",
  "data": {
    "document": {
      "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "environment": "live",
      "metadata": { "source": "portal" },
      "status": "completed",
      "title": "테스트 계약서"
    },
    "participant": null,
    "event_data": {
      "signed_participants": 2
    }
  }
}

import hashlib, hmac

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    parts = dict(item.split("=", 1) for item in signature_header.split(",") if "=" in item)
    timestamp = parts.get("t")
    received = parts.get("v1")
    if not timestamp or not received:
        return False

    signed_payload = timestamp.encode() + b"." + payload_bytes
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

# Flask 예시
@app.route("/webhooks/signplug", methods=["POST"])
def webhook():
    sig = request.headers.get("X-SignPlug-Signature", "")
    if not verify_webhook(request.get_data(), sig, WEBHOOK_SECRET):
        return "Unauthorized", 401
    event = request.json
    if event["event_type"] == "document.completed":
        # 완료 처리 로직
        pass
    return "OK", 200

{
  "api_keys": [
    {
      "id": "5f7a1c2b-1111-4444-9999-1c4f7a8b9d10",
      "name": "Default Test Key",
      "environment": "test",
      "key_prefix": "sp_test_",
      "is_active": true,
      "is_current": true,
      "created_at": "2026-04-23T10:00:00.000Z",
      "last_used_at": "2026-04-23T15:42:10.000Z",
      "expires_at": null
    },
    {
      "id": "6a8b2d3c-2222-5555-aaaa-2d5f8b9caef1",
      "name": "Default Live Key",
      "environment": "live",
      "key_prefix": "sp_live_",
      "is_active": true,
      "is_current": true,
      "created_at": "2026-04-23T10:00:00.000Z",
      "last_used_at": null,
      "expires_at": null
    }
  ]
}

{
  "api_key_id": "8c9d4e5f-3333-6666-bbbb-3e6f9cadef02",
  "api_key": "sp_live_AbCdEf...전체키...XyZ",
  "name": "Default Live Key",
  "environment": "live",
  "created_at": "2026-05-15T10:00:00.000Z"
}

{
  "doc_count": 23,
  "api_doc_count": 18,
  "web_doc_count": 5,
  "free_doc_count": 5,
  "amount_krw": 8400,
  "billing_status": "pending",
  "billed_at": null
}

{
  "provider": "portone",
  "card_company": "KG이니시스",
  "card_number_masked": "",
  "customer_key": "sp_customer...",
  "subscription_id": null,
  "is_active": true
}

// 오류 응답 형식
{
  "error": "invalid_request",
  "message": "The request body is invalid.",
  "details": null,
  "request_id": "req-13m",
  "responsibility": "client",
  "retryable": false,
  "field_errors": [
    {
      "field": "options.reminder_intervals_hours",
      "message": "This field must be an array. Use [] when no reminders are needed."
    }
  ]
}