문서 목록

개발자·연동

REST API

/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서버 오류
502KIPRIS 등 외부 검색 실패
503백그라운드 작업을 시작하지 못함(잠시 뒤 다시)

엔드포인트

경로는 모두 /api/v1 아래입니다. 「권한」은 필요한 토큰 권한이고, 크레딧은 웹에서 같은 작업을 할 때와 같습니다.

계정·알림

메서드·경로권한설명
GET /meread토큰 주인·잔여 크레딧·토큰 권한 {userId,name,firmName,tier,credits,isBenchmark,token:{id,name,scopes,expiresAt,notifyUrl}}
GET /me/notifyread이 토큰의 알림 주소 {token,url}
PUT /me/notifywrite알림 주소 등록 {"url":"https://..."} → {token,url,secret,signature}. secret 은 이 응답에서만 보입니다
DELETE /me/notifywrite알림 끄기
POST /me/notify/testwrite시험 알림(event: test)을 보내고 받은 상태 코드 {ok,status}
GET /metrics?days=30read사건→출원 전환·기간, 단계 이동(사람·봇), 토큰별 쓰기 요청

명세서

메서드·경로권한설명
GET /drafts?limit=&all=1read명세서 목록 {drafts:[{id,title,step,docType,updatedAt}]}(limit 기본 50, 최대 200). all=1 이면 OA 등 다른 문서 포함
POST /draftswrite명세서 새로 만들기 {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/:idread요약 {id,title,step,updatedAt,clientHold,pendingQuestions,claims:{count,independent},sections,figures,validation,priorArt}. ?full=1 이면 본문 전체(content)
GET /drafts/:id/statusread최근 백그라운드 작업 {draftId,tasks:[{id,type,status,step,detail,percent,error,createdAt,updatedAt}]}(결과는 GET /tasks/:taskId)
POST /drafts/:id/generatewrite한번에 생성 {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/holdwrite확정 대기 {reason} — 걸려 있으면 revise 가 409
POST /drafts/:id/revisewrite수정 분석 작업 시작 {instruction}(1 크레딧~) → 202 {taskId, status}. 아래 「수정 분석 본문」
POST /drafts/:id/revise/:taskId/applywrite수정 제안 반영 {"sections":["backgroundArt","claims"]}(생략 시 전체) → {applied:true, …, note} — 크레딧 없음
POST /drafts/:id/confirm-requestswrite고객 출원 동의 링크 {"email"?,"note"?,"send"?} → 201 {id,version,url,expiresAt,sent,sentTo}
GET /drafts/:id/confirm-requestsread동의 요청·결과 {requests[]}(최신 먼저, effectiveStatus: pending·confirmed·cancelled·expired·changed)
POST /drafts/:id/exportread{"format":"docx"|"hlz"|"zip"} → 파일 바이트. hlz 응답에는 요약 헤더 X-Hlz-Check(JSON base64url {ok,errors,warnings,codes})
POST /drafts/:id/export/checkreadhlz 점검 보고서 {format,filename,size,ok,errors[],warnings[]}(각 {code,message,detail?}). 파일은 돌려주지 않음

도면

메서드·경로권한설명
GET /drafts/:id/figures/:figId/imageread현재 도면 내려받기 주소 {figureId,url,mimeType,description}(서명 URL 1시간)
GET /drafts/:id/figures/:figId/historyread도면 이력 {figureId,current,history:[{index,timestamp,label,hasImage,storagePath,previewUrl}]}(미리보기 URL 1시간)
POST /drafts/:id/figures/:figId/history/:index/applywrite이력 버전을 현재 도면으로 {figureId,appliedIndex,storagePath,historyCount}
PUT /drafts/:id/figures/:figId/imagewrite올린 이미지로 바로 교체 {"imageBase64":"...","mimeType":"image/png","label"?} — PNG·JPEG·WEBP 10MB 이하, 크레딧 없음, 이전 도면은 이력 0번
POST /drafts/:id/figureswrite도면 칸 추가 {"imageBase64","mimeType","position"?,"caption"?,"updateRefs"?} — 크레딧 없음, 201
DELETE /drafts/:id/figures/:figId?updateRefs=1write도면 칸 삭제, 뒤 번호를 당김
POST /drafts/:id/figures/reorderwrite순서 변경 {"order":[2,1,3],"updateRefs"?}
POST /drafts/:id/figures/:figId/regeneratewrite도면 한 장 재생성(10 크레딧) → 결과와 creditsCharged. 아래 「도면 재생성 본문」
POST /drafts/:id/figures/generatewrite도면 일괄 생성 {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=readOA 사건 목록 {cases[]}
POST /oawriteOA 사건 만들기(크레딧 없음) {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/oaread사건 상태 — 자료 수, 분석(거절이유·인용문헌·대응 전략), 의견서·보정서 본문, 진행 중인 작업. 끝난 작업 결과는 이 조회에서 반영된다(justApplied). noticeStage 는 통지서 원문에서 읽은 절차 단계 — 아래 「거절결정 대응」
POST /drafts/:id/oa/analyzewrite거절이유 분석·대응 전략 {feedback?, procedure?}(5 크레딧) → 202 {taskId,status}. procedure 는 거절결정 대응 절차 reexamination·appeal — 사건에 남기고 그 절차로 분석한다. 고를 수 없는 절차면 400. ?dryRun=1. 작업이 도는 중이면 409
POST /drafts/:id/oa/opinionwrite고른 전략으로 의견서·보정서(자진보정은 보정안) {strategy?(1부터),feedback?,procedure?}(30 크레딧) → 202 {taskId,strategy,status}. 분석 전이면 409. 거절결정 사건은 분석이 전제한 절차와 만들려는 절차가 다르면 409 {analyzedProcedure,procedure}. ?dryRun=1
PATCH /drafts/:id/oawrite고친 본문 저장 {opinionText?, amendmentText?, instructionLetter?, clientEmail?, rationale?} → {updated} — 웹 저장과 같고 버전을 남긴다. 작업이 도는 중이면 409
POST /drafts/:id/oa/emailwrite고객 안내 메일 초안 {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/filesreadOA 사건 원본 목록
GET /drafts/:id/oa/files/:fileIdread원본 파일 바이트(정리됐으면 410)
GET /drafts/:id/oa/summaryread통지서 서지·거절이유·인용문헌·분석 요약
POST /kipo/dtaread원본·고친 명세서 비교 보정서 {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 /matterswrite사건 만들기 {title, rightType?, caseState?, code?, folderPath?} → 201. rightType 은 patent·trademark·design·utility·pct·overseas
GET /matters/:idread사건 카드 {drafts,delegations,quotations,payments,docket,researches,searches,checklist[{key,label,done,detail}],nextStep,nextStepKey}
PATCH /matters/:idwrite사건카드 고치기 {code?,title?,folderPath?,folderRef?,rightType?,clientName?,clientEmail?,applicantCode?,memo?,teamId?}
POST /matters/:id/stagewrite사건 단계 변경 {to, note?} → {from,fromLabel,to,toLabel}. 한 칸씩만, 아니면 409
POST /matters/:id/filingwrite출원 접수 기록 {applicationNumber, filingDate?(YYYY-MM-DD), receiptNumber?, note?} → 201. 제출은 사람이 특허로에서
POST /matters/:id/works / DELETE /matters/:id/workswrite작업 잇기·떼기 {draftId} 또는 {searchId}
POST /matters/:id/assignees / DELETE /matters/:id/assigneeswrite사무소 사건 담당자 지정·해제 {userId} 또는 {email}(대표·관리자만)
GET /matters/:id/planread사건함·작업을 보고 다음 할 일 제안(크레딧 없음). 단계마다 key·action·쓸 파일·이유·크레딧 여부
POST /matters/:id/runwrite제안 단계 실행 {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/fileswrite파일 올리기 {files:[{name,mimeType,data(base64),kind?}]} → 201. 무슨 서류인지 자동 분류
POST /matters/:id/files/upload-urlwrite큰 파일(25MB 초과, 100MB 까지)용 서명 업로드 주소 {name} → signedUrl 로 PUT
POST /matters/:id/files/registerwrite서명 URL 로 올린 파일 등록 {path,name,mimeType,kind?,source?,sourceRef?} → 201. 같은 파일·같은 원본이면 duplicate: true
GET /matters/:id/files/:fileIdread내려받기 서명 URL(10분)
PATCH /matters/:id/files/:fileIdwrite분류 고치기 {kind}
POST /inbox/classifyread사건을 모르는 파일 분류 {files:[{name,mimeType,data}],fromEmail?,clientName?} → 서류 종류와 사건 후보(근거·점수). 저장·크레딧 없음

위임장

메서드·경로권한설명
POST /delegationswrite기본 양식으로 위임장 초안 {"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/:idread상태·서명자별 서명 시각·진행 기록
GET /delegations/:id/pdfreadPDF(서명 완료면 서명된 본)
POST /delegations/:id/sendwrite서명 링크 발송 {"memo"?} — 초안만, 한 번
POST /delegations/:id/cancelwrite서명 요청 취소 {"reason"?}

검색

검색은 모두 크레딧이 들지 않습니다(이미지 디자인 검색 제외).

메서드·경로권한설명
GET /search/patents?q=&ipc=&utility=1&limit=&page=readKIPRIS 특허 검색 {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/goodsread지정상품·유사군코드
GET /search/goods?q=&code=&class=&limit=readNICE 고시 지정상품 명칭
GET /search/designs?q=&keyword=&scope=&class=&shape=&limit=&page=read디자인 공보 검색(메타데이터)
POST /search/designswrite이미지 디자인 유사 검토(multipart: image·articleName·description …, 이미지 10MB 이하), ?dryRun=1 예상 크레딧. 5 크레딧

선행조사·보고서

메서드·경로권한설명
POST /prior-artwriteAI 선행조사 {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-reportswrite상표 검색 보고서 {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 /competitorsread경쟁기업 조사 보고서 목록과 입력 후보 {reports,sources}
POST /competitorswrite경쟁기업 조사 보고서 {historyId}(선행조사 기록 id) → 201 {id}. 1~3분 걸리는 동기 응답, AI 서술이 나오면 5 크레딧. ?dryRun=1
GET /competitors/:id?format=json|md|docxread보고서 한 건

우선심사

메서드·경로권한설명
GET /priority-exams/reasonsread사유 코드표 {patent[],trademark[]}(각 {code,label,statute,requiredEvidence})
GET /priority-exams?kind=patent|trademarkread우선심사 건 목록 {priorityExams[]}
POST /priority-examswrite새 건 만들기(크레딧 없음) {kind, 서지…, reasons[], reasonDescription?, additionalNotes?, draftId?, files?[{name,mimeType,data,role:source|evidence}], extractBiblio?} → 201
GET /priority-exams/:idread서지·사유·첨부·설명서 본문·진행 중인 작업
POST /priority-exams/:id/generatewrite설명서 생성 {feedback?}(10 크레딧) → 202 {taskId,status}. ?dryRun=1
GET /priority-exams/:id/export?format=docx|pdfread설명서 파일(증거 이미지 포함, 상표는 docx)

분할출원 청구항

메서드·경로권한설명
POST /drafts/:id/divisional/candidateswrite분할 주제 후보 {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/applywrite고른 주제로 한번에 생성 준비 {candidate? , requirements?} → {title, claimsRequirements, reusedPriorArt, next}. 주제를 청구항 설계 요구사항에 넣고 복사된 청구항·본문을 비우며 원출원 선행조사를 재사용한다. 크레딧 없음. 생성 중이면 409. 이어서 POST /drafts/:id/generate {"resume":true}
GET /drafts/:id/divisionalread원출원·후보·고른 주제·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/noticeread입력 확인 {applies, noticeKind, intake, citedInputs}. intake 는 통지서 본문이 충분한지(스캔 쪽·판독 여부, 읽은 단계·거절이유 유형), citedInputs 는 통지서의 인용발명 번호 ↔ 공보번호 ↔ 올린 인용문헌 파일의 대응
POST /drafts/:id/oa/noticewrite선택 — 사람이 통지서 본문을 확인하거나 넣는다 {action, file?, text?}. read 스캔 쪽 판독(웹 「자료 로드 확인」과 같다, 한 번에 40쪽), confirm 판독 글자 확인, text 본문 직접 입력. 크레딧 없음
POST /drafts/:id/oa/alternativewrite조건 충돌로 함께 만든 두 대안 가운데 하나를 본문으로 {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-predictwrite청구범위와 선행문헌으로 가상 의견제출통지서 {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 /ftowriteFTO(침해 가능성) 예비 검토 시작 {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=readFTO 조사 목록 {researches[]}
GET /fto/:idread조사 하나 — {status, input, task, result:{counts, patents[{publicationNumber,reviewPriority,rows}], search}, disclaimer}. ?full=1 이면 대비표 행·청구항 발췌까지
GET /fto/:id/export?format=docx|md&audience=clientread보고서 파일. audience=client 는 고객용 요약(docx)
POST /valuationswrite특허 평가 {number(한국 특허 출원·공개·등록번호), product?, revenueModel?, priorArtHistoryId?} → 201 {id, grade, overall, axes, aiDetails, warnings, creditsUsed}. 1~수 분 걸리는 동기 응답, AI 판정이 나온 경우에만 5 크레딧. 실용신안·해외·공개 전 출원은 422. ?dryRun=1
GET /valuations / GET /valuations/:idread평가 목록 / 하나(?full=1 이면 지표 근거·청구항 발췌·재무 입력까지)
POST /valuations/:id/sheetswrite재무 채점표(기술강도·위험 프리미엄) AI 초안 {business?} → {id, draftSheets, creditsUsed}(5 크레딧). 값 확정·가치 계산은 웹에서. ?dryRun=1
GET /valuations/:id/export?audience=clientread평가 보고서 DOCX

FTO 결과는 침해·비침해 결론이 아닌 예비 검토입니다. 진행은 GET /tasks/:taskId(결과는 {researchId} 뿐), 보고서는 GET /fto/:id 에서 읽습니다.

번역

메서드·경로권한설명
POST /translationswrite내 명세서를 원문으로 번역 건을 만들고 작업 시작 {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/runwrite그 번역 건에서 작업 시작 {kind} → 202 {id,taskId,status}(보통 청구항 번역 뒤 full). ?dryRun=1
GET /translations?limit=read번역 건 목록 {translations[]}
GET /translations/:idread상태와 섹션별 글자 수 {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|trademarkread우선일로 해외 출원 기한 계산 {deadlines:[{key,label,date,basis,source,note?}], note} — 파리조약 우선권(특허 12개월·디자인·상표 6개월), PCT 국내단계 진입(KR·US·JP·CN·EP). 휴일 순연은 반영하지 않는다

작업

메서드·경로권한설명
GET /tasks/:taskIdread작업 상태 {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 로 끝난 뒤 다시 보냅니다.
429Retry-After 초만큼 기다립니다. 폴링은 30초~몇 분 간격이면 충분하고, 알림 주소를 쓰면 폴링이 필요 없습니다.
한번에 생성이 completed 인데 본문이 없음result.awaitingMaterialCheck 로 멈춘 것입니다. pendingQuestions 에 답해 answers 로, 그대로면 proceed:true 로 다시 부릅니다.
네트워크 오류로 응답을 못 받음같은 Idempotency-Key 로 다시 보내면 첫 결과를 돌려받고 크레딧이 두 번 나가지 않습니다.
413첨부를 줄이거나, 사건함 파일은 files/upload-url 로 올립니다.