Reference
v0.2
API 문서
OfficeMate HWP2PDF API v0.2 / 기본 URL: https://officemate.trendfactory.kr
인증
API는 두 가지 인증 방식을 사용합니다:
| 용도 | 헤더 | 설명 |
|---|---|---|
| 회원 기능 | Authorization: Bearer JWT_TOKEN | 로그인 후 받은 JWT 토큰 |
| 파일 변환 | X-API-Key: YOUR_API_KEY | 승인된 API 키 |
info
API 키를 외부에 노출하지 마세요. GitHub, 클라이언트 사이드 코드 등에 포함하면 안 됩니다.
회원가입 / 로그인
POST
/api/auth/register
새 계정을 생성합니다.
curl -X POST https://officemate.trendfactory.kr/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "mypassword",
"name": "홍길동"
}'
POST
/api/auth/login
로그인하여 JWT 토큰을 받습니다. 토큰 유효기간은 24시간입니다.
curl -X POST https://officemate.trendfactory.kr/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "mypassword"}'
API 키 관리
POST
/api/keys
새 API 키를 신청합니다. 관리자 승인 후 사용 가능합니다.
curl -X POST https://officemate.trendfactory.kr/api/keys \
-H "Authorization: Bearer JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "내 웹서비스", "description": "사내 문서 변환 시스템"}'
GET
/api/keys
내 API 키 목록을 조회합니다.
DELETE
/api/keys/{id}
API 키를 폐기합니다.
POST
/api/convert
HWP 또는 HWPX 파일을 PDF로 변환합니다.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| file | file | required | .hwp 또는 .hwpx 파일 |
성공 응답: 200 OK, Content-Type: application/pdf
에러 응답
| 코드 | 설명 |
|---|---|
| 401 | API 키 누락 또는 유효하지 않음 |
| 403 | API 키가 미승인 상태 |
| 422 | HWP 파싱 또는 변환 실패 |
| 429 | 사용량 제한 초과 |
사용량 조회
GET
/api/usage
현재 API 키의 일일/월간 사용량을 조회합니다.
변환 이력
GET
/api/history
변환 이력을 페이징하여 조회합니다. ?page=1&limit=20
사용량 제한
| 항목 | 일일 제한 | 월간 제한 |
|---|---|---|
| 변환 횟수 | 100건 | 3,000건 |
| 업로드 용량 | 500 MB | 10,000 MB |
| 파일 크기 | 최대 50 MB / 건 | |
제한 초과 시 429 Too Many Requests 응답이 반환됩니다.
에러 코드
| HTTP 코드 | 설명 |
|---|---|
| 400 | 잘못된 요청 |
| 401 | 인증 실패 |
| 403 | 권한 없음 |
| 404 | 리소스를 찾을 수 없음 |
| 409 | 충돌 (이미 등록된 이메일 등) |
| 422 | 처리 불가 (변환 실패) |
| 429 | 사용량 제한 초과 |
| 500 | 서버 내부 오류 |
모든 에러 응답 형식: {"error": "에러 메시지"}
헬스체크
GET
/api/health
{"status": "ok", "version": "0.2.0", "engine": "0.7.2"}
Request Example (cURL)
curl -X POST "https://officemate.trendfactory.kr/api/convert" \ -H "X-API-Key: om_a1b2c3d4..." \ -F "file=@document.hwp" \ -o result.pdf
Python
import requests with open('doc.hwp', 'rb') as f: res = requests.post( 'https://officemate.trendfactory.kr/api/convert', headers={'X-API-Key': 'om_...'}, files={'file': f} ) with open('result.pdf', 'wb') as f: f.write(res.content)
Response (200 OK)
Content-Type: application/pdf
Content-Disposition: attachment
# PDF binary data
Auth Response
{ "token": "eyJ0eXAi...", "user": { "id": 1, "email": "user@example.com", "name": "홍길동", "role": "user" } }