/api/v1 엔드포인트 — 인증, 요청 한도, 오류, 명세서·도면·OA·사건·검색·보고서, 예시 코드.
CLI 가 쓰는 것과 같은 API 입니다. 기본 주소는 https://inventips.net/api/v1 이고, 모든 요청에 개인 토큰을 넣습니다. 처음이면 빠른 시작부터 보세요.
Authorization: Bearer itp_xxxxxxxx...
토큰은 마이페이지 → 보안 → CLI 토큰에서 발급합니다. AI 커넥터가 만든 토큰(MCP · ...)으로는 이 API 를 쓸 수 없습니다.
인증
- 헤더는
Authorization: Bearer <토큰> 하나입니다. 토큰은 itp_ 뒤에 43자(영문·숫자·-·_)가 붙은 형태이고, 형식이 틀리면 서버가 확인하지 않고 401 을 돌려줍니다.
- 토큰 권한은
read(조회·내보내기)와 write(크레딧을 쓰거나 내용을 바꾸는 요청)입니다. 읽기 전용 토큰으로 쓰기 요청을 보내면 403 입니다. 표의 「권한」 칸이 각 요청에 필요한 권한입니다.
- 커넥터(OAuth) 토큰은 권한과 상관없이
403 입니다. REST API 에는 마이페이지에서 발급한 CLI 토큰을 씁니다.
- 승인된 계정의 유효한 토큰만 통과합니다. 만료·폐기된 토큰과 승인이 취소된 계정의 토큰은
401 입니다.
- 토큰은 토큰 주인의 문서만 봅니다. 사무소 사건에 묶인 작업은 그 사건을 볼 수 있는 사람이 읽기·내려받기만 할 수 있습니다(명세서·OA·우선심사 조회와 내보내기, 보고서). 볼 수 없는 문서는 없는 것처럼
404 입니다.
- 기한이 있는 토큰이면 응답에
X-Token-Expires-At 이 붙고, 만료 14일 안으로 들어오면 X-Token-Expires-In-Days 도 붙습니다.
요청과 응답
- 본문은 JSON 객체입니다(
Content-Type: application/json). 비어 있으면 {} 로 봅니다. 파일은 base64 문자열(data:...;base64, 접두 허용)로 넣습니다. 이미지 디자인 검색(POST /search/designs)만 multipart 입니다.
- 본문 상한은 기본 20MB 이고, 첨부를 받는 요청은 따로 정해져 있습니다(명세서 첨부 10개·합계 20MB, OA·우선심사 첨부 합계 25MB, 파일 하나 20MB). 넘으면
413.
- 오래 걸리는 작업은
202 {taskId, status: "pending"} 를 바로 돌려줍니다. GET /tasks/:taskId 의 status 가 pending → running → completed 또는 failed 로 바뀌고, 끝나면 result 가 붙습니다. 알림 주소를 등록하면 끝날 때 서버가 알려 줍니다(아래 「작업 완료 알림」).
- 크레딧을 쓰는 요청에
?dryRun=1 을 붙이면 실행하지 않고 예상 크레딧과 잔액만 돌려줍니다({dryRun, action, estimatedCredits, balance, note?}). 실제 실행 전에도 잔액이 예상치보다 적으면 402 로 멈춥니다.
- 쓰기 요청에
Idempotency-Key 헤더(영문·숫자·._:- 8~200자)를 붙이면 같은 토큰·같은 키로 다시 보낸 요청에 첫 응답을 그대로 돌려줍니다(24시간, 응답 헤더 Idempotent-Replayed: true). 첫 요청이 아직 처리 중이면 409, 같은 키로 다른 내용을 보내면 422 입니다. 파일 응답과 5xx 는 남기지 않아 다시 보내면 다시 실행합니다. dryRun 과 /me/* 에는 쓰지 않습니다.
- 파일을 돌려주는 요청은 JSON 이 아니라 파일 바이트와
Content-Disposition(UTF-8 파일 이름)을 돌려줍니다. 오류는 이때도 JSON 입니다.
요청 한도
| 구분 | 상한 | 넘으면 |
|---|
| 토큰당 전체 요청 | 분당 120회 | 429 요청이 너무 많습니다. |
| 계정 합계(토큰·커넥터 전부) | 분당 300회 | 429 요청이 너무 많습니다(사용자 합계). |
| 무거운 요청(아래), 토큰당 | 분당 10회 | 429 생성·내보내기 요청이 너무 많습니다(분당 10회). |
| 인증 실패, 접속 IP 당 | 분당 20회 | 그 창이 끝날 때까지 모든 요청 429(Retry-After: 60) |
| 한번에 생성 동시 실행 | 서버 설정값 | 429 한번에 생성은 동시에 N개까지입니다. |
- 무거운 요청은 생성·분석 시작(한번에 생성, 도면 재생성·일괄 생성, 수정 분석, 선행조사, 상표 보고서, OA 분석·의견서·메일, 우선심사 생성, 경쟁기업 조사, 이미지 디자인 검색, 사건 단계 실행)과 파일 만들기(명세서·OA·우선심사 내보내기, hlz 점검, 위임장 만들기·PDF)입니다.
dryRun 은 무거운 요청으로 세지 않습니다.
429 응답에는 Retry-After(초) 헤더와 본문 retryAfterSec 가 있습니다. 그만큼 기다린 뒤 다시 보내세요.
- 1분 고정 창으로 셉니다.
오류
오류 응답은 {"error": "설명"} 형태입니다. 상황에 따라 필드가 더 붙습니다(402 의 estimatedCredits·balance, 429 의 retryAfterSec).
{ "error": "크레딧이 부족합니다(필요 5, 잔액 2).", "estimatedCredits": 5, "balance": 2 }
| 상태 | 뜻 |
|---|
| 400 | 요청 형식이 틀림(필수 값 없음, 허용하지 않는 값, JSON 객체가 아님, 잘못된 Idempotency-Key) |
| 401 | 토큰 없음·형식 오류·만료·폐기, 또는 승인되지 않은 계정 |
| 402 | 크레딧 부족(estimatedCredits, balance 포함) |
| 403 | 토큰에 필요한 권한(read/write)이 없음, 또는 커넥터 토큰 |
| 404 | 없는 문서·작업(남의 문서도 404) |
| 409 | 지금 상태로는 할 수 없음 — 확정 대기 중 수정 분석, 작업이 도는 중에 고치기·다시 시작, 이미 반영한 제안, 한 칸씩이 아닌 사건 단계 변경, 같은 Idempotency-Key 처리 중 |
| 410 | 분석 뒤 정리된 OA 원본 파일 |
| 413 | 본문·첨부가 너무 큼 |
| 422 | 같은 Idempotency-Key 로 다른 요청, 보정서(dta)를 만들 수 없는 원본·고친 명세서 |
| 429 | 요청 한도 초과(Retry-After 헤더) |
| 500 | 서버 오류 |
| 502 | KIPRIS 등 외부 검색 실패 |
| 503 | 백그라운드 작업을 시작하지 못함(잠시 뒤 다시) |
엔드포인트
경로는 모두 /api/v1 아래입니다. 「권한」은 필요한 토큰 권한이고, 크레딧은 웹에서 같은 작업을 할 때와 같습니다.
계정·알림
| 메서드·경로 | 권한 | 설명 |
|---|
GET /me | read | 토큰 주인·잔여 크레딧·토큰 권한 {userId,name,firmName,tier,credits,isBenchmark,token:{id,name,scopes,expiresAt,notifyUrl}} |
GET /me/notify | read | 이 토큰의 알림 주소 {token,url} |
PUT /me/notify | write | 알림 주소 등록 {"url":"https://..."} → {token,url,secret,signature}. secret 은 이 응답에서만 보입니다 |
DELETE /me/notify | write | 알림 끄기 |
POST /me/notify/test | write | 시험 알림(event: test)을 보내고 받은 상태 코드 {ok,status} |
GET /metrics?days=30 | read | 사건→출원 전환·기간, 단계 이동(사람·봇), 토큰별 쓰기 요청 |
명세서
| 메서드·경로 | 권한 | 설명 |
|---|
GET /drafts?limit=&all=1 | read | 명세서 목록 {drafts:[{id,title,step,docType,updatedAt}]}(limit 기본 50, 최대 200). all=1 이면 OA 등 다른 문서 포함 |
POST /drafts | write | 명세서 새로 만들기 {title?,text?,requirements?,claimsText?,files?:[{name,mimeType,data(base64)}],matterId?,options?:{autoFinalize,claimStrategyPreference,priorArtRoundsMax,skipPriorArtSearch,manualPriorArtNotes,priorArtNumbers,targetPages,provisional,priorArtCutoffDate,priorArtExcludeNumbers,draftMode}} → 201 {id, title, files, claims, claimsFormality?} — text 나 files 중 하나는 있어야 한다. claimsFormality 는 넣은 청구범위의 기재불비 표현(중간점·"등"·및/또는·다중종속·인용항 오류) 목록이다. 청구범위는 그대로 저장되니 호출한 쪽이 고쳐 다시 넣는다. claimStrategyPreference 는 broad·narrow·workaround, priorArtRoundsMax 는 1 또는 3, targetPages 는 5~200, draftMode 는 pipeline·direct(간단 모드). 크레딧 없음 |
POST /drafts (후속출원) | write | 본문에 source 를 주면 후속출원·명세서 가져오기 {source:{kind:"divisional"|"continuation"|"priority"|"import", draftId | applicationNumber | file:{name,mimeType,data(base64)}, splitSections?}, title?, requirements?, matterId?} → 201 {id,title,claims,source,next}. 원본의 청구항·본문을 옮긴 새 명세서(크레딧 없음). 원본은 하나만, text·claimsText·files·options 와 함께 쓸 수 없다(400). 남의 명세서·없는 공보는 404. 후속출원 지침을 넣어 다시 쓰려면 POST /drafts/:id/generate {"resume":false} |
GET /drafts/:id | read | 요약 {id,title,step,updatedAt,clientHold,pendingQuestions,claims:{count,independent},sections,figures,validation,priorArt}. ?full=1 이면 본문 전체(content) |
GET /drafts/:id/status | read | 최근 백그라운드 작업 {draftId,tasks:[{id,type,status,step,detail,percent,error,createdAt,updatedAt}]}(결과는 GET /tasks/:taskId) |
POST /drafts/:id/generate | write | 한번에 생성 {resume?,proceed?,answers?,excludePriorArt?,priorArtCutoffDate?,useStyle?,provisional?}(provisional 은 가출원(임시 출원)용 켜기·끄기 — 청구항 1개, 전략·설계·검증 끔, 실시예 두껍게. 청구항이 있으면 resume:false 와 함께, 아니면 409) → 202 {taskId, draftId, estimatedCredits}(약 25분, 단계별 크레딧). ?dryRun=1 은 {estimatedCredits,minimumCredits,balance,openQuestions}. 핵심 확인 질문에서 멈추면 task result.awaitingMaterialCheck — GET /drafts/:id 의 pendingQuestions 를 보고 proceed 또는 answers 로 다시. resume:false 는 처음부터, useStyle:true 는 내 작성 스타일(본인 프로필) 적용 |
POST /drafts/:id/hold / DELETE /drafts/:id/hold | write | 확정 대기 {reason} — 걸려 있으면 revise 가 409 |
POST /drafts/:id/revise | write | 수정 분석 작업 시작 {instruction}(1 크레딧~) → 202 {taskId, status}. 아래 「수정 분석 본문」 |
POST /drafts/:id/revise/:taskId/apply | write | 수정 제안 반영 {"sections":["backgroundArt","claims"]}(생략 시 전체) → {applied:true, …, note} — 크레딧 없음 |
POST /drafts/:id/confirm-requests | write | 고객 출원 동의 링크 {"email"?,"note"?,"send"?} → 201 {id,version,url,expiresAt,sent,sentTo} |
GET /drafts/:id/confirm-requests | read | 동의 요청·결과 {requests[]}(최신 먼저, effectiveStatus: pending·confirmed·cancelled·expired·changed) |
POST /drafts/:id/export | read | {"format":"docx"|"hlz"|"zip"} → 파일 바이트. hlz 응답에는 요약 헤더 X-Hlz-Check(JSON base64url {ok,errors,warnings,codes}) |
POST /drafts/:id/export/check | read | hlz 점검 보고서 {format,filename,size,ok,errors[],warnings[]}(각 {code,message,detail?}). 파일은 돌려주지 않음 |
도면
| 메서드·경로 | 권한 | 설명 |
|---|
GET /drafts/:id/figures/:figId/image | read | 현재 도면 내려받기 주소 {figureId,url,mimeType,description}(서명 URL 1시간) |
GET /drafts/:id/figures/:figId/history | read | 도면 이력 {figureId,current,history:[{index,timestamp,label,hasImage,storagePath,previewUrl}]}(미리보기 URL 1시간) |
POST /drafts/:id/figures/:figId/history/:index/apply | write | 이력 버전을 현재 도면으로 {figureId,appliedIndex,storagePath,historyCount} |
PUT /drafts/:id/figures/:figId/image | write | 올린 이미지로 바로 교체 {"imageBase64":"...","mimeType":"image/png","label"?} — PNG·JPEG·WEBP 10MB 이하, 크레딧 없음, 이전 도면은 이력 0번 |
POST /drafts/:id/figures | write | 도면 칸 추가 {"imageBase64","mimeType","position"?,"caption"?,"updateRefs"?} — 크레딧 없음, 201 |
DELETE /drafts/:id/figures/:figId?updateRefs=1 | write | 도면 칸 삭제, 뒤 번호를 당김 |
POST /drafts/:id/figures/reorder | write | 순서 변경 {"order":[2,1,3],"updateRefs"?} |
POST /drafts/:id/figures/:figId/regenerate | write | 도면 한 장 재생성(10 크레딧) → 결과와 creditsCharged. 아래 「도면 재생성 본문」 |
POST /drafts/:id/figures/generate | write | 도면 일괄 생성 {sections?:{briefDescriptionOfDrawings?,detailedDescription?,descriptionOfReferenceNumbers?},figures?:[1,2],force?,model?} → 202 {taskId,figures,estimatedCredits}(한 번에 20장까지, 장당 10 크레딧). figures 를 비우면 이미지 없는 칸 전부, force 면 있는 것도 다시. ?dryRun=1 |
updateRefs 를 켜면 본문의 "도 N" 참조도 번호에 맞춰 고칩니다. 【도면의 간단한 설명】·대표도는 항상 같이 고칩니다.
OA 대응
| 메서드·경로 | 권한 | 설명 |
|---|
GET /oa?limit= | read | OA 사건 목록 {cases[]} |
POST /oa | write | OA 사건 만들기(크레딧 없음) {ipType?,responseMode?,title?,sourceDraftId?,matterId?,originalClaims?,priority?,protectedClaims?,excludedLimitations?,files:[{name,mimeType,data,role}]} → 201 {id,title,ipType,responseMode,files}. ipType 은 patent(기본)·trademark·design, responseMode 는 office-action(기본)·voluntary-amendment·foreign-instruction, role 은 notice·spec·ref·prior. 통지서 대응은 notice 가, 특허 사건은 spec 이 필요하다. 해외 지시서 사건은 jurisdiction(US·EP·JP·CN·OTHER)과 oaStage·letterFormat·letterLanguage·budgetGuidance·clientPreference |
GET /drafts/:id/oa | read | 사건 상태 — 자료 수, 분석(거절이유·인용문헌·대응 전략), 의견서·보정서 본문, 진행 중인 작업. 끝난 작업 결과는 이 조회에서 반영된다(justApplied). noticeStage 는 통지서 원문에서 읽은 절차 단계 — 아래 「거절결정 대응」 |
POST /drafts/:id/oa/analyze | write | 거절이유 분석·대응 전략 {feedback?, procedure?}(5 크레딧) → 202 {taskId,status}. procedure 는 거절결정 대응 절차 reexamination·appeal — 사건에 남기고 그 절차로 분석한다. 고를 수 없는 절차면 400. ?dryRun=1. 작업이 도는 중이면 409 |
POST /drafts/:id/oa/opinion | write | 고른 전략으로 의견서·보정서(자진보정은 보정안) {strategy?(1부터),feedback?,procedure?}(30 크레딧) → 202 {taskId,strategy,status}. 분석 전이면 409. 거절결정 사건은 분석이 전제한 절차와 만들려는 절차가 다르면 409 {analyzedProcedure,procedure}. ?dryRun=1 |
PATCH /drafts/:id/oa | write | 고친 본문 저장 {opinionText?, amendmentText?, instructionLetter?, clientEmail?, rationale?} → {updated} — 웹 저장과 같고 버전을 남긴다. 작업이 도는 중이면 409 |
POST /drafts/:id/oa/email | write | 고객 안내 메일 초안 {feedback?} → {clientEmail}(크레딧 CHAT, 사건에 저장). ?dryRun=1 |
GET /drafts/:id/oa/export?format= | read | 결과 파일. docx(기본, 의견서·보정서)·tracked-docx(보정 변경추적본)·opinion-hlz(의견서 hlz)·amendment-dta(보정서 dta)·fin(출원 원본에 보정서를 붙인 FIN) |
GET /drafts/:id/oa/files | read | OA 사건 원본 목록 |
GET /drafts/:id/oa/files/:fileId | read | 원본 파일 바이트(정리됐으면 410) |
GET /drafts/:id/oa/summary | read | 통지서 서지·거절이유·인용문헌·분석 요약 |
POST /kipo/dta | read | 원본·고친 명세서 비교 보정서 {original:{name,data(base64)} (.hlz·.fin), amended:{name,data} (.hlz)} → {filename, data(base64), summary:{title, paragraphs[], abstract[], claimsReplaced[], claimsDeleted[]}}. 저장·크레딧 없음. 원본에 없는 단락은 앞 단락에 합치고 summary.merged 에 남긴다. 단락 삭제와 추가가 함께 있으면 422 |
사건
| 메서드·경로 | 권한 | 설명 |
|---|
GET /matters?limit=&offset=&q=&state=&code=&appNumber=&client=&externalOrderId= | read | 사건 목록 {matters[],nextOffset}(limit 기본 50, 최대 200). 다음 쪽은 offset 에 nextOffset |
POST /matters | write | 사건 만들기 {title, rightType?, caseState?, code?, folderPath?} → 201. rightType 은 patent·trademark·design·utility·pct·overseas |
GET /matters/:id | read | 사건 카드 {drafts,delegations,quotations,payments,docket,researches,searches,checklist[{key,label,done,detail}],nextStep,nextStepKey} |
PATCH /matters/:id | write | 사건카드 고치기 {code?,title?,folderPath?,folderRef?,rightType?,clientName?,clientEmail?,applicantCode?,memo?,teamId?} |
POST /matters/:id/stage | write | 사건 단계 변경 {to, note?} → {from,fromLabel,to,toLabel}. 한 칸씩만, 아니면 409 |
POST /matters/:id/filing | write | 출원 접수 기록 {applicationNumber, filingDate?(YYYY-MM-DD), receiptNumber?, note?} → 201. 제출은 사람이 특허로에서 |
POST /matters/:id/works / DELETE /matters/:id/works | write | 작업 잇기·떼기 {draftId} 또는 {searchId} |
POST /matters/:id/assignees / DELETE /matters/:id/assignees | write | 사무소 사건 담당자 지정·해제 {userId} 또는 {email}(대표·관리자만) |
GET /matters/:id/plan | read | 사건함·작업을 보고 다음 할 일 제안(크레딧 없음). 단계마다 key·action·쓸 파일·이유·크레딧 여부 |
POST /matters/:id/run | write | 제안 단계 실행 {key, params?, confirm?}. 크레딧이 드는 단계는 confirm:true 일 때만 실행하고, 없으면 예상 크레딧을 돌려준다 |
사건 단계 코드는 requested(요청접수) → researching(조사중) → report_sent(보고서발송) → quoted(견적발송) → approved(승인) → awaiting_payment(입금대기) → paid(입금확인) → invoiced(계산서발행) → closed(종결), 그리고 canceled(취소)입니다.
사건함 파일
| 메서드·경로 | 권한 | 설명 |
|---|
GET /matters/:id/files?kind= | read | 사건함 목록(자동 분류한 서류 종류·읽어 낸 값 meta) |
POST /matters/:id/files | write | 파일 올리기 {files:[{name,mimeType,data(base64),kind?}]} → 201. 무슨 서류인지 자동 분류 |
POST /matters/:id/files/upload-url | write | 큰 파일(25MB 초과, 100MB 까지)용 서명 업로드 주소 {name} → signedUrl 로 PUT |
POST /matters/:id/files/register | write | 서명 URL 로 올린 파일 등록 {path,name,mimeType,kind?,source?,sourceRef?} → 201. 같은 파일·같은 원본이면 duplicate: true |
GET /matters/:id/files/:fileId | read | 내려받기 서명 URL(10분) |
PATCH /matters/:id/files/:fileId | write | 분류 고치기 {kind} |
POST /inbox/classify | read | 사건을 모르는 파일 분류 {files:[{name,mimeType,data}],fromEmail?,clientName?} → 서류 종류와 사건 후보(근거·점수). 저장·크레딧 없음 |
위임장
| 메서드·경로 | 권한 | 설명 |
|---|
POST /delegations | write | 기본 양식으로 위임장 초안 {"applicantName","signerEmail"?,"signerPhone"?,"deliveryChannel"?,"inventionTitle"?,"draftId"?,"caseDisplay"?,"applicantCode"?,"signerName"?,"entityType"?,"representative"?,"corporateRegNo"?,"at"?:{x,y,page?}} — 크레딧 없음, 201. 서명 칸은 양식의 "(인)" 자리(signPlacement) |
GET /delegations?status=&limit= | read | 위임장 목록(서명 링크·서명 이미지는 싣지 않음). limit 기본 20, 최대 100 |
GET /delegations/:id | read | 상태·서명자별 서명 시각·진행 기록 |
GET /delegations/:id/pdf | read | PDF(서명 완료면 서명된 본) |
POST /delegations/:id/send | write | 서명 링크 발송 {"memo"?} — 초안만, 한 번 |
POST /delegations/:id/cancel | write | 서명 요청 취소 {"reason"?} |
검색
검색은 모두 크레딧이 들지 않습니다(이미지 디자인 검색 제외).
| 메서드·경로 | 권한 | 설명 |
|---|
GET /search/patents?q=&ipc=&utility=1&limit=&page= | read | KIPRIS 특허 검색 {query,totalCount,page,limit,results[]}(limit 1~30, 기본 10). 검색식은 공백 AND, | OR, ^ 제외 |
GET /search/patents/:number?part=&offset=&maxChars=&doc=&as= | read | 공보 본문(한국 kipris·해외 google-patents), nextOffset 으로 이어 읽기. part 는 claims·description·all(기본), maxChars 1000~60000(기본 20000), doc 은 open·register, as 는 번호 종류(publication·announcement·registration·application) |
GET /search/trademarks?q=&class=&similar=1&limit= | read | 상표 검색(mode kipris·similar). class 는 9,35 처럼 |
GET /search/trademarks/:applicationNumber/goods | read | 지정상품·유사군코드 |
GET /search/goods?q=&code=&class=&limit= | read | NICE 고시 지정상품 명칭 |
GET /search/designs?q=&keyword=&scope=&class=&shape=&limit=&page= | read | 디자인 공보 검색(메타데이터) |
POST /search/designs | write | 이미지 디자인 유사 검토(multipart: image·articleName·description …, 이미지 10MB 이하), ?dryRun=1 예상 크레딧. 5 크레딧 |
선행조사·보고서
| 메서드·경로 | 권한 | 설명 |
|---|
POST /prior-art | write | AI 선행조사 {description?,draftId?,title?,field?,problem?,solution?,background?,effects?,patentNumbers?,instruction?,outputLanguage?,cutoffDate?,excludeNumbers?} → 202 {taskId,status,title,draftId}(5 크레딧, 10~20분). ?dryRun=1. 결과는 GET /tasks/:taskId(요약, ?full=1 전체). 작업 id 가 곧 조사 기록 id |
GET /prior-art?draftId=&offset= | read | 선행조사 기록 목록 {records:[{id,title,clientName,draftId,resultsCount,createdAt}],nextOffset} |
POST /trademark-reports | write | 상표 검색 보고서 {searchTerm,businessField,classification?,classificationLimit?,manualKeywords?,searchScope?,foreignCountries?} → 202 {taskId,status,searchTerm}(8 크레딧, 1~3분). searchScope 는 domestic(기본)·both·foreign. ?dryRun=1 |
GET /reports/:id?format=&audience= | read | 상표·선행조사 보고서. format 은 json(기본, 요약)·md·docx·pdf, audience=client 는 고객용 요약(docx·pdf) |
GET /competitors | read | 경쟁기업 조사 보고서 목록과 입력 후보 {reports,sources} |
POST /competitors | write | 경쟁기업 조사 보고서 {historyId}(선행조사 기록 id) → 201 {id}. 1~3분 걸리는 동기 응답, AI 서술이 나오면 5 크레딧. ?dryRun=1 |
GET /competitors/:id?format=json|md|docx | read | 보고서 한 건 |
우선심사
| 메서드·경로 | 권한 | 설명 |
|---|
GET /priority-exams/reasons | read | 사유 코드표 {patent[],trademark[]}(각 {code,label,statute,requiredEvidence}) |
GET /priority-exams?kind=patent|trademark | read | 우선심사 건 목록 {priorityExams[]} |
POST /priority-exams | write | 새 건 만들기(크레딧 없음) {kind, 서지…, reasons[], reasonDescription?, additionalNotes?, draftId?, files?[{name,mimeType,data,role:source|evidence}], extractBiblio?} → 201 |
GET /priority-exams/:id | read | 서지·사유·첨부·설명서 본문·진행 중인 작업 |
POST /priority-exams/:id/generate | write | 설명서 생성 {feedback?}(10 크레딧) → 202 {taskId,status}. ?dryRun=1 |
GET /priority-exams/:id/export?format=docx|pdf | read | 설명서 파일(증거 이미지 포함, 상표는 docx) |
분할출원 청구항
| 메서드·경로 | 권한 | 설명 |
|---|
POST /drafts/:id/divisional/candidates | write | 분할 주제 후보 {count?(1~8)} → {originalCoverage, items:[{no,title,summary,kind,whyNotClaimed,basis:[{paragraph,quote,status,foundIn}],supported}], creditsUsed}. status 는 원출원 본문과 글자 대조 결과(verified·relocated·not-found·too-short). 5 크레딧(만든 뒤). 분할 명세서가 아니면 409. ?dryRun=1 |
POST /drafts/:id/divisional/apply | write | 고른 주제로 한번에 생성 준비 {candidate? , requirements?} → {title, claimsRequirements, reusedPriorArt, next}. 주제를 청구항 설계 요구사항에 넣고 복사된 청구항·본문을 비우며 원출원 선행조사를 재사용한다. 크레딧 없음. 생성 중이면 409. 이어서 POST /drafts/:id/generate {"resume":true} |
GET /drafts/:id/divisional | read | 원출원·후보·고른 주제·check(마지막 분할 검사: claims[{claimId,type,unsupported[],duplication{risk,claimId,reason}}], blocking, excludedClaims, discardedAvoidance) |
분할 검사는 한번에 생성의 청구항 설계·회피 설계·자동 마무리 뒤에 돌아갑니다. 독립항에 원출원 근거가 없는 구성이 있거나 원출원 청구항과 같거나 넓으면(blocking) 생성이 확인 질문에서 멈추고(awaitingMaterialCheck), 회피 설계가 원출원에 없는 구성을 끌어들이면 그 수정을 버립니다. 남의 분할 명세서·남의 원출원은 404 입니다.
거절결정 대응
GET /drafts/:id/oa 의 noticeStage 는 분석이 통지서 원문 표지로 읽은 절차 단계입니다(분석 전이거나 표지를 못 읽으면 null).
{
"stage": "rejection-decision",
"label": "거절결정",
"evidence": ["… 거절이유를 해소하지 못하였으므로 특허법 제62조에 따라 거절결정합니다"],
"appealPeriod": "3개월",
"maintainedNoticeDate": "2026.03.02",
"amendmentDismissed": false,
"restrictedAmendment": true,
"procedure": "reexamination",
"analyzedProcedure": "reexamination",
"needsReanalysis": false,
"options": [
{"id": "reexamination", "label": "재심사 청구", "available": true, "summary": "…", "notes": ["…"]},
{"id": "appeal", "label": "거절결정불복심판 청구", "available": true, "summary": "…", "notes": ["…"]},
{"id": "divisional", "label": "분할출원", "available": true, "summary": "…", "notes": ["…"]}
]
}
stage: first-notice(최초 통지)·final-notice(최후 통지)·rejection-decision(거절결정)·reexam-rejection-decision(재심사 후 거절결정 — 재심사 불가).
restrictedAmendment: 청구범위 보정이 특허법 제47조 제3항(감축·오기 정정·명확화)으로 제한되는 단계인지. 최후 통지와 재심사를 고른 거절결정이 해당합니다.
procedure 는 지금 고른 절차, analyzedProcedure 는 분석이 전제한 절차입니다. 다르면 needsReanalysis: true — POST …/oa/analyze {"procedure": …} 로 다시 분석해야 의견서를 만들 수 있습니다.
options 는 거절결정 단계에서만 채워집니다. notes 에 기간(결정서 기재)·수수료·주의가 있습니다. 기한 날짜는 송달일 기준이라 계산해 주지 않습니다. divisional 은 안내뿐이고 procedure 로 고를 수 없습니다.
- 심판(
appeal)을 고르면 보정안을 만들지 않습니다.
분석 전 입력 관문과 대응 계획
특허 OA(의견제출통지·거절결정 대응)는 분석·생성이 멈추지 않습니다. 부족한 입력은 다른 수단으로 실제로 읽어 채우고, 그래도 없는 것은 지어내지 않고 표시합니다.
| 메서드·경로 | 권한 | 설명 |
|---|
GET /drafts/:id/oa/notice | read | 입력 확인 {applies, noticeKind, intake, citedInputs}. intake 는 통지서 본문이 충분한지(스캔 쪽·판독 여부, 읽은 단계·거절이유 유형), citedInputs 는 통지서의 인용발명 번호 ↔ 공보번호 ↔ 올린 인용문헌 파일의 대응 |
POST /drafts/:id/oa/notice | write | 선택 — 사람이 통지서 본문을 확인하거나 넣는다 {action, file?, text?}. read 스캔 쪽 판독(웹 「자료 로드 확인」과 같다, 한 번에 40쪽), confirm 판독 글자 확인, text 본문 직접 입력. 크레딧 없음 |
POST /drafts/:id/oa/alternative | write | 조건 충돌로 함께 만든 두 대안 가운데 하나를 본문으로 {choice: relax|argue} → {selected, tally}. 크레딧 없음 |
POST /oa 는 noticeKind(first-notice·final-notice·rejection-decision·reexam-rejection-decision)와 noticeText(사람이 옮긴 통지서 본문)를 받습니다. noticeKind 는 본문에서 읽은 단계보다 우선하고, 다르면 GET …/oa 의 noticeStageWarning 에 남습니다.
POST …/oa/analyze 는 시작 전에 inputWarnings 로 미리 알릴 뿐 막지 않습니다. 통지서 글자 층이 부실하면 분석이 스캔 쪽을 AI로 판독해 진행합니다. 결과의 noticeRead 에는 「AI 판독본 사용」, 품질이 낮을 수 있는 쪽, 판독 실패가 남고, 판독까지 실패한 부분은 「원문 판독 실패」로 표시합니다. 통지서의 인용문헌 본문이 빠졌으면 올린 파일 판독·KIPRIS·해외 원문으로 확보를 시도합니다(citedAcquire). 그래도 없는 문헌은 「본문 미확보 — 통지서의 심사관 인용 부분만 근거」로 다룹니다. 판독·수집 비용은 분석 과금 안입니다.
POST …/oa/opinion 은 거절이유마다 해법·해소 근거·명세서 근거 단락을 정하고(responsePlan), 초안 뒤 이유별로 판정합니다(resolutionCheck). 미해소면 계획을 고쳐 다시 쓰고(기본 2번), 그래도 남으면 resolutionCheck.notes 에 사유·시도한 해법·다음 조치를 남기고 완성본을 냅니다. 사용자 조건(feedback·보호 청구항·넣지 않을 한정)과 충돌하는 거절이유가 있으면 조건 완화안·조건 유지안을 모두 만들어 검증합니다. 결과는 alternatives(판정 요약 tally 포함)이고, 본문은 판정이 나은 추천안입니다. conflictChoice(relax·argue)를 주면 그 안만 만듭니다. 이 모든 호출이 같은 30 크레딧입니다.
심사 예측
| 메서드·경로 | 권한 | 설명 |
|---|
POST /exam-predict | write | 청구범위와 선행문헌으로 가상 의견제출통지서 {claimsText, refs, inventionSummary?, specificationText?} → {notice, allowableClaims[], usedRefs[], failedRefs[], groundingWarnings[], withoutSpecification, creditsUsed, disclaimer}. refs 는 문헌번호 문자열 또는 {id, summary?} 의 배열(15건, 요지를 주면 공보를 불러오지 않음), 또는 번호 | 요지 줄로 된 문자열. 13분 걸리는 동기 응답, 15 크레딧(통지서가 만들어진 뒤). 저장하지 않는다. 문헌을 하나도 못 불러오면 422 {failedRefs}. ?dryRun=1 |
결과는 예측이며 실제 심사 결과를 보장하지 않습니다. groundingWarnings 는 통지서가 든 청구항 번호·인용 문구가 문헌 원문과 다른 곳입니다.
IP 조사(FTO)·특허 평가
| 메서드·경로 | 권한 | 설명 |
|---|
POST /fto | write | FTO(침해 가능성) 예비 검토 시작 {productDescription(30자~), jurisdictions:["KR","US","EP","JP","CN"], markets?(EP 면 필수), outputLanguage?, publications?[], suppliedClaims?[{publicationNumber,claims}]} → 202 {researchId,taskId,status}. 15 크레딧(보고서 저장 때, 근거를 못 찾거나 실패하면 차감 없음). {translationSourceResearchId, outputLanguage} 는 완료된 보고서의 번역(크레딧 없음), {researchId} 는 실패한 조사 다시. ?dryRun=1 |
GET /fto?limit= | read | FTO 조사 목록 {researches[]} |
GET /fto/:id | read | 조사 하나 — {status, input, task, result:{counts, patents[{publicationNumber,reviewPriority,rows}], search}, disclaimer}. ?full=1 이면 대비표 행·청구항 발췌까지 |
GET /fto/:id/export?format=docx|md&audience=client | read | 보고서 파일. audience=client 는 고객용 요약(docx) |
POST /valuations | write | 특허 평가 {number(한국 특허 출원·공개·등록번호), product?, revenueModel?, priorArtHistoryId?} → 201 {id, grade, overall, axes, aiDetails, warnings, creditsUsed}. 1~수 분 걸리는 동기 응답, AI 판정이 나온 경우에만 5 크레딧. 실용신안·해외·공개 전 출원은 422. ?dryRun=1 |
GET /valuations / GET /valuations/:id | read | 평가 목록 / 하나(?full=1 이면 지표 근거·청구항 발췌·재무 입력까지) |
POST /valuations/:id/sheets | write | 재무 채점표(기술강도·위험 프리미엄) AI 초안 {business?} → {id, draftSheets, creditsUsed}(5 크레딧). 값 확정·가치 계산은 웹에서. ?dryRun=1 |
GET /valuations/:id/export?audience=client | read | 평가 보고서 DOCX |
FTO 결과는 침해·비침해 결론이 아닌 예비 검토입니다. 진행은 GET /tasks/:taskId(결과는 {researchId} 뿐), 보고서는 GET /fto/:id 에서 읽습니다.
번역
| 메서드·경로 | 권한 | 설명 |
|---|
POST /translations | write | 내 명세서를 원문으로 번역 건을 만들고 작업 시작 {draftId, kind:"claims"|"full", targetLang?(ko·en·ja·zh), jurisdiction?(US·WO·EP·JP·CN), sourceLang?, styleGuide?} → 202 {id,taskId,status}. 청구항 10·전문 20 크레딧 — 작업이 번역을 시작할 때 차감, 실패해도 돌려주지 않는다. 청구항이 있는 원문에서 청구항 번역 없이 full 은 409. ?dryRun=1 |
POST /translations/:id/run | write | 그 번역 건에서 작업 시작 {kind} → 202 {id,taskId,status}(보통 청구항 번역 뒤 full). ?dryRun=1 |
GET /translations?limit= | read | 번역 건 목록 {translations[]} |
GET /translations/:id | read | 상태와 섹션별 글자 수 {status, sections:[{key,sourceChars,translatedChars,preview}]}. ?sections=claims,abstract 또는 ?full=1 이면 translated 에 번역문 |
전문 번역은 청구항을 다시 옮기지 않고 번역된 청구항의 용어를 기준으로 나머지 섹션을 옮깁니다. 일부 섹션이 실패해도 작업은 completed 이고 그 섹션에 [번역 실패 — 재시도해주세요] 가 들어갑니다. 같은 번역 건에 run 을 두 번 보내면 두 번 차감되므로 Idempotency-Key 를 붙이세요.
기한
| 메서드·경로 | 권한 | 설명 |
|---|
GET /docket?severity=&appNumber=&limit= | read | 열린 기한(마감 빠른 순) {connected, lastSync, counts:{overdue,today,soon,normal,unknown}, total, deadlines:[{id,dueDate,severity,category,title,applicationNumber,caseTitle,applicantName}]}. 웹 「기한 관리」의 특허로 동기화 결과를 읽는다. 연동이 없으면 connected:false. 읽기 전용 — 동기화·연동 설정은 웹에서 |
GET /overseas/deadlines?priorityDate=YYYY-MM-DD&type=patent|design|trademark | read | 우선일로 해외 출원 기한 계산 {deadlines:[{key,label,date,basis,source,note?}], note} — 파리조약 우선권(특허 12개월·디자인·상표 6개월), PCT 국내단계 진입(KR·US·JP·CN·EP). 휴일 순연은 반영하지 않는다 |
작업
| 메서드·경로 | 권한 | 설명 |
|---|
GET /tasks/:taskId | read | 작업 상태 {id,type,projectId,status,progress,error,createdAt,updatedAt}, 끝났으면 result. 선행조사·상표 결과는 요약, ?full=1 이면 전체 |
크레딧을 쓰는 요청에 ?dryRun=1 을 붙이면 실행하지 않고 예상 크레딧과 잔액만 돌려줍니다.
도면 재생성 본문
{
"instruction": "부호 220 과 230 을 바꿔 표기",
"referenceImageBase64": "data:image/png;base64,....",
"referenceRole": "3d",
"mode": "existing",
"saveAs": "candidate"
}
referenceRole 은 3d·dimension·sketch 중 하나이고 참조 이미지와 함께 보냅니다.
mode 는 new·existing·sketch. 생략하면 참조가 있으면 sketch, 현재 도면이 있으면 existing.
saveAs 는 candidate(이력 후보, 기본) 또는 apply(바로 교체, 이전 도면은 이력). 응답의 applied 로 실제 교체 여부를 확인합니다.
수정 분석 본문
{ "instruction": "청구항 1항의 '고정부'를 '체결부'로 통일" }
응답의 taskId 로 GET /tasks/:taskId 를 불러 끝날 때까지 기다립니다. 결과는 수정 제안(result.revision)입니다.
수정 제안 반영
{ "sections": ["detailedDescription", "claims"] }
POST /drafts/:id/revise/:taskId/apply. sections 를 생략하면 제안 전체를 반영합니다. 청구범위는 claims 입니다.
- 제안에 없는 항목을 고르면
400 과 함께 고를 수 있는 항목을 알려 줍니다. 같은 제안을 다시 반영하면 409.
- 반영 전 값은 명세서의 수정 이력에 남아 웹 최종 검토 화면에서 되돌릴 수 있습니다.
- 웹에서 같은 명세서를 열어 둔 상태라면 반영 뒤 새로고침하세요. 열린 화면이 자동 저장하면 반영 내용을 덮을 수 있습니다.
예시
curl -H "Authorization: Bearer $INVENTIPS_TOKEN" https://inventips.net/api/v1/drafts?limit=5
curl -X POST -H "Authorization: Bearer $INVENTIPS_TOKEN" -H "Content-Type: application/json" \
-d '{"format":"docx"}' -o draft.docx https://inventips.net/api/v1/drafts/<id>/export
크레딧 작업 시작하고 기다리기
선행조사를 예로 듭니다. 예상 크레딧을 먼저 보고, Idempotency-Key 를 붙여 시작한 뒤, 작업이 끝날 때까지 확인합니다.
BASE=https://inventips.net/api/v1
AUTH="Authorization: Bearer $INVENTIPS_TOKEN"
# 1) 예상 크레딧(실행 안 함)
curl -s -X POST "$BASE/prior-art?dryRun=1" -H "$AUTH" -H "Content-Type: application/json" \
-d '{"description":"드론 배터리를 착륙 패드에서 자동으로 교체하는 장치"}'
# → {"dryRun":true,"action":"prior-art","estimatedCredits":5,"balance":120,"note":"..."}
# 2) 시작 — 같은 키로 다시 보내도 한 번만 실행된다
curl -s -X POST "$BASE/prior-art" -H "$AUTH" -H "Content-Type: application/json" \
-H "Idempotency-Key: prior-art-2026-11-12-001" \
-d '{"description":"드론 배터리를 착륙 패드에서 자동으로 교체하는 장치"}'
# → 202 {"taskId":"<taskId>","status":"pending","title":"...","draftId":null}
# 3) 상태 확인
curl -s "$BASE/tasks/<taskId>" -H "$AUTH"
import os
import time
import uuid
import requests
BASE = "https://inventips.net/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['INVENTIPS_TOKEN']}"
body = {"description": "드론 배터리를 착륙 패드에서 자동으로 교체하는 장치"}
est = S.post(f"{BASE}/prior-art", params={"dryRun": 1}, json=body, timeout=60).json()
print("예상 크레딧", est["estimatedCredits"], "잔액", est["balance"])
r = S.post(f"{BASE}/prior-art", json=body, timeout=60,
headers={"Idempotency-Key": f"prior-art-{uuid.uuid4()}"})
if r.status_code == 402:
raise SystemExit(r.json()["error"])
r.raise_for_status()
task_id = r.json()["taskId"]
while True:
t = S.get(f"{BASE}/tasks/{task_id}", timeout=30)
if t.status_code == 429:
time.sleep(int(t.headers.get("Retry-After", "60")))
continue
t.raise_for_status()
task = t.json()
if task["status"] in ("completed", "failed"):
break
time.sleep(30)
print(task["status"], task.get("error"))
// Node.js 18+ — prior-art.mjs
import { randomUUID } from 'node:crypto';
const BASE = 'https://inventips.net/api/v1';
const headers = {
Authorization: `Bearer ${process.env.INVENTIPS_TOKEN}`,
'Content-Type': 'application/json',
};
const body = JSON.stringify({ description: '드론 배터리를 착륙 패드에서 자동으로 교체하는 장치' });
async function call(path, init = {}) {
const res = await fetch(`${BASE}${path}`, { ...init, headers: { ...headers, ...init.headers } });
const data = await res.json();
if (!res.ok) throw Object.assign(new Error(data.error), { status: res.status, data });
return data;
}
const est = await call('/prior-art?dryRun=1', { method: 'POST', body });
console.log('예상 크레딧', est.estimatedCredits, '잔액', est.balance);
const { taskId } = await call('/prior-art', {
method: 'POST',
body,
headers: { 'Idempotency-Key': `prior-art-${randomUUID()}` },
});
let task;
do {
await new Promise((r) => setTimeout(r, 30_000));
task = await call(`/tasks/${taskId}`);
} while (task.status !== 'completed' && task.status !== 'failed');
console.log(task.status, task.error);
파일 내려받기
import base64, json, os, requests
BASE = "https://inventips.net/api/v1"
H = {"Authorization": f"Bearer {os.environ['INVENTIPS_TOKEN']}"}
draft_id = "<id>"
r = requests.post(f"{BASE}/drafts/{draft_id}/export", headers=H, json={"format": "hlz"}, timeout=180)
r.raise_for_status()
open("draft.hlz", "wb").write(r.content)
check = r.headers.get("X-Hlz-Check")
if check:
summary = json.loads(base64.urlsafe_b64decode(check + "=" * (-len(check) % 4)))
print("점검", summary["ok"], summary["codes"])
// Node.js 18+ — export.mjs
import { writeFile } from 'node:fs/promises';
const res = await fetch(`https://inventips.net/api/v1/drafts/${process.argv[2]}/export`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.INVENTIPS_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ format: 'docx' }),
});
if (!res.ok) throw new Error((await res.json()).error);
await writeFile('draft.docx', Buffer.from(await res.arrayBuffer()));
작업 완료 알림
PUT /me/notify 로 토큰에 https 주소를 등록하면, 그 토큰으로 시작한 작업이 끝나거나·실패하거나·확인 질문에서 멈출 때 서버가 그 주소로 POST 합니다. 주소는 외부에서 닿는 https 만 받습니다(내부망·localhost 불가).
{
"event": "task.completed",
"taskId": "<taskId>",
"type": "prior-art-search",
"projectId": null,
"status": "completed",
"at": "2026-11-12T03:21:00.000Z"
}
event 는 task.completed·task.failed·task.awaiting_input(한번에 생성이 확인 질문에서 멈춤)·test 입니다. 실패면 error 가 붙습니다.
- 헤더
X-Inventips-Event 에 이벤트, X-Inventips-Signature 에 sha256=<HMAC-SHA256(secret, 본문) hex> 가 실립니다.
- 한 번, 5초 안에 보냅니다. 받지 못해도 작업에는 영향이 없으니 결과는
GET /tasks/:taskId 로 확인하세요.
서명은 받은 본문 그대로(파싱 전 바이트)로 확인합니다.
import hashlib, hmac
def verify(secret: str, raw_body: bytes, signature: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret, rawBody, signature = '') {
const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
위임장 발송 방법.
deliveryChannel은 email(기본), sms, alimtalk 중 하나입니다. 이메일 발송은 signerEmail이 필요하고, 문자·알림톡은 국내 휴대전화번호 signerPhone이 필요합니다. 문자·알림톡 선택 시 이메일은 선택이며, 입력한 경우 완료본·감사추적인증서·취소 안내를 받습니다. 발송 응답의 sentCount는 실제 수신 완료가 아닌 발송 접수 수입니다. 실패·불확실한 접수가 있으면 failedCount·unknownCount도 반환합니다. 알림톡 미도달은 문자로 대체되며, 접수 여부가 불확실한 건은 자동 재발송하지 않습니다.
문제 해결
| 증상 | 원인과 해결 |
|---|
401 Authorization: Bearer <토큰> 헤더가 필요합니다. | 헤더가 없거나 토큰 형식이 틀렸습니다. Bearer 뒤 한 칸, 따옴표·줄바꿈 없이 itp_… 전체를 넣으세요. |
401 토큰이 유효하지 않습니다(만료·폐기 포함). | 만료·폐기됐거나 계정 승인이 취소됐습니다. 마이페이지에서 새로 발급합니다. |
403 커넥터 토큰은 MCP 도구에서만… | 커넥터가 만든 MCP · ... 토큰입니다. CLI 토큰을 따로 발급하세요. |
403 이 토큰에는 'write' 권한이 없습니다. | 읽기 전용 토큰입니다. 읽기+쓰기 토큰을 발급합니다. |
내 문서인데 404 | 다른 계정의 토큰이거나 id 를 잘못 넣었습니다. GET /me 의 userId 와 GET /drafts?all=1 로 확인하세요. OA·우선심사 문서는 all=1 에서만 보입니다. |
402 | 크레딧이 부족합니다. ?dryRun=1 로 필요한 양을 보고 충전합니다. |
409 수정 분석이 막힘 | 확정 대기가 걸려 있습니다(GET /drafts/:id 의 clientHold). DELETE /drafts/:id/hold 로 풉니다. |
409 작업이 진행 중 | 같은 문서에서 작업이 도는 중입니다. GET /drafts/:id/status 또는 GET /tasks/:taskId 로 끝난 뒤 다시 보냅니다. |
429 | Retry-After 초만큼 기다립니다. 폴링은 30초~몇 분 간격이면 충분하고, 알림 주소를 쓰면 폴링이 필요 없습니다. |
한번에 생성이 completed 인데 본문이 없음 | result.awaitingMaterialCheck 로 멈춘 것입니다. pendingQuestions 에 답해 answers 로, 그대로면 proceed:true 로 다시 부릅니다. |
| 네트워크 오류로 응답을 못 받음 | 같은 Idempotency-Key 로 다시 보내면 첫 결과를 돌려받고 크레딧이 두 번 나가지 않습니다. |
413 | 첨부를 줄이거나, 사건함 파일은 files/upload-url 로 올립니다. |