관세 서류 분석기

파일명	상태	진행	등록일시
아직 등록된 서류가 없습니다. PDF 파일을 업로드해 주세요.

API 연동 가이드

외부 시스템에서 이 서비스를 API로 호출하여 PDF 서류를 분석할 수 있습니다.
아래 흐름대로 호출하면 됩니다.

전체 흐름

1 PDF 업로드 — PDF 파일을 서버에 전송하면 고유 ID(UUID)를 받습니다.

↓

2 진행 상태 확인 — 받은 ID로 주기적으로 상태를 조회합니다. (대기중 → 분석중 → 완료)

↓

3 결과 가져오기 — 상태가 "completed"가 되면 분석 결과를 가져옵니다.

1단계: PDF 업로드

PDF 파일을 multipart/form-data 형식으로 업로드합니다.

POST /api/upload

PDF 파일을 업로드하고 분석을 시작합니다. 고유 ID를 반환합니다.

curlcurl -X POST https://tariff.cloud-handson.com/api/upload \
  -F "file=@선적서류.pdf"

응답 예시:

JSON{
  "id": "d2dd462e-5e7c-4f9f-87cc-0280f825457f",
  "filename": "선적서류.pdf",
  "status": "pending"
}

📌 반환된 id 값을 저장해 두세요. 이후 모든 조회에 이 값을 사용합니다.

2단계: 진행 상태 확인

분석이 완료될 때까지 주기적으로(3~5초 간격) 상태를 확인합니다.

GET /api/jobs/{id}

해당 ID의 분석 작업 상태와 결과를 조회합니다.

curlcurl https://tariff.cloud-handson.com/api/jobs/d2dd462e-5e7c-4f9f-87cc-0280f825457f

상태(status) 종류:

pending — 대기중 (아직 처리 시작 전)
processing — 분석중 (progress 필드에서 세부 진행 확인 가능)
completed — 완료 (extracted_info에 분석 결과 포함)
failed — 실패 (error_message에 원인 포함)

분석중 응답 예시:

JSON{
  "id": "d2dd462e-...",
  "status": "processing",
  "progress": "[1/3 OCR] page 2/5",
  "extracted_info": null
}

3단계: 결과 가져오기

status가 "completed"가 되면 같은 API에서 결과를 확인할 수 있습니다.

JSON{
  "id": "d2dd462e-...",
  "status": "completed",
  "progress": "Done (3/3)",
  "filename": "선적서류.pdf",
  "md_content": "## Page 1\n...(OCR 결과 마크다운)...",
  "extracted_info": "① 수입자 기본정보\n- 업체명: ...\n② 신고주체 정보\n..."
}

주요 필드 설명:

md_content — OCR로 인식한 원문 (마크다운 형식)
extracted_info — AI가 추출한 관세 서류 분석 결과

프롬프트 변경 후 재분석 (선택사항)

OCR은 유지하고 AI 분석만 다시 실행하고 싶을 때 사용합니다.
프롬프트를 직접 전달하면 저장된 프롬프트 대신 해당 내용으로 분석합니다.

POST /api/jobs/{id}/re-extract

기존 OCR 결과를 기반으로 AI 분석만 다시 실행합니다.

curlcurl -X POST https://tariff.cloud-handson.com/api/jobs/d2dd462e-.../re-extract \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a customs analyst...",
    "question_prompt": "아래 문서에서 수입자 정보만 추출해주세요..."
  }'

📌 system_prompt와 question_prompt를 생략하면 서버에 저장된 기본 프롬프트가 사용됩니다.

처음부터 재처리 (선택사항)

OCR부터 다시 하고 싶을 때 사용합니다.

POST /api/jobs/{id}/retry

OCR + AI 분석을 처음부터 다시 실행합니다.

curlcurl -X POST https://tariff.cloud-handson.com/api/jobs/d2dd462e-.../retry

전체 목록 조회

GET /api/jobs

등록된 모든 분석 작업 목록을 조회합니다. (최신순)

curlcurl https://tariff.cloud-handson.com/api/jobs

PDF 원본 다운로드

GET /api/jobs/{id}/pdf

업로드한 원본 PDF 파일을 다운로드합니다.

curlcurl -o output.pdf https://tariff.cloud-handson.com/api/jobs/d2dd462e-.../pdf

작업 삭제

DELETE /api/jobs/{id}

분석 작업과 업로드된 PDF 파일을 삭제합니다.

curlcurl -X DELETE https://tariff.cloud-handson.com/api/jobs/d2dd462e-...

Python 연동 예제 (전체 흐름)

Pythonimport time
import requests

BASE = "https://tariff.cloud-handson.com"

# 1. PDF 업로드
with open("선적서류.pdf", "rb") as f:
    res = requests.post(f"{BASE}/api/upload", files={"file": f})
job_id = res.json()["id"]
print(f"업로드 완료, ID: {job_id}")

# 2. 상태 확인 (완료될 때까지 대기)
while True:
    res = requests.get(f"{BASE}/api/jobs/{job_id}")
    job = res.json()
    print(f"상태: {job['status']} / {job.get('progress', '')}")

    if job["status"] == "completed":
        break
    elif job["status"] == "failed":
        print(f"실패: {job['error_message']}")
        break

    time.sleep(3)  # 3초 간격으로 확인

# 3. 결과 출력
if job["status"] == "completed":
    print("\n=== 분석 결과 ===")
    print(job["extracted_info"])

    print("\n=== OCR 원문 ===")
    print(job["md_content"][:500])  # 앞부분만 출력

Swagger (자동 API 문서)

FastAPI가 자동 생성하는 대화형 API 문서를 사용할 수도 있습니다.

/docs — Swagger UI (API 직접 테스트 가능)
/redoc — ReDoc (읽기 편한 문서)