FLOWNCO DEVELOPERS · V1

간편분석 API

서비스의 서버에서 시험지를 보내고, 분석 상태와 손글씨 첨삭 PDF를 받아보세요. 홈페이지 간편분석과 같은 처리 흐름과 보고서를 사용합니다.

1. 이메일로 키를 받으세요

간편분석 화면 상단에서 이메일을 입력해 요청하면, 사전 승인된 이메일로 키와 이용 안내를 보내드립니다. 그 외 이메일은 검토 대기로 접수됩니다. 메일 서비스가 준비되지 않았거나 발송에 실패하면 발송 완료로 표시하지 않습니다.

키는 기본 90일간 유효합니다. 같은 이메일로 새 키를 받아도 기존 키를 자동 폐기하지 않으며, 해당 이메일의 작업은 계속 조회할 수 있습니다.

API는 서버 간 연동용입니다. 키를 서비스 서버의 비공개 환경변수에 보관하고, 웹페이지·모바일 앱·공개 저장소에 넣지 마세요. 모든 분석 요청에는 HTTPS와 Bearer 인증이 필요합니다.

Authorization: Bearer YOUR_API_KEY

2. 파일 전송 → 분석 요청 → PDF 받기

아래 예시는 서버 터미널의 curl 기준입니다. API_KEY 환경변수에 이메일로 받은 키를 설정해 주세요.

① 시험지 파일 전송

curl -X POST 'https://www.flownco.co.kr/api/quick-analysis/v1/files?name=exam.pdf' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/pdf' \
  --data-binary @exam.pdf

{"ok":true,"file":{"id":"qfile_000000000000000000000000","name":"exam.pdf","expiresAt":"..."}}

② 간편분석 요청

응답의 file.id를 넣어 주세요. 같은 요청을 재전송할 때는 같은 idempotencyKey를 사용합니다. 공백 없는 ASCII 문자 1~100자로 지정해 주세요.

curl -X POST 'https://www.flownco.co.kr/api/quick-analysis/v1/analyses' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"fileId":"qfile_000000000000000000000000","idempotencyKey":"exam-20261031-001","reportType":"simple","explanationLevel":"neutral"}'

{"ok":true,"analysis":{"id":"analysis_000000000000000000000000","status":"queued","reportType":"simple","reportReady":false}}

③ 상태 조회

아래 예시 ID를 분석 접수 응답의 analysis.id로 바꿔 주세요. 분석은 비동기로 진행됩니다. 5초 이상의 간격으로 조회하고, analysis.reportReady가 true이면 PDF를 받으세요. 워커 연결과 대기 작업에 따라 처리 시간이 달라집니다.

curl 'https://www.flownco.co.kr/api/quick-analysis/v1/analyses/analysis_000000000000000000000000' \
  -H "Authorization: Bearer $API_KEY"

④ 손글씨 첨삭 PDF 다운로드

curl 'https://www.flownco.co.kr/api/quick-analysis/v1/analyses/analysis_000000000000000000000000/report' \
  -H "Authorization: Bearer $API_KEY" \
  --output feedback.pdf

reportType: "simple"은 간편보고서, "detailed"은 상세보고서입니다. 두 유형 모두 기존 서비스의 첨삭 페이지를 포함합니다.

3. API 목록

기본 주소: https://www.flownco.co.kr/api/quick-analysis/v1

메서드	경로	용도
GET	`/status`	발급 서비스 준비 상태·문서·이용 한도
POST	`/key-requests`	이메일로 키 요청. `email`, `consent: true`
GET	`/key`	현재 키의 만료일과 이용 정보
DELETE	`/key`	현재 키 폐기
POST	`/files?name=exam.pdf`	파일 바이트 전송. multipart 형식은 사용하지 않음
POST	`/analyses`	간편분석 접수
GET	`/analyses/{id}`	작업 상태·진행 상황·경과 시간 조회
GET	`/analyses/{id}/report`	준비된 PDF 받기
DELETE	`/analyses/{id}`	해당 업로드 시험지와 그 파일에서 파생된 분석·보고서 삭제

분석 요청의 선택값

reportType: simple(기본), detailed
explanationLevel: neutral(기본), elementary_lower, elementary_upper, middle, high

4. 상태와 오류 처리

응답	의미·처리
200 / 201 / 202	조회·전송·접수 성공. 202는 분석 완료가 아닌 접수 상태
400 / 415	입력값·파일 형식을 확인
401 / 403	키의 유효기간·폐기 여부·인증 방식 확인
404	작업이 없거나 현재 이메일의 작업이 아님
409	같은 멱등 키로 다른 요청을 보냈거나 PDF가 아직 준비되지 않음
413	파일 크기 초과
429	이용 한도 초과. `Retry-After` 후 재시도
503	키 발급 메일 또는 분석 연결 서비스가 준비되지 않음

작업의 failed 상태는 분석 실패이며, reportReady: true를 확인하기 전에는 PDF가 준비된 것으로 처리하지 마세요. 키는 HTTP 응답에 반환되지 않습니다.

5. 이용 범위

PDF·PNG·JPG/JPEG 한 파일을 요청당 최대 40MB까지 전송할 수 있습니다.
초기 기본 한도는 이메일별 하루(UTC 기준) 분석 20건·업로드 40건, 동시 진행 2건, 분당 API 요청 30회입니다. 운영 설정에 따른 현재 한도는 /status에서 확인하세요.
발급 메일에는 별도 요청 횟수 제한이 있습니다. 연속 클릭으로 새 키를 여러 개 요청하지 마세요.
다른 이메일의 파일과 작업에는 접근할 수 없습니다. 같은 이메일로 발급받은 키는 해당 이메일의 작업을 공유합니다.
파일의 expiresAt 이전에 결과를 내려받아 보관해 주세요.
분석 결과는 AI 첨삭 초안입니다. 강사가 확인한 뒤 활용해 주세요.

연동·승인·이용 한도 문의는 문의하기로 남겨 주세요. 이용해 주셔서 감사합니다.