서명 세션
서명자 한 명이 문서 한 건에 여러분의 페이지 안에서 서명합니다. 이메일 왕복도, 사이트 밖으로의 리디렉션도 없습니다.
- 문서를 읽고, 자신의 필드를 채우고, 그리기·입력·업로드로 서명
- 사유를 적어 거절할 수 있고, 페이지는 이를 이벤트로 받음
- 서명이 끝나면 서명된 PDF 다운로드
- 프레임 자체 메뉴에서 언어 전환
작동 방식세 단계, 그리고 시크릿 키는
세 단계, 그리고 시크릿 키는
서버를 떠나지 않습니다
임베드는 서버가 발급하는 세션에서 시작합니다. 돌려받은 URL을 페이지가 프레임으로 띄우고, 프레임은 고정된 postMessage 채널로 여러분의 코드와 통신합니다.
- 1
서버에서 세션 발급
시크릿 키로 POST /embed_sessions를 호출하면서 문서와, 프레임을 띄울 페이지의 오리진을 지정합니다. id와 만료되는 URL을 돌려받습니다.
- 2
페이지에 마운트
URL을 @gingerdocs/embed에 넘기세요. SDK는 당사 오리진에서 서명 화면을 프레임으로 띄우고, 양쪽에서 오리진과 세션 id를 고정하고, 타입이 지정된 이벤트를 코드에 전달합니다.
- 3
웹훅으로 처리
SDK 이벤트는 UX 신호입니다 — 스피너를 숨기고 확인 화면을 보여 주는 용도입니다. 실제 처리는 서명된 document.completed 웹훅으로 하세요. 모든 이벤트는 90일 동안 읽을 수 있습니다.
const res = await fetch('https://api.gingerdocs.com/api/v1/embed_sessions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GINGERDOCS_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
kind: 'signing',
document_id: documentId,
host_origin: 'https://app.example.com',
}),
})
const { id, url } = await res.json()import { mount } from '@gingerdocs/embed'
const embed = mount('#signing', { url, sessionId: id })
embed.on('ready', () => hideLoader())
embed.on('completed', () => showConfirmation())
embed.on('session_expired', async () => {
const fresh = await refetchSession()
embed.reload(fresh.url, { sessionId: fresh.id })
})import { GingerDocsEmbed } from '@gingerdocs/react'
<GingerDocsEmbed
url={session.url}
sessionId={session.id}
onEvent={event => event.type === 'completed' && showConfirmation()}
/>URL은 그대로 전달하세요. 프래그먼트에는 세션 자격 증명이, 쿼리에는 어느 페이지가 프레임을 띄울 수 있는지 당사 엣지가 판단하는 값이 들어 있습니다.
세 가지 임베드 방식서명 한 건부터
서명 한 건부터
전체 편집기까지
모든 임베드는 서버가 발급하는 세션입니다. 그 종류(kind)와 모드(mode)가 프레임 안의 사람이 할 수 있는 일을 정하고, 서버는 UI뿐 아니라 모든 요청에서 이를 강제합니다.
워크스페이스 · minimal
편집기를 노출하지 않고, 여러분의 사용자가 템플릿으로 문서를 만듭니다.
- 사용 가능한 템플릿을 둘러보고 변수와 자신의 입력값 채우기
- 보내는 사람과 서명하는 사람 지정 — 원하면 미리 설정하고 잠글 수 있음
- 채우는 동안 페이지를 미리 보고, 만들어서 보내기
- 자신의 PDF를 업로드해 보내기 — 서명 필드는 자동으로 배치
워크스페이스 · advanced
GingerDocs 앱이 제공하는 바로 그 편집기가 여러분의 도메인에서 실행됩니다.
- PDF를 업로드하고 서명·이니셜·텍스트·날짜·체크박스 필드 배치
- 초안을 저장하고 나중에 다시 열기
- PDF에서 템플릿을 만들고, 직접 만든 템플릿 편집
- minimal의 모든 기능 포함
네 번째 모드인 read_only는 완료된 문서나 템플릿을 조작 없이 보여 줍니다 — 자사 UI에 넣을 수 있는 뷰어입니다.
REST API같은 제품을
같은 제품을
엔드포인트로
모두 https://api.gingerdocs.com/api/v1 아래에 있으며 Bearer API 키로 인증합니다. 사용자를 만들고, 문서를 업로드하고, 보내고, 무슨 일이 있었는지 읽기 — 네 번의 호출로, 어떤 언어에서든.
믿고 쓸 수 있는 규약
- 서버용 시크릿 키와 읽기 전용 브라우저용 퍼블리셔블 키 — 각각 필요한 범위(스코프)로 한정
- 완전히 분리된 test와 live 두 환경을 같은 엔드포인트에서
- 모든 POST에 Idempotency-Key를 붙이면 재시도가 안전
- 오류에는 변하지 않는 기계용 code가 있고, message는 표시용이라 바뀔 수 있음
- 키당 분당 120회 요청, 429에는 Retry-After
- OpenAPI 3.1 계약으로 정의되고 모든 응답이 그에 맞춰 검증됨
curl https://api.gingerdocs.com/api/v1/account \
-H "Authorization: Bearer gd_sk_test_YOUR_KEY"{
"environment": "test",
"scopes": ["documents", "templates", "users", "embed", "webhooks"],
"plan": { "key": "free", "limit": 30, "used": 12, "remaining": 18 },
"defaults": { "email_delivery": "platform" }
}Users
문서의 소유자가 되는 여러분 제품의 사용자. 여러분의 external_id로 관리합니다.
Documents
PDF를 업로드하거나 템플릿으로 만들고, 서명자를 지정하고, 상태를 따라가고, 서명된 사본을 다운로드.
Fields
서명·이니셜·텍스트·날짜·체크박스 필드를 정규화된 페이지 좌표로 배치.
Templates
앱이나 advanced 워크스페이스에서 만든 템플릿을 목록으로 보고, 공유하고, 문서로 생성.
Sending
당사가 서명자에게 이메일을 보내거나, 여러분이 서명 링크를 직접 전달하고 당사는 아무것도 보내지 않도록 선택.
Webhooks & events
HTTPS 엔드포인트를 등록하고, 전송 로그를 읽고, 90일 이벤트 로그에서 어떤 이벤트든 다시 가져오기.
v1은 문서당 서명자가 정확히 한 명입니다 — 수신자 목록도, 서명 순서도, 인계도 없습니다.
프로덕션을 위한 설계직접 만들어야 했을
직접 만들어야 했을
나머지 부분
서명은 쉬운 절반입니다. 나머지 — 전달, 검증, 재시도, 브랜딩, 다국어 — 는 플랫폼에 들어 있습니다.
서명된 웹훅, 16가지 이벤트 유형
HMAC-SHA256으로 서명된 전송에 재시도와 전송 로그가 따릅니다. 모든 이벤트는 이벤트 API로 90일 동안 읽을 수 있어, 엔드포인트가 다운된 동안에도 잃는 것이 없습니다.
이메일을 보내지 않는 테스트 환경
테스트 키는 모든 요금제에서 작동합니다. 출력물에는 워터마크가 찍히고 법적 효력이 없으며, 요금제 한도를 소모하지 않습니다. 테스트 엔드포인트로 서명을 시뮬레이션해 CI에서 COMPLETED를 검증할 수 있고, 테스트 데이터는 90일 후 삭제됩니다.
여러분의 브랜드 색상, 여러분의 뷰포트
세션을 발급할 때 theme.primary_color를 넘기면 프레임의 버튼, 링크, 포커스 링이 그 색을 따릅니다. 좁은 사이드바 임베드는 확장 버튼으로 뷰포트 전체를 차지하고 다시 돌려줄 수 있습니다.
서명 링크를 직접 전달
계정 단위 또는 전송 단위로, GingerDocs가 여러분의 브랜딩으로 서명자에게 이메일을 보낼지, 여러분의 제품이 전달할지 선택하세요. 후자라면 당사는 아무것도 보내지 않고 서명 URL을 넘겨 드립니다.
여러분의 이름이 적힌 증명서
링크를 직접 전달했거나 임베드 세션으로 서명자를 받아들였다면, 완료 증명서는 검증 당사자로 여러분의 법인명을 명시합니다 — 통합 파트너 약관에서 여러분이 받아들이는 책임입니다.
프레임은 6개 언어 지원
서명 프레임과 워크스페이스 프레임은 영어, 일본어, 한국어, 독일어, 스페인어, 프랑스어로 제공됩니다. 세션이나 마운트에서 언어를 지정할 수 있고, 서명자는 프레임 자체 메뉴에서 바꿀 수 있습니다.
오픈소스
MIT 라이선스의 작은 SDK 두 개
SDK가 하는 일은 하나입니다. 세션 URL을 프레임으로 띄우고, postMessage 채널 양쪽에서 오리진과 세션 id를 고정하고, 타입이 지정된 이벤트를 코드에 전달하는 것. 한 번에 다 읽을 수 있는 크기입니다.
MIT 라이선스gzip 기준 1.5 KB 미만의존성 없음
@gingerdocs/embed
프레임워크에 의존하지 않습니다. mount(), on(), reload(), unmount() — 그리고 iframe을 직접 만들고 싶을 때를 위한 확장 프로토콜.
GitHub에서 보기@gingerdocs/react
코어 패키지를 감싼 얇은 React 컴포넌트. 모든 이벤트를 onEvent 핸들러 하나로 받고, 인라인으로 넘겨도 안전합니다.
GitHub에서 보기문서
첫 키부터 서명된 문서까지의 가이드, 바로 호출해 볼 수 있는 엔드포인트 레퍼런스, 그리고 API 검증에 쓰이는 OpenAPI 3.1 계약.
개발자를 위한 요금
무료로 만들고, 연 $100로 라이브.
테스트 키로 만들기 — 무료
개발자 모드와 테스트 키는 무료 요금제를 포함한 모든 요금제에서 쓸 수 있습니다. 생성·전송·서명·웹훅·다운로드까지 전체 연동이 테스트 환경에서 작동합니다.
테스트 키 받기개발자 요금제로 라이브
$100/ 년
프로의 모든 기능과 동일한 월 1,000건 문서 업로드에, 라이브 API 키, 등록된 도메인에서의 임베드 서명, 서명된 웹훅까지.
개발자 요금제 보기