throwDocs API
문서 등록부터 링크 회수까지

개요

비즈니스 플랜 전용입니다. 다른 플랜의 호출은 plan_upgrade_required 403으로 거절됩니다.

이 API가 하지 않는 일

• 메일·문자 발송
• externalRef로 받은 고객 정보의 해석
• 문서를 보내는 담당자의 계정 생성

빠른 시작

토큰 확인부터 공유 링크 생성까지 세 번의 호출로 끝납니다.

1. 토큰 발급마이페이지 → API 연동. 원문은 한 번만 표시됩니다.
2. 연결 확인GET /me로 토큰과 사용 가능 옵션을 확인합니다.
3. 공유 생성PDF를 등록한 뒤 받은 documentId로 공유를 만듭니다.

# 토큰과 API 주소
export TOKEN="tdk_live_여기에_붙여넣기"
export API=https://doc.throw.im/api/v1

# ① 연결 확인
curl -s $API/me -H "Authorization: Bearer $TOKEN"

# ② 파일 등록
DOC=$(curl -s -X POST $API/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@계약서.pdf;type=application/pdf" | jq -r .documentId)

# ③ 공유 생성
curl -s -X POST $API/shares \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{
    \"documentId\": \"$DOC\",
    \"recipient\": { \"name\": \"김민수\", \"email\": \"minsu@example.com\" }
  }"

links.recipient는 고객에게 보내고, links.host는 담당자 화면에 저장해 같은 주소를 계속 사용합니다.

오류가 나면 오류 코드에서 원인별 해결 방법을 확인하세요.

API 점검

토큰 연결만 빠르게 확인합니다.

연동 설계

파일 재사용 여부에 따라 호출 방식을 고르고, 응답 식별자를 저장합니다.

문서와 공유의 차이

문서는 파일, 공유는 수신자별 링크입니다.

저장할 값

구현 핵심

복사 가능한 요청 예시는 각 엔드포인트에 있습니다. 운영 코드에는 아래 규칙을 적용하세요.

사용량 제한

대량 발송은 토큰과 계정 한도를 모두 고려합니다.

실제 계산

토큰 하나의 쓰기 5건/분 기준입니다.

요청 한도 초과

HTTP 429
Retry-After: 42                // 42초 뒤에 다시 오세요
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42

{ "error": { "code": "rate_limited",
            "details": { "retryAfterSeconds": 42,
                         "scope": "token" } } }

엔드포인트

모든 요청에 Authorization: Bearer {토큰} 헤더가 필요합니다.

{
  "actor": { "kind": "pat",
              "scopes": ["documents:write", "shares:write", "shares:read"] },
  "plan": {
    "code": "business",
    "maxExpiresInDays": 365,
    "allowedExpiresInDays": [1, 7, 90, 365],
    "maxShareRecipients": null,
    "maxUploadBytes": 262144000,
    "screenGuardAvailable": true
  }
}

# 파일을 가져옵니다. S3 사전 서명 URL을 그대로 보내도 됩니다.
curl -X POST $API/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://버킷.s3.ap-northeast-2.amazonaws.com/docs/계약서.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20260901%2Fap-northeast-2%2Fs3%2Faws4_request&X-Amz-Date=20260901T091500Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=b1d7c0f4e2a95c3d8f6b04e1a7c92d5f38ba61c4e07d92f5a3b8c61d4f290e7b",
       "name":"계약서.pdf"}'

{ "documentId": "doc_pJbchjs_mQ4QYKrkjTDkiA",
  "name": "계약서.pdf",
  "sizeBytes": 148231,
  "createdAt": "2026-08-27T00:00:00Z" }

계약서.pdf → 계약서 (2).pdf → 계약서 (3).pdf

{ "documentId": "doc_pJbchjs_mQ4QYKrkjTDkiA",
  "name": "계약서.pdf",
  "sizeBytes": 148231,
  "createdAt": "2026-08-27T00:00:00Z",
  "activeShares": 3 }                      // 살아 있는 공유 수

평소
DELETE /api/v1/documents/doc_pJbchjs_mQ4QYKrkjTDkiA

살아 있는 공유가 있어도 지울 때
DELETE /api/v1/documents/doc_pJbchjs_mQ4QYKrkjTDkiA?force=true

{ "id": "doc_pJbchjs_mQ4QYKrkjTDkiA",
  "deleted": true,
  "activeShares": 0,                          // force 로 지웠다면 방금 죽은 링크 수
  "restorableUntil": "2026-09-09T00:00:00Z" }

① file — 파일을 직접 올린다 · Content-Type: multipart/form-data

{ "file": (계약서.pdf 의 바이너리),
  "sender": {
    "name": "박영업",
    "email": "yh.park@company.com"
  },
  "recipient": {
    "name": "김민수",
    "email": "minsu@example.com",
    "phone": "010-1234-5678",
    "externalRef": "cus_1001",
    "metadata": {
      "contractId": "c-99",
      "branch": "강남",
      "staffId": "emp-042"
    }
  },
  "options": {
    "expiresInDays": 90,
    "personalNote": true,
    "branding": true,
    "watermark": false,
    "allowDownload": true,
    "screenGuard": false
  },
  "message": "{{recipient.name}}님, 요청하신 계약서를 보내드립니다. — {{sender.name}}"
}

multipart 의 폼 필드로 보냅니다 — 필드명은 위 키 그대로입니다.
객체인 항목(recipient·sender·options)은 JSON 문자열로 싣습니다.

② url — 파일이 있는 주소를 준다 · Content-Type: application/json

{ "url": "https://버킷.s3.ap-northeast-2.amazonaws.com/docs/계약서.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20260901%2Fap-northeast-2%2Fs3%2Faws4_request&X-Amz-Date=20260901T091500Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=b1d7c0f4e2a95c3d8f6b04e1a7c92d5f38ba61c4e07d92f5a3b8c61d4f290e7b",
  "name": "계약서.pdf",
  "sender": {
    "name": "박영업",
    "email": "yh.park@company.com"
  },
  "recipient": {
    "name": "김민수",
    "email": "minsu@example.com",
    "phone": "010-1234-5678",
    "externalRef": "cus_1001",
    "metadata": {
      "contractId": "c-99",
      "branch": "강남",
      "staffId": "emp-042"
    }
  },
  "options": {
    "expiresInDays": 90,
    "personalNote": true,
    "branding": true,
    "watermark": false,
    "allowDownload": true,
    "screenGuard": false
  },
  "message": "{{recipient.name}}님, 요청하신 계약서를 보내드립니다. — {{sender.name}}"
}

③ documentId — 미리 등록해 둔 문서를 쓴다 · Content-Type: application/json

{ "documentId": "doc_pJbchjs_mQ4QYKrkjTDkiA",
  "sender": {
    "name": "박영업",
    "email": "yh.park@company.com"
  },
  "recipient": {
    "name": "김민수",
    "email": "minsu@example.com",
    "phone": "010-1234-5678",
    "externalRef": "cus_1001",
    "metadata": {
      "contractId": "c-99",
      "branch": "강남",
      "staffId": "emp-042"
    }
  },
  "options": {
    "expiresInDays": 90,
    "personalNote": true,
    "branding": true,
    "watermark": false,
    "allowDownload": true,
    "screenGuard": false
  },
  "message": "{{recipient.name}}님, 요청하신 계약서를 보내드립니다. — {{sender.name}}"
}

{
  "id": "shr_fc1JjpkaDRRXwyKBG08uFg",        // 반드시 저장
  "links": {
    "recipient": "https://doc.throw.im/s/r/uO3xbWI4nQM8", // 고객에게 발송
    "host": "https://doc.throw.im/s/h/AaaaaAAAAA12", // 담당자 전용 · 저장 후 재사용
    "joinCode": "SFFCU" // 폐기 예정 — 사용하지 않음
  },
  "policy": { "expiresInDays": 90, "download": true, "watermark": false,
              "screenGuard": false, "personalNote": true, "branding": true },
  "adjustments": [],
  "recipient": { "name": "김민수", "externalRef": "cus_1001",
                  "metadata": null },
  "document": { "id": "doc_pJbchjs_mQ4QYKrkjTDkiA",   // 같은 파일을 또 보낼 때 재사용
                 "name": "계약서.pdf", "sizeBytes": 148231 },
  "request": {                                // 보낸 내용 그대로
    "options": { "expiresInDays": 90 },
    "message": "요청하신 계약서를 보내드립니다.",
    "recipient": { "name": "김민수", "email": "minsu@example.com",
                    "phone": null, "externalRef": "cus_1001", "metadata": null },
    "sender": null
  },
  "createdAt": "2026-08-27T00:00:00Z",
  "expiresAt": "2026-11-25T00:00:00Z"   // 링크가 죽는 시각
}

{ "id": "shr_fc1JjpkaDRRXwyKBG08uFg",
  "status": { "session": "WAITING",   // 아직 아무도 안 열었음
              "link": "active" },
  "links": { "recipient": "https://doc.throw.im/s/r/uO3xbWI4nQM8",
             "host": "https://doc.throw.im/s/h/AaaaaAAAAA12",
             "joinCode": "SFFCU" /* 폐기 예정 */ },
  "externalRef": "cus_1001",
  "expiresAt": "2026-11-25T00:00:00Z",
  "opened": { "count": 3, "lastAt": "2026-08-27T10:00:00Z" },
  "metadata": { "contractId": "c-99", "branch": "강남" },
  "downloads": { "count": 1 } }

{ "ok": true, "revokedAt": "2026-08-27T00:00:00Z" }

발신자 정보

sender는 고객 화면에 표시할 담당자 정보입니다. 전체 위치와 형태는 위의 세 Shares 요청 예시에서 확인하세요.

생략하면 docs 계정 이름이 표시됩니다. email은 생략할 수 있습니다.

공유 옵션

모든 항목을 생략할 수 있으며 기본값이 적용됩니다.

응답 형식

policy는 적용값, request는 인식한 요청, adjustments는 둘의 차이입니다.

자동 조정

아래 두 경우만 adjustments에 기록됩니다. 요금제 상한 초과는 403입니다.

request.options에는 서버가 인식한 키만 들어갑니다. 생략하면 null입니다.

오류 코드

message가 아닌 error.code로 분기하세요.

{ "error": {
    "code": "retention_exceeds_plan_limit",
    "message": "expiresInDays cannot exceed the current plan retention limit",
    "requestId": "req_8kZq3mVx7pLnR2wTy4",
    "details": { "requested": 365, "limit": 90 } } }

인증·권한

요청 내용

파일·문서

재시도·조회·서버

404는 없는 공유와 남의 공유를 구분하지 않습니다. 다른 계정의 공유 존재 여부는 알려주지 않습니다.

웹훅

고객이 문서를 열면 throw가 지정한 서버로 알림을 보냅니다. 폴링 대신 쓰세요.

공유 생성
  ├─▶ 링크 열림                알림 없음
  │     └─▶ 입장               ● share.opened
  │           ├─▶ 다운로드     ● share.downloaded
  │           └─▶ 게스트 메모  ● share.memo_created
  ├─▶ 유효기간 끝              ● share.expired
  └─▶ 회수                     알림 없음

●이 붙은 곳에서만 웹훅이 나갑니다.

share.opened는 실제 문서 진입 시 발생하며 링크 클릭과 회수는 알리지 않습니다.

POST /webhooks — 등록

필요 권한은 shares:read입니다. 등록한 계정이 만든 공유에서만 이벤트를 받습니다.

curl -X POST $API/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CRM 알림",
       "url": "https://crm.회사.com/hooks/throw",
       "events": ["share.opened", "share.downloaded", "share.expired", "share.memo_created"] }'

// 201 — 등록 완료
{ "id": "whk_Fh7daz1oQZmXvKr3tSNbLw",
  "name": "CRM 알림",
  "url": "https://crm.회사.com/hooks/throw",
  "events": ["share.opened", "share.downloaded", "share.expired", "share.memo_created"],
  "status": "active",
  "createdAt": "2026-08-27T09:00:00Z" }

잘못된 이름·URL·이벤트 또는 계정당 3개 제한 초과는 400 bad_request, 권한이 없으면 403 missing_scope입니다. 제한을 넘으면 error.details.limit가 반환됩니다.

담당자에게 알림 보내기

웹훅 데이터로 담당자를 찾은 뒤 사내 알림을 보내세요.

웹훅 헤더

모든 알림에 아래 헤더가 포함됩니다.

이벤트별 요청 본문

네 이벤트의 공통 헤더 형식은 같습니다. X-Throw-Event와 본문의 event가 해당 이벤트 이름으로 바뀝니다.

POST https://crm.회사.com/hooks/throw
X-Throw-Event: share.opened
X-Throw-Delivery: dlv_90

share.opened — 고객이 문서에 실제로 들어왔을 때

{ "event": "share.opened",
  "webhookId": "whk_TAGr3xSZ2NpXeB4YSBqabQ",
  "createdAt": "2026-08-27T10:00:00Z",
  "data": {
    "links": {
      "host": "https://doc.throw.im/s/h/AaaaaAAAAA12xxxxxxxxxxxxxxxxxxxxxx",
      "recipient": "https://doc.throw.im/s/r/uO3xbWI4nQM8"
    },
    "shareId": "shr_1EuEW9BtUXqT4mLpKzR8Vw",
    "externalRef": "cus_9911",
    "metadata": { "contractId": "c-99", "branch": "강남" },
    "viewer": { "name": "김민수" },
    "sender": { "name": "박영업", "email": "yh.park@회사.com" }
  } }

share.memo_created — 게스트가 메모를 만들었을 때

{ "event": "share.memo_created",
  "webhookId": "whk_TAGr3xSZ2NpXeB4YSBqabQ",
  "createdAt": "2026-08-27T10:05:00Z",
  "data": {
    "shareId": "shr_1EuEW9BtUXqT4mLpKzR8Vw",
    "externalRef": "cus_9911",
    "metadata": { "contractId": "c-99" },
    "viewer": { "name": "김민수" },
    "sender": { "name": "박영업", "email": "yh.park@회사.com" },
    "memo": { "id": "memo_01", "page": 2, "visibility": "all", "text": "확인 부탁드립니다." }
  } }

share.downloaded — 원본 파일 다운로드 요청이 처리됐을 때

{ "event": "share.downloaded",
  "webhookId": "whk_TAGr3xSZ2NpXeB4YSBqabQ",
  "createdAt": "2026-08-27T10:03:00Z",
  "data": {
    "shareId": "shr_1EuEW9BtUXqT4mLpKzR8Vw",
    "externalRef": "cus_9911",
    "metadata": { "contractId": "c-99", "branch": "강남" },
    "viewer": { "name": "김민수" },
    "sender": { "name": "박영업", "email": "yh.park@회사.com" }
  } }

share.expired — 공유 유효기간이 끝났을 때

{ "event": "share.expired",
  "webhookId": "whk_TAGr3xSZ2NpXeB4YSBqabQ",
  "createdAt": "2026-11-25T00:00:00Z",
  "data": {
    "shareId": "shr_1EuEW9BtUXqT4mLpKzR8Vw",
    "externalRef": null,
    "metadata": null,
    "viewer": null,
    "sender": { "name": "박영업", "email": "yh.park@회사.com" }
  } }

수신 서버 예시

알림에 필요한 값만 확인해 받은 편지함에 저장한 뒤 응답합니다. 실제 채팅 알림은 작업 큐에서 보냅니다.

// 등록할 때 알려 준 그 주소
app.use(express.json())
app.post('/hooks/throw', async (req, res) => {
  const deliveryId = String(req.headers['x-throw-delivery'] || '')
  const payload = req.body
  // API 점검 도구의 단발 테스트. 업무 이벤트로 저장하지 않는다.
  if (payload?.event === 'webhook.test') return res.status(204).end()

  const allowed = ['share.opened', 'share.downloaded', 'share.expired', 'share.memo_created']
  if (!deliveryId || !allowed.includes(payload?.event) || !payload?.data?.shareId) {
    return res.status(400).end()
  }

  // 본문의 고객 정보는 그대로 믿지 않고, 저장해 둔 shareId로 발송 건을 찾는다.
  const shareRecord = await crmShares.findByThrowShareId(payload.data.shareId)
  if (!shareRecord) return res.status(200).end()

  // deliveryId에 UNIQUE를 걸어 같은 알림은 한 번만 저장한다.
  await webhookInbox.insertOnce({ deliveryId, event: payload.event, shareId: payload.data.shareId })
  res.status(200).end() // 10초 안에 응답
})

받은 편지함을 처리하는 작업자가 이벤트별 문구를 만든 뒤 사내 채팅 API를 호출하세요. 자동 처리의 근거가 필요하면 저장한 shareId로 GET /shares/{id}를 조회해 현재 상태를 확인하세요.

수신 서버 체크 사항

재시도

2xx가 아니면 4xx를 포함해 다시 보냅니다.

1회차 즉시 → 1분 → 5분 → 30분 → 2시간 → 6시간   (총 6회 · 약 9시간)

• 연속 20회 실패하면 자동 비활성화됩니다. 해제 후 다시 등록하세요.
• 상태 확인과 관리는 마이페이지 → 웹훅에서 할 수 있습니다.

조회·해제

아래 API도 Authorization: Bearer {토큰}과 shares:read 권한이 필요합니다.

GET /webhooks 응답

[
  { "id": "whk_Fh7daz1oQZmXvKr3tSNbLw",
    "name": "CRM 알림",
    "url": "https://crm.회사.com/hooks/throw",
    "events": ["share.opened", "share.downloaded", "share.expired", "share.memo_created"],
    "status": "active",
    "consecutiveFailures": 0,
    "lastDeliveredAt": "2026-08-27T10:03:01Z",
    "createdAt": "2026-08-27T09:00:00Z" }
]

웹훅 전달 점검

API 점검 도구의 05 웹훅에서 인증용 토큰을 입력하고 열람·다운로드·만료·메모 작성 중 테스트할 이벤트를 선택하세요. 메타데이터(키/값 최대 3쌍)를 입력한 뒤 테스트 실행을 누르면 선택한 이벤트의 임의 데이터를 점검 도구의 수신 서버로 실제 전송합니다. 같은 화면에서 수신 확인된 헤더·JSON·수신 시각을 볼 수 있습니다. 별도 CRM 수신 주소는 필요하지 않습니다.

열람에는 data.links, 메모 작성에는 data.memo가 포함됩니다. 만료 이벤트는 실제 규격과 동일하게 metadata·externalRef·viewer가 null이며 입력한 메타데이터도 전달하지 않습니다.

문서·공유·열람 기록이나 임시 웹훅 등록은 만들지 않으며, 기존 CRM에도 보내지 않습니다. JSON의 data.metadata에서 입력값을 확인하세요. 고객·담당자 정보와 data.links는 임의 데이터이며 링크는 사용할 수 없습니다. 테스트 요청에는 X-Throw-Test: true가 포함됩니다. 수신 결과는 이 화면에서만 표시하며 입력 변경·새로고침 시 지워집니다. 기존 API 토큰 사용 기록은 갱신됩니다. CRM 수신 서버 자체를 점검하려면 아래 등록 주소 테스트를 사용하세요.

POST /webhooks/{id}/test — 요청 본문은 없습니다.

등록 주소로 아래 요청을 즉시 한 번 보냅니다. 공유나 업무 이벤트를 만들지 않고 테스트 전달 이력은 DB에 기록하지 않으며, 실패해도 재시도하지 않습니다. 기존 API 토큰 사용 기록은 갱신됩니다.

POST https://crm.회사.com/hooks/throw
Content-Type: application/json
X-Throw-Event: webhook.test
X-Throw-Delivery: dlv_test_Yt7dM2pQ

{ "event": "webhook.test",
  "webhookId": "whk_Fh7daz1oQZmXvKr3tSNbLw",
  "createdAt": "2026-09-07T03:00:00.000Z",
  "data": { "test": true } }

응답의 request에는 실제 보낸 주소·헤더·본문이, response에는 수신 서버의 상태 코드·처리 시간·오류가 들어갑니다. ok가 false여도 이 API 자체는 200으로 응답하므로 response를 확인하세요.

{ "deliveryId": "dlv_test_Yt7dM2pQ",
  "request": {
    "method": "POST",
    "url": "https://crm.회사.com/hooks/throw",
    "headers": {
      "Content-Type": "application/json",
      "X-Throw-Event": "webhook.test",
      "X-Throw-Delivery": "dlv_test_Yt7dM2pQ"
    },
    "body": { "event": "webhook.test", "webhookId": "whk_Fh7daz1oQZmXvKr3tSNbLw", "createdAt": "2026-09-07T03:00:00.000Z", "data": { "test": true } }
  },
  "response": { "ok": true, "statusCode": 204, "durationMs": 82, "error": null } }

GET /webhooks/{id}/deliveries?limit=20

실제 share.opened·share.downloaded·share.expired·share.memo_created 전달을 최신순으로 조회합니다. 각 항목에는 전송 헤더와 JSON 본문, 상태, 시도 횟수, 마지막 HTTP 응답과 실패 원인이 포함됩니다. 전송 대기 건은 전송 예정 내용이며, 수신 서버 내부 처리 완료 여부는 확인할 수 없습니다. limit은 1~100이며 기본값은 20입니다. 단발 테스트는 이 목록에 나타나지 않습니다.

DELETE /webhooks/{id} 응답 — 요청 본문은 없습니다.

{ "ok": true,
  "removedAt": "2026-08-27T11:00:00Z" }

형식이 잘못됐거나 없거나 다른 계정의 웹훅 ID는 모두 404 not_found로 반환합니다.

운영 참고사항

토큰

무중단으로 토큰 바꾸기

① 새 토큰 발급        (이 시점에 활성 2개)
② 연동 시스템에 반영
③ 옛 토큰 회수        ← 순서를 지키면 끊기지 않습니다

현재 지원하지 않는 기능

연동 체크리스트

운영 배포 전에 확인하세요.

• 담당자별 토큰을 발급하고 서버에만 보관했습니다
• Idempotency-Key와 공유 id를 발송 기록에 함께 저장합니다
• error.code로 분기합니다
• 429를 받으면 Retry-After만큼 기다립니다
• 쓰기 5건/분 기준으로 대량 발송 시간을 계산했습니다
• 같은 파일은 documentId를 재사용합니다
• links.host를 담당자 화면에 저장하고 고객에게 전달하지 않습니다
• 고객 안내는 policy를 기준으로 작성합니다
• 토큰 회수 절차를 문서화했습니다