인증 및 키

Bearer 토큰 하나. 모든 엔드포인트.

PaperOffice-API의 모든 제품 엔드포인트는 Authorization: Bearer 헤더를 요구합니다. OAuth 흐름이나 갱신은 필요 없습니다.

두 가지 토큰 유형, 명확한 권한, 문서화된 속도 제한.

헤더 하나 OAuth 흐름 없음 언제든지 취소 가능

cURL

1curl -X POST "https://api.paperoffice.ai/latest/job/add/workflow" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -F "file_1=@invoice.pdf" \4  -F "idp_collection=invoice" \5  -F "model=basic-pro-max"

1import requests23response = requests.post(4    "https://api.paperoffice.ai/latest/job/add/workflow",5    headers={"Authorization": "Bearer po_ut_YOUR_API_KEY"},6    files={"file_1": open("invoice.pdf", "rb")},7    data={"idp_collection": "invoice", "model": "basic-pro-max"},8)9print(response.json())

1const form = new FormData();2form.append("file_1", new Blob([await readFile("invoice.pdf")]), "invoice.pdf");3form.append("idp_collection", "invoice");4form.append("model", "basic-pro-max");56const response = await fetch("https://api.paperoffice.ai/latest/job/add/workflow", {7  method: "POST",8  headers: { Authorization: "Bearer po_ut_YOUR_API_KEY" },9  body: form,10});11console.log(await response.json());

첫 호출

헤더 설정, 파이프라인 선택, 제출

/latest/job/add/ 이후의 경로는 작업 이름입니다: 일반적으로 handler___command 형식(예: paperoffice_aiocr___generate)이며, 구조화된 IDP의 경우 전용 workflow 파이프라인이 사용됩니다.

헤더 하나
Authorization: Bearer po_ut_… — 제품 엔드포인트에는 이것만 필요합니다. poai_ 및 po_ut_는 Origin 헤더를 보내지 않습니다.
경로의 파이프라인
handler___command는 세 개의 밑줄을 사용하며, 워크플로우는 고유한 슬러그를 가진 예외입니다. 점 표기법은 API에 HTTP 400 JOB_CONFIG_INVALID로 응답합니다.
결과 또는 job_id
client_wait는 기본값이 true입니다: API은 연결을 유지하고 결과를 인라인으로 제공합니다. 시간 창이 충분하지 않으면 job_id와 poll_url이 포함된 HTTP 202가 반환되며, GET /latest/job/get/{job_id}를 통해 폴링할 수 있습니다.

API 카탈로그 보기 IDE용 llms-full.txt

idp_collection=invoice의 경우, basic-pro-max이 권장 모델입니다. 실제로 사용되는 모델은 응답 필드 'model'에 반환되며, 요청한 모델과 다를 수 있습니다.

토큰 유형

두 가지 토큰 유형, 명확히 분리됨

둘 다 서버에 필요합니다. 앱의 계정 → API에서 생성, 회전 및 무효화됩니다.

poai_ 서버 간

API 키

생성 계정의 권한 (관리자: 전체 계정)
브라우저 코드에 절대 제공하지 않음
Origin 헤더 불필요
MCP에서 차단됨
IP 주소로 제한 가능

API 키 관리

po_ut_ 사용자 기반

User Token

사용자의 권한을 보유합니다
브라우저 코드에 절대 제공하지 않음
Origin 헤더 불필요
MCP 허용됨

사용자 토큰 생성

브라우저에서 직접 호출할 경우 이 두 토큰이 아닌 publishable key po_pk_를 통해 실행됩니다. — 출처 기반, 예산 및 속도 제한 적용. Publishable Keys 보기

권한

User Token이(가) 수행할 수 있는 작업

User Token은 해당 영역에서 사용자의 권한과 정확히 동일한 권한을 가집니다. 생성 시 개별 영역에 대한 권한을 직접 부여할 수 없으며, 범위를 좁히기 위해서는 사용자 그룹의 권한을 가진 그룹 토큰(po_gt_)이 필요합니다.

문서 documents
업로드, 다운로드, 처리
Workspaces workspaces
폴더 및 구조 관리
AI 작업 ai_jobs
OCR, IDP, 추출
청구 billing
사용량 및 계정 잔액 조회
사용자 users
팀 구성원 관리
웹훅 webhooks
이벤트 수신
지식 베이스 knowledge_base
지식 데이터베이스 및 FAQ
에이전트 agents
IDP 에이전트 구성
워크플로우 workflows
자동화 생성
컴플라이언스 compliance
감사, GDPR, 아카이빙

속도 제한

API이 카운트하는 항목

청구는 토큰 단위로, Bearer 없이 IP 주소 단위로 계산됩니다. 다음 값은 모든 요금제에서 적용되는 문서화된 최소값입니다.

5: 초당 요청 수
30: 분당 요청 수
100: 시간당 요청 수
500: 일일 요청 수

잔여 값은 응답 헤더에 포함됩니다
각 응답의 RateLimit-* 및 X-RateLimit-* 헤더는 현재 기간 내에 남은 한도를 나타냅니다.
초과 시 HTTP 429
API은 RATE_LIMIT_EXCEEDED로 응답합니다. Retry-After 헤더의 시간 후 호출을 재시도하십시오.
고급 요금제는 값을 상향 조정합니다
유료 요금제는 이러한 최소 기준보다 높습니다. 각 요금제의 범위는 가격 페이지에서 확인할 수 있습니다.

요금제 및 범위 보기

보안

키를 보호하는 요소

운영 중 작동하는 여섯 가지 메커니즘 — 각각 검증 가능한 상태 코드 또는 앱 내 위치를 가집니다.

회전 및 취소
키는 앱에서 계정 → API 아래에 생성, 나열, 회전 및 취소됩니다. 취소된 토큰은 HTTP 401 TOKEN_NOT_FOUND를 반환합니다.
만료 및 유효성
만료된 토큰은 HTTP 401 및 BEARERTOKEN_EXPIRED으로 응답하며, 오류가 있는 토큰은 HTTP 401 및 INVALID_TOKEN으로 응답합니다. Publishable Keys는 생성일로부터 180일 동안 유효합니다.
토큰별 제한
Free 요금제에서는 토큰별로 속도 제한(Rate-Limits)이 적용됩니다. 유료 요금제에서는 계정이 기준입니다. Credits이 존재하는 한 해당 곳에는 속도 제한이 적용되지 않습니다.
브라우저에서의 출처 바인딩
Publishable Keys는 각 요청에서 Allowlist의 Origin을 요구하며, 그렇지 않으면 API이 403 ORIGIN_HEADER_REQUIRED 또는 DOMAIN_NOT_ALLOWED로 응답합니다.
사용 내역 추적
청구된 모든 응답에는 _billing 블록이 포함되며, 호출별 평가는 GET /latest/billing/usage-detail을 통해 수행됩니다.
강력한 차단
브라우저 키에 대한 계정 로그인, 키 관리, OAuth, 파트너 관리자, 결제 변경 및 비밀번호 크래킹은 차단됩니다. 제품 APIs(청구 읽기 및 웹훅 포함)는 허용됩니다. Workspace 삭제, 휴지통 비우기 및 법적 보존 해제 앱에서만 수행 가능(403 UI_ONLY_ENDPOINT).