{"openapi":"3.1.0","info":{"title":"CLIP API","version":"2026-10-28","description":"## 시작하기\n\nCLIP HTTP API 는 무역서류 점검을(를) 고객 시스템에서 호출할 수 있도록 제공하는 API 입니다. 이 문서는 공통으로 적용되는 규칙과 기능별 호출 방법을 설명합니다.\n\n모든 주소는 `{{BASE_URL}}` 을 기준으로 합니다. 실제 연동 시에는 담당자가 안내한 서버 주소로 바꿔 사용하십시오.\n\n- 모든 요청은 고객 서버에서 호출해 주십시오. 브라우저나 모바일 앱에서 직접 호출할 수 없습니다(CORS 미지원).\n- 인증이 필요한 모든 요청에는 `x-clip-key` 헤더로 API 키를 보내야 합니다. 인증 세부 사항은 다음 섹션을 참고하십시오.\n- 파일을 보내는 요청은 multipart/form-data 를, 그 밖의 요청은 application/json 을 사용합니다.\n- 일부 기능은 작업을 만든 뒤 작업 ID 로 결과를 조회하는 방식입니다. 자세한 내용은 비동기 작업 섹션을 참고하십시오.\n\n연동을 시작할 때는 아래 순서로 서버 상태를 먼저 확인하는 것을 권장합니다. 상태 확인 경로는 인증 없이 호출할 수 있습니다.\n\n```curl\n# 1. 서버 동작 확인 (인증 불필요)\ncurl -s {{BASE_URL}}/api/health\n\n# 2. 키 상태와 잔여 한도 확인\ncurl -s {{BASE_URL}}/api/key-status -H \"x-clip-key: YOUR_API_KEY\"\n```\n\n첫 번째 요청은 `{\"status\":\"ok\"}` 응답이면 서버가 정상 동작하는 것입니다. 두 번째 요청에서 키가 유효하면 요금제, 사용 가능한 기능, 한도 정보가 응답으로 옵니다.\n\n## 인증\n\nAPI 키는 모든 인증 요청의 `x-clip-key` 헤더로 보냅니다. 키 값을 요청 본문이나 주소의 쿼리 문자열에 넣지 마십시오.\n\n```curl\ncurl -X POST {{BASE_URL}}/api/shipping/upload -H \"x-clip-key: YOUR_API_KEY\" -F \"file=@/path/to/document.pdf\"\n```\n\nAPI 키는 담당자에게 요청하여 발급받습니다. 키마다 사용할 수 있는 권한이 다르므로, 아래 표에서 연동할 기능에 필요한 권한을 확인하십시오.\n\n| 기능 | 필요한 권한 | 비고 |\n| --- | --- | --- |\n| 무역서류 파일 업로드·처리 | `files`, `ocr` | 업로드한 파일은 같은 키로만 처리할 수 있습니다 |\n| 무역서류 분류·추출 (`/api/shipping/classify`, `/api/shipping/extract`) | `ocr` | 문서 본문을 직접 보내는 방식입니다 |\n| 키 상태·잔여 한도 확인 | 키 활성·만료 상태 | `GET {{BASE_URL}}/api/key-status` |\n\n키에는 추가 기능(분류, 키 추출, 개인정보 탐지) 사용 여부가 설정되어 있을 수 있습니다. 설정이 꺼진 기능을 요청하면 403 이 옵니다.\n\n인증 실패는 다음과 같이 구분됩니다.\n\n- 키 헤더가 없거나 비어 있으면 401 이 오며, 본문의 `code` 값이 `api_key_required` 입니다. 배포 설정에 따라 키 헤더 없이도 요청이 처리될 수 있으나, 연동은 항상 키를 보내는 것을 전제로 하십시오.\n- 키가 잘못되었거나 비활성·만료되었거나 권한이 없으면 401 또는 403 이 옵니다. 기능 API 응답의 `error` 문자열로 세부 사유를 확인할 수 있습니다. 다만 키 상태 확인 API(`GET /api/key-status`)는 업스트림 사유를 감추고 `{\"error\":\"Upstream error 401\"}` 처럼 상태 코드만 돌려주므로 401 과 403 을 구분할 수 없습니다. 이 API 의 502 본문은 `Failed to fetch: ...` 형식입니다.\n- 분당 또는 일일 사용 한도를 넘으면 429 가 옵니다.\n\n```json\n{\"error\":\"우측 상단에 API Key 를 입력해 주세요.\",\"code\":\"api_key_required\"}\n```\n\n**API 키를 브라우저, 모바일 앱, 공개 저장소 등 클라이언트 쪽 코드에 넣지 마십시오.** 키가 노출되었다고 판단되면 즉시 담당자에게 폐기와 재발급을 요청하십시오.\n\n## 요청 형식\n\n파일을 보내는 API 는 multipart/form-data 형식을 사용하며 파일 필드 이름은 `file` 입니다.\n\n파일이 없는 POST 요청은 application/json 본문을 사용합니다. `Content-Type` 헤더를 `application/json` 으로 지정하고 JSON 본문을 보내십시오. 작업 조회는 GET 요청이며 본문이 없습니다.\n\n```curl\ncurl -X POST {{BASE_URL}}/api/shipping/upload -H \"x-clip-key: YOUR_API_KEY\" -F \"file=@/path/to/document.pdf\"\n```\n\n기능별로 받는 파일 형식이 다릅니다. 아래 목록은 권장 형식이며, 목록에 없는 형식을 보내면 처리가 실패하거나 결과 품질이 떨어질 수 있습니다.\n\n| 기능 | 지원 파일 형식 |\n| --- | --- |\n| 무역서류 점검 | PDF, PNG, JPG(JPEG), TIF(TIFF), WEBP |\n\n파일 크기와 페이지 수 상한은 계정 설정에 따릅니다. 상한을 넘는 파일은 413 으로 거절됩니다. 정확한 상한 값은 담당자에게 확인하십시오. 이미지 해상도는 기본적으로 자동 축소되어 처리됩니다. 파일 크기, 페이지 수, 픽셀 상한을 넘으면 413 으로 거절됩니다.\n\n파일 업로드 요청을 보낼 때는 `Content-Type` 을 직접 지정하지 마십시오. HTTP 클라이언트가 multipart 경계 값을 포함한 헤더를 자동으로 만들도록 두어야 합니다.\n\n## 비동기 작업(작업 ID 폴링)\n\n문서 처리는 시간이 오래 걸리므로 여러 기능이 같은 방식의 비동기 작업으로 동작합니다. 기본 흐름은 다음과 같습니다.\n\n1. 파일을 업로드 API 로 보내면 `fileId` 를 응답으로 받습니다. 업로드 응답의 HTTP 상태는 200 입니다.\n2. 처리 API 를 POST 로 호출하면 `{\"jobId\": \"...\"}` 형태의 응답을 받습니다. 이 값이 작업 ID 입니다.\n3. 같은 처리 API 주소에 `?job=작업ID` 를 붙여 GET 으로 호출합니다. 3초 간격으로 조회하십시오.\n4. 응답의 `status` 가 `pending` 이면 다시 조회하고, `done` 또는 `error` 이면 조회를 멈춥니다.\n\n처리 API 의 요청 본문과 페이지 단위 호출 방식은 기능별 문서를 따르십시오.\n\n| status 값 | 의미 | 처리 방법 |\n| --- | --- | --- |\n| `pending` | 처리 중입니다. | 3초 뒤에 다시 조회합니다. |\n| `done` | 처리가 끝났습니다. | 결과는 `result` 또는 `results` 필드에 있습니다. 필드 이름은 기능에 따라 다릅니다. |\n| `error` | 처리에 실패했습니다. | 본문의 `status` 는 항상 문자열 `\"error\"` 이고, `error` 필드에 사유가 옵니다. 실패 여부는 조회 응답의 HTTP 상태 코드로 판단하십시오. 처리·검토 API 는 처리 엔진의 상태 코드를 그대로 쓰며(알 수 없으면 502). |\n| `unknown` (HTTP 404) | 작업이 없거나 만료되었거나 서버 재시작으로 사라졌습니다. | 작업을 처음부터 다시 만들어야 합니다. |\n\n**`done` 과 `error` 응답은 한 번 읽으면 서버에서 삭제됩니다.** 응답을 받은 즉시 저장하십시오. 같은 작업을 다시 조회하면 404 `unknown` 이 옵니다. 응답이 유실되었다면 같은 작업을 재조회하지 말고 작업을 처음부터 다시 만들지 여부를 판단하십시오.\n\n**모니터링이나 상태 점검에 HEAD 요청을 사용하지 마십시오.** HEAD 요청도 같은 조회 처리로 들어가 결과를 소비하므로, 이후 GET 조회는 404 `unknown` 이 될 수 있습니다.\n\n- 작업 정보는 서버 메모리에만 있으며, 마지막 상태 변경 후 1시간이 지나면 만료됩니다.\n- 서버가 재시작되면 진행 중이던 작업은 모두 사라지며 조회 시 404 `unknown` 이 옵니다.\n- 여러 대의 서버를 앞단 로드밸런서로 묶은 환경에서는 작업을 만든 서버와 다른 서버로 조회될 수 있습니다. 이 경우에도 404 `unknown` 이 옵니다.\n\n작업 ID 는 결과를 조회하는 값이므로 외부에 노출하지 마십시오.\n\n작업 생성 요청(POST)이 200 을 돌려주었다고 해서 키가 유효하다는 뜻은 아닙니다. 키가 무효하거나 권한·한도가 부족하면 작업은 만들어지고, 실패 사유는 조회 단계에서 401, 403, 413, 429 등으로 나타납니다. 연동 전에 `GET {{BASE_URL}}/api/key-status` 로 키 상태를 먼저 확인하십시오.\n\n작업 생성 요청을 다시 보내면 새 작업이 만들어져 처리 횟수가 중복으로 소모됩니다. 재시도 규칙은 처리 시간·재시도 섹션을 따르십시오.\n\n## 오류 응답\n\n오류 응답의 본문 형식은 API 마다 다릅니다. 공통된 형식이 없으므로, 먼저 HTTP 상태 코드로 분류하고 본문에서 `code` 또는 `status` 값, 그리고 `error` 문자열을 확인하십시오. 거절한 상위 시스템의 세부 필드(부족한 권한 이름, 허용량 등)는 전달되지 않습니다.\n\n| 형식 | 본문 예 | 해당 API |\n| --- | --- | --- |\n| 키 누락 | `{\"error\":\"...\",\"code\":\"api_key_required\"}` | 인증이 필요한 모든 API |\n| 입력 오류 (400) | `{\"error\":\"...\"}` | 필드가 없거나 형식이 맞지 않을 때입니다. 메시지는 엔드포인트마다 다릅니다(각 엔드포인트의 오류 표 참고). |\n| 처리 오류 (상태 값 포함) | `{\"error\":\"...\",\"status\":502}` | 무역서류 분류·추출 |\n| 처리 오류 (상태 값 없음) | `{\"error\":\"...\"}` | 파일 업로드, 근거 페이지 이미지, 키 상태 확인 |\n| 작업 조회 실패 | `{\"status\":\"error\",\"error\":\"...\"}` | 비동기 작업 조회 |\n| 작업 없음 | `{\"status\":\"unknown\"}` | 비동기 작업 조회 (HTTP 404) |\n\n```json\n{\"error\":\"처리 중 오류가 발생했습니다.\",\"status\":502}\n```\n\n| 상태 코드 | 의미 | 대응 |\n| --- | --- | --- |\n| 400 | 입력 필드가 없거나 형식이 맞지 않습니다. | 필드 이름과 형식을 확인하십시오. 같은 요청을 재시도하지 마십시오. |\n| 401 | API 키가 없거나 잘못되었거나 비활성·만료되었습니다. | `code` 가 `api_key_required` 이면 키 헤더 누락입니다. 그 밖이면 키 값과 상태를 담당자에게 확인하십시오. 재시도하지 마십시오. |\n| 403 | 키 권한이 부족하거나 설정이 꺼진 기능을 요청했습니다. | 필요한 권한을 담당자에게 확인하십시오. 재시도하지 마십시오. |\n| 404 | 작업이 없거나(`unknown`) 파일을 찾을 수 없습니다. | 작업이 만료되었거나 재시작으로 사라졌는지 확인하십시오. 파일 ID 는 같은 키로 업로드한 것만 사용할 수 있습니다. |\n| 413 | 파일 크기, 페이지 수, 이미지 픽셀 상한 중 하나를 넘었습니다. | 파일을 줄이거나 나누어 보내십시오. 상한은 담당자에게 확인하십시오. 재시도하지 마십시오. |\n| 429 | 분당 또는 일일 사용 한도를 넘었습니다. | 60초 이상 기다린 뒤 재시도하십시오. 일일 한도는 날짜가 바뀌면 초기화되며, 기준은 한국 시간 오전 9시입니다. |\n| 5xx | 서버 또는 문서 처리 엔진의 일시적인 오류입니다. | 지수 백오프로 최대 2회 재시도하십시오. 이 경우 본문이 JSON 이 아닐 수 있습니다. |\n\n## 처리 시간·재시도\n\n문서 1건의 판정이나 추출은 보통 수 초에서 수 분이 걸립니다. 문서 길이와 페이지 수, 스캔 여부에 따라 차이가 큽니다. 클라이언트 타임아웃은 20분 이상으로 설정하는 것을 권장합니다.\n\n- 동시 요청은 문서 4~8건 이내로 제한하는 것을 권장합니다. 많이 보내면 한도에 빨리 도달하고 대기 시간이 길어집니다.\n- 요청 1건이 내부적으로 여러 번의 처리 호출로 나뉘므로, 사용량 한도는 보낸 요청 수보다 빠르게 소모될 수 있습니다.\n- 비동기 작업 조회는 3초 간격으로 하고, 전체 대기 시간에도 상한을 두어 상한을 넘으면 실패로 처리하십시오.\n\n| 상황 | 재시도 여부 | 대기 방법 |\n| --- | --- | --- |\n| 네트워크 오류 또는 5xx (조회 GET, 파일 업로드) | 최대 2회 | 지수 백오프 (예: 2초, 4초) |\n| 작업 생성 POST 의 네트워크 오류 | 응답을 받지 못한 경우에만 | 5xx 를 포함해 응답을 받았다면 재시도하지 마십시오. 재시도하면 작업이 중복 생성됩니다 |\n| 429 | 재시도합니다 | 60초 이상 기다린 뒤 재시도합니다. 응답에 Retry-After 헤더가 없으므로 고정 대기 시간을 사용하십시오 |\n| 그 밖의 4xx | 재시도하지 않습니다 | 요청 내용이나 키 권한을 고쳐야 합니다 |\n\n작업 생성 요청(POST)을 재시도하면 새 작업이 생겨 처리 비용이 중복될 수 있습니다. 응답을 받지 못한 경우에만 재시도하고, 이미 받은 작업 ID 는 다시 생성하지 마십시오.\n\n## 데이터 처리와 보관\n\n업로드한 원본 파일과 OCR 로 추출한 텍스트는 문서 처리 엔진으로 전송되어 처리됩니다. 연동 전에 전송 경로가 고객 정책에 맞는지 보안 담당 부서와 확인하십시오.\n\n- **기본 모드**에서는 업로드한 원본 파일이 문서 처리 엔진의 저장소에 남습니다. 파일은 API 키 단위로 격리되어 저장되며, 기간이 지나도 자동으로 삭제되지 않습니다.\n- 무역서류 점검은(는) 항상 원본을 저장합니다.\n- 저장된 원본을 삭제해야 하면 담당자에게 요청하십시오.\n\n응답 JSON 과 고객 서버의 로그에도 판정 대상 문서의 내용이 들어 있을 수 있습니다. 개인정보와 기밀 문서를 다룬다면 고객 측 보관 기간과 접근 권한 정책을 함께 적용하십시오.\n\n## 버전과 상태 확인\n\n이 문서는 2026-10-28 기준입니다. API 경로에는 버전 번호가 없으며(예: `/v1` 없음), 서버 버전을 응답에서 확인할 수 없습니다. 연동 테스트 전에 담당자에게 배포된 버전을 확인하십시오.\n\n- 응답에 새 필드가 추가될 수 있습니다. 모르는 필드는 무시하도록 파서를 작성하십시오.\n- 변경 사항은 담당자를 통해 확인하십시오.\n\n서버 동작 확인은 인증 없이 호출할 수 있습니다. 이 경로는 서버가 응답하는지만 확인하며, 문서 처리 엔진의 연결 상태나 API 키 상태는 확인하지 않습니다.\n\n```curl\ncurl -s {{BASE_URL}}/api/health\n```\n\n응답은 `{\"status\":\"ok\"}` 입니다. 키 상태와 잔여 한도는 `GET {{BASE_URL}}/api/key-status` 에 `x-clip-key` 헤더를 보내 확인하십시오."},"servers":[{"url":"https://clip-kbstar.floaterlab.com"}],"tags":[{"name":"무역서류 점검","description":"무역서류 점검 API 는 선적서류와 신용장 파일을 올려 서류 종류와 핵심정보, 근거 좌표를 얻는 API 입니다. 기본 흐름은 파일을 한 번 업로드하고, 쪽 단위로 분류와 추출 작업을 시작한 뒤 결과를 조회하는 비동기 방식입니다.\n\n**교차 검토와 UCP 600·ISBP 821 규정 검토의 판정(통과·하자·확인 필요)은 API 로 제공되지 않습니다.** 이 API 는 문서 분류, 핵심정보, 근거 위치까지 제공합니다."}],"paths":{"/api/shipping/upload":{"post":{"tags":["무역서류 점검"],"operationId":"upload","summary":"파일 업로드","description":"서류 파일을 서버에 올리고 이후 처리에 쓸 fileId 를 받습니다.\n\n파일은 한 번만 올리면 됩니다. 받은 `fileId` 로 쪽별 처리(`process`)를 여러 번 호출할 수 있습니다.\n\n처리 시간: 파일 크기에 따라 수 초에서 수 분이 걸릴 수 있습니다. 파일 전달 단계는 5분이 지나면 서버에서 중단되므로 그 안에 끝나는 크기여야 합니다. 클라이언트 타임아웃은 넉넉히(10분 이상) 잡으십시오.\n\n**업로드한 파일은 서버 파일 저장소에 보관됩니다.** 이 API 에는 파일 삭제 기능이 없으며, 이 API 는 파일을 저장하지 않는 옵션(저장 없는 모드)을 제공하지 않습니다.","parameters":[{"name":"x-clip-key","in":"header","required":true,"description":"API 키. 발급받은 키를 넣으십시오.","schema":{"type":"string","description":"API 키. 발급받은 키를 넣으십시오.","examples":["YOUR_API_KEY"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"서류 파일. PDF, PNG, JPG, TIFF, WEBP 를 권장합니다. 파일 크기 한도는 서버 설정에 따릅니다."}},"required":["file"]}}}},"responses":{"200":{"description":"저장소가 성공 응답을 했지만 fileId 를 주지 않았을 때. HTTP 상태는 200 이지만 fileId 가 없으므로 실패로 처리하십시오.","content":{"application/json":{"example":{"error":"upload 200"}}}},"400":{"description":"file 필드가 없거나 파일이 아닐 때","content":{"application/json":{"example":{"error":"file is required"}}}},"401":{"description":"x-clip-key 헤더가 없거나 비어 있을 때. 본문의 문구는 화면 안내용이므로, 판별에는 code 값(api_key_required)을 쓰십시오. / 처리 엔진이 키를 거부할 때. 상태 코드와 본문은 처리 엔진의 응답을 따릅니다.","content":{"application/json":{"example":{"error":"우측 상단에 API Key 를 입력해 주세요.","code":"api_key_required"}}}},"413":{"description":"파일 크기가 서버 설정의 한도를 넘을 때. 한도는 서버 설정에 따릅니다.","content":{"application/json":{"example":{"error":"Clip API error 413: File size exceeds limit"}}}},"500":{"description":"파일 저장소가 오류를 돌려줄 때(상태 코드는 저장소 응답을 그대로 따릅니다). 본문에는 저장소의 오류 메시지가 있으면 그대로 들어가고, 없으면 이 형태가 나옵니다.","content":{"application/json":{"example":{"error":"upload 500"}}}},"502":{"description":"파일 저장소에 연결하지 못했을 때, 또는 저장소 전달이 5분을 넘어 중단되었을 때","content":{"application/json":{"example":{"error":"The operation was aborted due to timeout"}}}}}}},"/api/shipping/process":{"post":{"tags":["무역서류 점검"],"operationId":"process-start","summary":"쪽 처리 시작","description":"업로드한 파일의 한 쪽에 대해 분류 또는 핵심정보 추출 작업을 시작하고 jobId 를 받습니다.\n\n`mode` 가 `classify` 면 서류 종류만, `full` 이면 서류 종류와 핵심정보를 얻습니다. 작업은 비동기이므로 결과는 `GET /api/shipping/process?job=` 으로 받습니다.\n\nPOST 는 키 유무와 `fileId`·`page` 필수 값만 확인합니다. 쪽 번호가 파일의 쪽 수 안에 있는지는 확인하지 않으므로, 범위 밖 쪽은 지정하지 마십시오. 처리 중의 오류는 POST 가 아니라 GET 조회의 `error` 상태로 나옵니다.\n\n처리 시간: 요청 자체는 즉시 응답합니다. 실제 처리 시간은 GET 조회로 기다립니다.","parameters":[{"name":"x-clip-key","in":"header","required":true,"description":"API 키. 발급받은 키를 넣으십시오.","schema":{"type":"string","description":"API 키. 발급받은 키를 넣으십시오.","examples":["YOUR_API_KEY"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string","description":"업로드 응답의 fileId. 업로드할 때 쓴 키와 같은 키로 호출하십시오.","examples":["f_8c21a7e4"]},"page":{"type":"integer","description":"처리할 쪽 번호(1부터 시작). 파일의 쪽 수 안의 번호만 지정하십시오.","examples":["1"]},"mode":{"type":"string","description":"`classify`(서류 종류만) 또는 `full`(종류와 핵심정보)","default":"full"}},"required":["fileId","page"]}}}},"responses":{"200":{"description":"작업 식별자. 결과가 아니라 작업 번호입니다.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"작업 식별자(UUID). GET 조회에 씁니다."}},"required":["jobId"]},"example":{"jobId":"3f2b9c1e-6a4d-4e8b-9f0a-2d7c5b1e8a40"}}}},"400":{"description":"fileId 가 없거나 page 가 1 미만일 때","content":{"application/json":{"example":{"error":"fileId and page are required"}}}},"401":{"description":"x-clip-key 헤더가 없거나 비어 있을 때. 본문의 문구는 화면 안내용이므로, 판별에는 code 값(api_key_required)을 쓰십시오.","content":{"application/json":{"example":{"error":"우측 상단에 API Key 를 입력해 주세요.","code":"api_key_required"}}}}}},"get":{"tags":["무역서류 점검"],"operationId":"process-result","summary":"쪽 처리 결과 조회","description":"jobId 의 상태를 조회합니다. 처리가 끝나면 쪽의 서류 종류와 핵심정보를 돌려줍니다.\n\n`status` 가 `pending` 이면 아직 처리 중입니다. 3초 간격으로 다시 조회하십시오. `done` 이면 `result` 를 받습니다. 결과(오류 결과 포함)는 한 번 받으면 서버에서 삭제됩니다.\n\n처리 시간: 처리 시간은 파일 크기와 쪽 수에 따라 수 초에서 수 분입니다. 클라이언트 타임아웃은 20분 이상 권장합니다.","parameters":[{"name":"x-clip-key","in":"header","required":false,"description":"이 조회는 키를 검사하지 않습니다. 같은 키로 보내는 것을 권장합니다.","schema":{"type":"string","description":"이 조회는 키를 검사하지 않습니다. 같은 키로 보내는 것을 권장합니다.","examples":["YOUR_API_KEY"]}},{"name":"job","in":"query","required":true,"description":"POST 응답의 jobId","schema":{"type":"string","description":"POST 응답의 jobId","examples":["3f2b9c1e-6a4d-4e8b-9f0a-2d7c5b1e8a40"]}}],"responses":{"200":{"description":"`status` 가 `pending`, `done`, `error`, `unknown` 중 하나입니다. `done` 일 때만 `result` 가 있고, `error` 일 때만 `error` 메시지가 있습니다.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","done","error","unknown"],"description":"작업 상태"},"result":{"type":"object","description":"status 가 done 일 때의 쪽 처리 결과","properties":{"page":{"type":"integer","description":"처리한 쪽 번호"},"type":{"type":"string","description":"서류 종류 이름(분류 결과). 분류하지 못하면 document 입니다. 값은 고정 목록이 아닙니다."},"keys":{"type":"array","description":"추출된 핵심정보 목록. classify 모드에서는 비어 있습니다.","items":{"type":"object","description":"추출된 핵심정보 한 항목","properties":{"key":{"type":"string","description":"항목 이름(예: L/C No., Amount). 서류 종류마다 다릅니다."},"value":{"type":"string","description":"추출된 값 문자열. 값을 찾지 못하면 빈 문자열입니다."},"informationList":{"type":"array","items":{"type":"string"},"description":"여러 줄로 된 항목(예: 서류 목록, 조건 목록)의 줄 단위 값. 해당하지 않으면 생략됩니다."},"processed":{"type":"object","description":"금액·과부족처럼 구조화된 값(예: 금액은 currency·amount, 과부족은 plus·minus). 해당하지 않으면 생략됩니다."},"reference":{"type":"object","description":"값이 적힌 쪽 번호(문자열 키)와 단어 번호 목록. 번호로 words 에서 좌표를 찾습니다.","additionalProperties":{"type":"array","items":{"type":"integer"}}},"confidence":{"type":"number","description":"항목의 등급 점수(0~1). 확률이 아니라 처리 엔진이 매긴 등급 점수입니다. 값이 낮은 항목은 사람이 다시 확인할 후보로 참고하십시오. 값이 없는 응답도 있으니 없으면 표시를 생략하십시오."}},"required":["key","value","reference"]}},"words":{"type":"object","description":"근거 단어의 좌표. 키 이름이 단어 번호(문자열)이고, 값이 좌표입니다(쪽 번호 단계가 없는 평면 맵). keys 의 reference 가 가리키는 단어만 들어 있습니다.","additionalProperties":{"type":"array","items":{"type":"number"},"description":"단어의 좌표 [x0, y0, x1, y1]. 보통 쪽 크기에 대한 0~1 비율입니다."}}},"required":["page","type","keys","words"]},"error":{"type":"string","description":"status 가 error 일 때의 오류 메시지"}},"required":["status"]},"example":{"status":"done","result":{"page":1,"type":"letter of credit","keys":[{"key":"L/C No.","value":"LC2026-0042","reference":{"1":[12]},"confidence":0.97},{"key":"Amount","value":"USD 125,000.00","processed":{"currency":"USD","amount":125000},"reference":{"1":[18,19]},"confidence":0.95}],"words":{"12":[0.11,0.08,0.31,0.1],"18":[0.2,0.42,0.3,0.44],"19":[0.32,0.42,0.42,0.44]}}}}}},"401":{"description":"처리 엔진이 키를 거부할 때. 상태 코드는 처리 엔진의 응답을 따르며, 본문의 status 는 error 입니다.","content":{"application/json":{"example":{"status":"error","error":"process 401"}}}},"404":{"description":"jobId 를 찾을 수 없을 때. 잘못된 값, 이미 한 번 받은 값, 서버 재시작으로 사라진 값, 정리된 값이 해당합니다. 본문의 status 가 unknown 입니다. / 처리 엔진이 파일이나 쪽을 찾지 못했을 때. 본문의 status 가 error 이므로, unknown(작업 없음)과 구분하십시오.","content":{"application/json":{"example":{"status":"unknown"}}}},"413":{"description":"파일 크기가 서버 설정의 한도를 넘을 때. 한도는 서버 설정에 따릅니다.","content":{"application/json":{"example":{"status":"error","error":"File size exceeds limit"}}}},"429":{"description":"요청이 너무 많을 때","content":{"application/json":{"example":{"status":"error","error":"process 429"}}}},"502":{"description":"처리 엔진에 연결하지 못했을 때, 또는 상태를 알 수 없을 때","content":{"application/json":{"example":{"status":"error","error":"fetch failed"}}}}}}},"/api/shipping/classify":{"post":{"tags":["무역서류 점검"],"operationId":"classify","summary":"파일 서류 종류 분류","description":"파일 1건을 한 번에 처리해 서류 종류와 쪽 수를 돌려줍니다. 응답까지 기다리는 동기 호출입니다.\n\n핵심정보는 추출하지 않습니다. 파일에 서류가 한 종류만 들어 있을 때 쓰십시오. 여러 서류가 섞인 파일은 `review` 를 사용하십시오. 파일 전체를 동기로 처리하므로 쪽 수가 많으면 시간과 비용이 큽니다. 쪽 수 확인만을 목적으로 호출하지 마십시오.\n\n처리 시간: 처리 시간은 파일 크기와 쪽 수에 따라 수 초에서 수 분입니다. 클라이언트 타임아웃은 20분 이상 권장합니다. 서버 내부에서 처리 엔진 호출이 실패하면 재시도가 최대 3회까지 이루어지므로, 실패 응답이 늦게 올 수 있고 OCR 이 중복 실행될 수 있습니다.","parameters":[{"name":"x-clip-key","in":"header","required":true,"description":"API 키. 발급받은 키를 넣으십시오.","schema":{"type":"string","description":"API 키. 발급받은 키를 넣으십시오.","examples":["YOUR_API_KEY"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"서류 파일. 파일 크기 한도는 서버 설정에 따릅니다."}},"required":["file"]}}}},"responses":{"200":{"description":"파일의 대표 서류 종류와 신뢰도, 쪽 수입니다.","content":{"application/json":{"schema":{"type":"object","properties":{"documentType":{"type":"string","description":"서류 종류 이름. 분류하지 못하면 unknown 또는 document 가 올 수 있습니다. 값은 고정 목록이 아닙니다."},"confidence":{"type":"number","description":"서류 분류 신뢰도(0~1). 현재는 값이 제공되지 않아 항상 0 으로 돌아오므로 판단에 쓰지 마십시오."},"pages":{"type":"integer","description":"파일의 쪽 수"}},"required":["documentType","confidence","pages"]},"example":{"documentType":"commercial invoice","confidence":0,"pages":3}}}},"400":{"description":"file 필드가 없거나 파일이 아닐 때","content":{"application/json":{"example":{"error":"file is required"}}}},"401":{"description":"x-clip-key 헤더가 없거나 비어 있을 때. 본문의 문구는 화면 안내용이므로, 판별에는 code 값(api_key_required)을 쓰십시오. / 키가 잘못되었을 때. 처리 엔진의 응답 상태를 그대로 전달합니다.","content":{"application/json":{"example":{"error":"우측 상단에 API Key 를 입력해 주세요.","code":"api_key_required"}}}},"403":{"description":"키에 이 작업 권한이 없을 때. 처리 엔진의 응답 상태를 그대로 전달합니다.","content":{"application/json":{"example":{"error":"Clip API error 403: Forbidden","status":403}}}},"404":{"description":"처리 엔진이 대상을 찾지 못했을 때. 처리 엔진의 응답 상태를 그대로 전달합니다.","content":{"application/json":{"example":{"error":"Clip API error 404: Not Found","status":404}}}},"413":{"description":"파일 크기가 서버 설정의 한도를 넘을 때. 한도는 서버 설정에 따르며, 현재 한도는 dashboard 에서 확인할 수 있습니다.","content":{"application/json":{"example":{"error":"Clip API error 413: File size exceeds limit","status":413}}}},"429":{"description":"요청이 너무 많을 때. 잠시 뒤 다시 보내십시오.","content":{"application/json":{"example":{"error":"Clip API error 429: Too Many Requests","status":429}}}},"500":{"description":"처리 엔진이 오류를 돌려줄 때(상태 코드는 그대로 전달됩니다)","content":{"application/json":{"example":{"error":"Clip API error 500: Internal Server Error","status":500}}}},"502":{"description":"처리 엔진에 연결하지 못했을 때, 또는 처리 엔진의 응답 형식이 맞지 않을 때 / 응답 형식이 맞지 않을 때(메시지에 Invalid OCR response shape 가 붙습니다)","content":{"application/json":{"example":{"error":"Network error: fetch failed","status":502}}}}}}},"/api/shipping/extract":{"post":{"tags":["무역서류 점검"],"operationId":"extract","summary":"파일 핵심정보 추출","description":"파일 1건을 한 번에 처리해 서류 종류와 핵심정보를 평면 목록으로 돌려줍니다. 동기 호출입니다.\n\n`data` 는 항목 이름을 키로 하는 평면 객체입니다. 쪽 구분 없이 합친 값이므로 서류가 한 종류만 들어 있는 파일에 맞습니다.\n\n처리 시간: 처리 시간은 파일 크기와 쪽 수에 따라 수 초에서 수 분입니다. 클라이언트 타임아웃은 20분 이상 권장합니다. 서버 내부에서 처리 엔진 호출이 실패하면 재시도가 최대 3회까지 이루어지므로, 실패 응답이 늦게 올 수 있고 OCR 이 중복 실행될 수 있습니다.","parameters":[{"name":"x-clip-key","in":"header","required":true,"description":"API 키. 발급받은 키를 넣으십시오.","schema":{"type":"string","description":"API 키. 발급받은 키를 넣으십시오.","examples":["YOUR_API_KEY"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"서류 파일. 파일 크기 한도는 서버 설정에 따릅니다."}},"required":["file"]}}}},"responses":{"200":{"description":"서류 종류, 신뢰도, 쪽 수, 그리고 핵심정보입니다.","content":{"application/json":{"schema":{"type":"object","properties":{"documentType":{"type":"string","description":"서류 종류 이름. 값은 고정 목록이 아닙니다."},"confidence":{"type":"number","description":"서류 분류 신뢰도(0~1). 현재는 값이 제공되지 않아 항상 0 으로 돌아오므로 판단에 쓰지 마십시오."},"pages":{"type":"integer","description":"파일의 쪽 수"},"data":{"type":"object","description":"항목 이름 → 값 문자열. 값이 비어 있는 항목은 빠집니다. 같은 이름의 항목이 여러 쪽에 있으면 뒤의 값이 남습니다.","additionalProperties":{"type":"string"}}},"required":["documentType","confidence","pages","data"]},"example":{"documentType":"commercial invoice","confidence":0,"pages":3,"data":{"Invoice No.":"INV-2026-0931","Total Amount":"USD 125,000.00"}}}}},"400":{"description":"file 필드가 없거나 파일이 아닐 때","content":{"application/json":{"example":{"error":"file is required"}}}},"401":{"description":"x-clip-key 헤더가 없거나 비어 있을 때. 본문의 문구는 화면 안내용이므로, 판별에는 code 값(api_key_required)을 쓰십시오. / 키가 잘못되었을 때. 처리 엔진의 응답 상태를 그대로 전달합니다.","content":{"application/json":{"example":{"error":"우측 상단에 API Key 를 입력해 주세요.","code":"api_key_required"}}}},"403":{"description":"키에 이 작업 권한이 없을 때. 처리 엔진의 응답 상태를 그대로 전달합니다.","content":{"application/json":{"example":{"error":"Clip API error 403: Forbidden","status":403}}}},"404":{"description":"처리 엔진이 대상을 찾지 못했을 때. 처리 엔진의 응답 상태를 그대로 전달합니다.","content":{"application/json":{"example":{"error":"Clip API error 404: Not Found","status":404}}}},"413":{"description":"파일 크기가 서버 설정의 한도를 넘을 때. 한도는 서버 설정에 따르며, 현재 한도는 dashboard 에서 확인할 수 있습니다.","content":{"application/json":{"example":{"error":"Clip API error 413: File size exceeds limit","status":413}}}},"429":{"description":"요청이 너무 많을 때. 잠시 뒤 다시 보내십시오.","content":{"application/json":{"example":{"error":"Clip API error 429: Too Many Requests","status":429}}}},"500":{"description":"처리 엔진이 오류를 돌려줄 때(상태 코드는 그대로 전달됩니다)","content":{"application/json":{"example":{"error":"Clip API error 500: Internal Server Error","status":500}}}},"502":{"description":"처리 엔진에 연결하지 못했을 때, 또는 처리 엔진의 응답 형식이 맞지 않을 때 / 응답 형식이 맞지 않을 때(메시지에 Invalid OCR response shape 가 붙습니다)","content":{"application/json":{"example":{"error":"Network error: fetch failed","status":502}}}}}}},"/api/shipping/review":{"post":{"tags":["무역서류 점검"],"operationId":"review-start","summary":"파일 서류 분리·추출 시작","description":"파일 1건을 서류별로 나누고 핵심정보를 추출하는 작업을 시작해 jobId 를 받습니다.\n\n한 파일에 여러 서류(예: 신용장과 첨부 서류)가 섞여 있을 때 쪽 단위 호출 없이 서류별 결과를 받을 수 있습니다. `mode` 가 `classify` 면 서류 범위만 받고 키는 받지 않습니다.\n\n처리 시간: 요청 자체는 즉시 응답합니다. 처리는 GET 조회로 기다립니다.\n\n**이 경로는 clip 웹 화면이 쓰지 않는 경로입니다.** 서류 경계는 파일 전체 분류로 정해지므로 화면의 결과와 다를 수 있습니다. 연동 전에 실제 샘플 파일로 응답 형식과 결과를 먼저 확인하십시오.","parameters":[{"name":"x-clip-key","in":"header","required":true,"description":"API 키. 발급받은 키를 넣으십시오.","schema":{"type":"string","description":"API 키. 발급받은 키를 넣으십시오.","examples":["YOUR_API_KEY"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"서류 파일. 파일 크기 한도는 서버 설정에 따릅니다."},"mode":{"type":"string","description":"`classify`(서류 범위만) 또는 `full`(범위와 핵심정보)","default":"full"}},"required":["file"]}}}},"responses":{"200":{"description":"작업 식별자입니다. 결과는 GET 으로 받습니다.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"작업 식별자(UUID)"}},"required":["jobId"]},"example":{"jobId":"9d4e1a7b-2c3f-4a6e-8b1d-5f0e7c9a2b11"}}}},"400":{"description":"file 필드가 없거나 파일이 아닐 때","content":{"application/json":{"example":{"error":"file is required"}}}},"401":{"description":"x-clip-key 헤더가 없거나 비어 있을 때. 본문의 문구는 화면 안내용이므로, 판별에는 code 값(api_key_required)을 쓰십시오.","content":{"application/json":{"example":{"error":"우측 상단에 API Key 를 입력해 주세요.","code":"api_key_required"}}}}}},"get":{"tags":["무역서류 점검"],"operationId":"review-result","summary":"서류 분리·추출 결과 조회","description":"jobId 의 상태를 조회합니다. 완료되면 서류별 범위와 핵심정보, 근거 좌표를 돌려줍니다.\n\n`status` 가 `pending` 이면 3초 간격으로 다시 조회하십시오. `done` 이면 `result` 를 받습니다. 결과(오류 결과 포함)는 한 번 받으면 서버에서 삭제됩니다.\n\n처리 시간: 처리 시간은 파일 크기와 쪽 수에 따라 수 초에서 수 분입니다. 클라이언트 타임아웃은 20분 이상 권장합니다.","parameters":[{"name":"x-clip-key","in":"header","required":false,"description":"이 조회는 키를 검사하지 않습니다. 같은 키로 보내는 것을 권장합니다.","schema":{"type":"string","description":"이 조회는 키를 검사하지 않습니다. 같은 키로 보내는 것을 권장합니다.","examples":["YOUR_API_KEY"]}},{"name":"job","in":"query","required":true,"description":"POST 응답의 jobId","schema":{"type":"string","description":"POST 응답의 jobId","examples":["9d4e1a7b-2c3f-4a6e-8b1d-5f0e7c9a2b11"]}}],"responses":{"200":{"description":"`status` 가 `pending`, `done`, `error`, `unknown` 중 하나입니다. `done` 일 때만 `result` 가 있습니다.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","done","error","unknown"],"description":"작업 상태"},"result":{"type":"object","description":"status 가 done 일 때의 결과","properties":{"documents":{"type":"array","description":"서류 목록(시작 쪽 순서). 범위는 대체로 앞 서류의 끝 다음 쪽부터 이어집니다. 다만 시작 쪽이 같은 두 서류가 있으면 그 쪽이 두 서류에 모두 들어갈 수 있습니다.","items":{"type":"object","properties":{"type":{"type":"string","description":"서류 종류 이름. 값은 고정 목록이 아닙니다."},"pageStart":{"type":"integer","description":"서류의 첫 쪽 번호"},"pageEnd":{"type":"integer","description":"서류의 마지막 쪽 번호(포함)"},"keys":{"type":"array","description":"이 서류의 핵심정보. classify 모드에서는 비어 있습니다. 여러 서류에 걸친 항목은 각 서류에 복제됩니다.","items":{"type":"object","description":"추출된 핵심정보 한 항목","properties":{"key":{"type":"string","description":"항목 이름(예: L/C No., Amount). 서류 종류마다 다릅니다."},"value":{"type":"string","description":"추출된 값 문자열. 값을 찾지 못하면 빈 문자열입니다."},"informationList":{"type":"array","items":{"type":"string"},"description":"여러 줄로 된 항목(예: 서류 목록, 조건 목록)의 줄 단위 값. 해당하지 않으면 생략됩니다."},"processed":{"type":"object","description":"금액·과부족처럼 구조화된 값(예: 금액은 currency·amount, 과부족은 plus·minus). 해당하지 않으면 생략됩니다."},"reference":{"type":"object","description":"값이 적힌 쪽 번호(문자열 키)와 단어 번호 목록. 번호로 words 에서 좌표를 찾습니다.","additionalProperties":{"type":"array","items":{"type":"integer"}}}},"required":["key","value","reference"]}}},"required":["type","pageStart","pageEnd","keys"]}},"words":{"type":"object","description":"근거 단어 좌표. 2단계 맵입니다. 바깥 키는 쪽 번호(문자열), 안쪽 키는 단어 번호(문자열), 값은 좌표입니다. classify 모드에서는 비어 있습니다.","additionalProperties":{"type":"object","additionalProperties":{"type":"array","items":{"type":"number"},"description":"단어의 좌표 [x0, y0, x1, y1]. 보통 쪽 크기에 대한 0~1 비율입니다."}}},"pageCount":{"type":"integer","description":"파일의 전체 쪽 수"}},"required":["documents","words","pageCount"]},"error":{"type":"string","description":"status 가 error 일 때의 오류 메시지"}},"required":["status"]},"example":{"status":"done","result":{"documents":[{"type":"letter of credit","pageStart":1,"pageEnd":2,"keys":[{"key":"L/C No.","value":"LC2026-0042","reference":{"1":[12]}}]},{"type":"commercial invoice","pageStart":3,"pageEnd":3,"keys":[{"key":"Invoice No.","value":"INV-2026-0931","reference":{"3":[40]}}]}],"words":{"1":{"12":[0.11,0.08,0.31,0.1]},"3":{"40":[0.2,0.5,0.4,0.52]}},"pageCount":3}}}}},"401":{"description":"처리 엔진이 키를 거부할 때. 상태 코드는 처리 엔진의 응답을 따르며, 본문의 status 는 error 입니다.","content":{"application/json":{"example":{"status":"error","error":"review 401"}}}},"404":{"description":"jobId 를 찾을 수 없을 때(잘못된 값, 이미 받은 값, 서버 재시작으로 사라진 값, 정리된 값). 본문의 status 가 unknown 입니다. / 처리 엔진이 파일을 찾지 못했을 때. 본문의 status 가 error 이므로 unknown 과 구분하십시오.","content":{"application/json":{"example":{"status":"unknown"}}}},"413":{"description":"파일 크기가 서버 설정의 한도를 넘을 때. 한도는 서버 설정에 따릅니다.","content":{"application/json":{"example":{"status":"error","error":"File size exceeds limit"}}}},"429":{"description":"요청이 너무 많을 때","content":{"application/json":{"example":{"status":"error","error":"review 429"}}}},"502":{"description":"처리 엔진에 연결하지 못했을 때, 또는 상태를 알 수 없을 때","content":{"application/json":{"example":{"status":"error","error":"fetch failed"}}}}}}}},"components":{"securitySchemes":{"clipKey":{"type":"apiKey","in":"header","name":"x-clip-key","description":"발급받은 CLIP API 키"}}},"security":[{"clipKey":[]}]}