사양 문서 위치
엔드포인트 사양은 API 카탈로그에서 실시간으로 생성됩니다. 기사에서 엔드포인트 목록을 복사하는 대신 다음 파일을 사용하십시오:
- AI 클라이언트용 컴팩트 인덱스:
https://api.paperoffice.ai/latest/docs/llms.txt - 전체 참조:
https://api.paperoffice.ai/latest/docs/llms-full.txt - OpenAPI 3.1:
https://api.paperoffice.ai/latest/docs/openapi.json - 에이전트 스킬:
https://api.paperoffice.ai/latest/docs/skill.md - Postman 컬렉션:
https://api.paperoffice.ai/latest/docs/postman
문서 라우트는 공개되어 있으며 토큰이 필요하지 않습니다. Postman URL을 Postman, VS Code 또는 Bruno에 가져온 후 문서 릴리스가 변경될 때마다 다시 다운로드하십시오. 프로덕션 기본 주소는 https://api.paperoffice.ai/latest이며, 개발 목적으로만 /dev를 사용하십시오.
AI 코딩 어시스턴트와 빠른 시작: llms-full.txt의 주소를 제공하고 필요한 함수(예: 이미지를 보내고 인식된 텍스트를 반환하는 함수)를 설명하십시오.
인증 및 토큰 유형
대부분의 제품 엔드포인트는 Authorization 헤더에 Bearer 토큰을 요구합니다. 토큰은 PaperOffice 앱의 계정 → API에서 생성합니다.
- 시스템 키 (po_sk_): 전체 API 접근 권한이 있는 서버 간 통합용입니다. 브라우저에서 절대 사용하지 마십시오.
- 사용자 토큰 (po_ut_): 단일 사용자의 범위를 가지며, 예를 들어 MCP에 사용됩니다. 권한은 사용자 및 라이선스를 따릅니다.
- 그룹 토큰 (po_gt_): 사용자 그룹의 권한과 작업 공간 화이트리스트를 상속받습니다.
- 공개 키 (po_pk_): 브라우저에서 사용해야 합니다. 모든 요청에는 키 소유자가 입력한 출처가 필요하며, 수명 예산은 소비량을 제한합니다. 삭제, 계정 관리, 키 관리 및 결제 변경은 차단됩니다. MCP에는 허용되지 않습니다.
토큰이 없으면 사양, 상태 확인 및 연결성 테스트와 같은 인프라 엔드포인트에만 접근할 수 있습니다. 토큰 없는 제품 요청은 HTTP 401 대신 HTTP 403과 코드 TIER_RESTRICTED로 응답합니다.
작업: 대기, 폴링 및 결과
처리는 작업으로 실행됩니다. 작업 경로는 handler___command 패턴을 사용하며(세 개의 밑줄 포함), 예를 들어 텍스트 인식을 위해 POST /job/add/paperoffice_aiocr___generate입니다. 점 표기법은 JOB_CONFIG_INVALID로 거부됩니다.
- 기본적으로 요청은 잠시 연결을 유지합니다. 작업이 시간 내에 완료되면 결과를 직접 받습니다. 그렇지 않으면 HTTP 202와 작업 ID, 폴링 주소가 반환되며 작업은 계속 실행됩니다.
- HTTP 202는 오류가 아닌 성공입니다. 상태가 완료될 때까지 5~10초마다
GET /job/get/{job_id}를 폴링하십시오. 결과는 job_result에 있습니다. - client_wait=false를 사용하면 즉시 작업 ID를 받고 처음부터 폴링합니다.
- 모든 응답은 JSON입니다. 클라이언트는 로컬화된 메시지 텍스트가 아닌 안정적인 코드 필드를 읽어야 합니다.
계정 → API → 작업 대기열에서 대기 중, 실행 중 및 완료된 API 작업을 확인할 수 있습니다. 전체 오류 코드 목록은 사양에 있으며, 일반적인 사례로는 누락되거나 잘못된 매개변수(400), 누락되거나 잘못된 토큰(401), Credits 부족(402), 금지된 작업(403) 및 너무 많은 요청(429, Retry-After 준수)이 있습니다.
시작 SLA: 작업 시작 시점
선택적 필드 processing_lane은 작업이 완료되는 시점이 아니라 큐에서 시작되는 시점을 제어합니다. client_wait는 연결이 결과를 기다릴지 여부를 제어하며, 두 필드는 독립적입니다.
processing_lane이 없으면 작업 공간의 기본값이 적용되며, 그렇지 않으면 최선의 노력을 다합니다. 모든 플랜에는 추가 요금 없이 최선의 노력이 포함됩니다. 더 빠른 시작 라인은 선택 사항이며 비용이 더 듭니다. 현재 라인과 가격은 API 가격 목록을 통해 실시간으로 확인 가능하며, 자세한 내용은 API 문서에 있습니다.
웹훅
웹훅 엔드포인트는 작업 및 계정 이벤트(예: job.completed, job.failed, job.progress 및 문서, 작업 공간, 작업 관련 이벤트)를 수신합니다. 지갑 잔액 소진이나 키 취소와 같은 계정 알림은 웹훅 이벤트가 아닙니다.
- 페이로드는 X-Paperoffice-Signature 헤더에서 HMAC-SHA256로 서명됩니다. 웹훅 시크릿을 사용하여 원본 요청 본문에 대해 서명을 계산하고, 일치하지 않으면 요청을 거부하십시오.
- 웹훅는 API를 통해 등록, 나열, 업데이트, 테스트 및 삭제됩니다.
청구 및 사용량
API 호출은 앱과 동일한 조직의 공유 풀에서 Credits를 소비합니다. 일부 상태 및 상태 확인 쿼리는 과금되지 않으며, 자세한 내용은 API 문서에 나와 있습니다. 유효하지 않은 입력으로 인해 거부된 호출도 과금되지만, 속도 제한으로 인해 거부된 호출은 과금되지 않습니다.
API 및 개발자 → API 사용량에서 Credits와 함께 호출 내역을 확인할 수 있습니다. 실시간 로그는 각 요청을 보여주며, 기록은 날짜, 핸들러 및 작업별 사용량을 보여줍니다. Credits가 소진되면 잔액을 충전하거나 자동 충전이 적용될 때까지 호출이 거부됩니다. 속도 제한은 플랜에 따라 다르며, 현재 제한 사항과 응답 헤더는 API 문서에 설명되어 있습니다. Credits에 대한 자세한 내용: PaperOffice AI의 청구 및 Credits.
MCP: AI 어시스턴트 연결
MCP는 Claude, ChatGPT, Grok 및 Cursor와 같은 AI 어시스턴트를 PaperOffice에 직접 연결합니다. 인증은 OAuth 2.1 또는 사용자/그룹 토큰이며, 시스템 키 및 공개 키는 MCP에서 차단됩니다. 프로덕션 호스트는 https://mcp.paperoffice.ai이며, /claude, /chatgpt, /grok, /cursor 및 /dms와 같은 프로필이 있습니다. 설정, 권한 및 데이터 흐름: Claude, ChatGPT, Grok 및 Cursor와 함께 PaperOffice 사용.
자주 묻는 질문
- 모든 엔드포인트는 어디에서 찾을 수 있나요? llms.txt, llms-full.txt 및 OpenAPI 파일에서 확인할 수 있습니다. 이들은 실시간으로 생성됩니다.
- 서버에서 어떤 토큰을 사용해야 하나요? 시스템 키를 사용하고, 브라우저에서는 절대 사용하지 마십시오. 브라우저의 경우 출처와 예산이 있는 공개 키를 사용하십시오.
- HTTP 202는 오류인가요? 아닙니다. 작업이 아직 실행 중이므로 결과를 폴링하십시오.
- 더 빠른 시작 레인은 더 비싼가요? 네. 최선의 노력(best effort)에는 추가 요금이 없으며, 현재 가격은 API 가격 목록에 나와 있습니다.
- 거부된 호출은 과금되나요? 유효하지 않은 입력으로 인해 거부된 호출은 과금되지만, 속도 제한으로 인해 거부된 호출은 과금되지 않습니다.