리포트 생성 흐름
리포트 생성부터 이미지 등록, 자동 분석, 자동 공개, 완료 알림까지 전체 흐름을 설명합니다.
리포트 생성은 단계가 여러 개지만, 파트너가 호출하는 것은 POST /reports 하나입니다.
분석 트리거, finalize, 공개는 플랫폼이 자동으로 처리하고, 완료는 webhook으로 알립니다.
큰 그림
핵심 동작:
- 이미지를 등록하면 분석이 자동으로 시작됩니다. 일괄
analyze호출은 필요 없습니다. - 공유 링크(
share_url)는 생성 응답에서 미리 받습니다. 바로 저장해 두면 되고, 분석·공개가 끝나면 그 URL이 자동으로 열람 가능해집니다. - 완료와 실패는 webhook으로 알립니다. 다만 신뢰할 수 있는 완료 확인은
GET /reports/{id}폴링으로 합니다(webhook은 알림용).
모드 A — 고객 URL (이미지 URL 보유 시)
자사 스토리지에 이미지를 두고 변하지 않는(immutable) URL을 줄 수 있다면 가장 간단합니다.
POST /reports 요청에 이미지 URL을 넣으면 한 번의 호출로 흐름이 시작됩니다.
이미지를 두 경로로 다루는 이유
분석은 고객 URL을 그대로 사용하고, 리포트를 안정적으로 표시할 이미지는 ATRACE 스토리지에 사본으로 둡니다. 리포트 화면은 항상 ATRACE URL로 렌더됩니다. 전제: 고객 URL은 변하지 않아야(immutable) 합니다.
모드 B — Pre-Signed (자체 스토리지가 없을 때)
이미지를 호스팅할 곳이 없다면 ATRACE 스토리지에 직접 업로드합니다. 플랫폼 서버는 이미지 바이트를 직접 받지 않습니다. 업로드는 스토리지로 곧바로 전송됩니다.
| 구분 | 모드 A (고객 URL) | 모드 B (Pre-Signed) |
|---|---|---|
| 대상 | immutable URL 보유 고객 | 자체 스토리지 없는 고객 |
| 파트너 호출 | POST /reports 1번 | POST /reports + POST /images |
| 이미지 업로드 | 없음 (URL만 전달) | 스토리지에 직접 PUT |
자세한 비교는 이미지 수집을 보세요.
리포트 상태 전이
summary_status는 리포트 전체의 완료도를 나타냅니다:complete/partial/failed.- 각 슬롯의
status는pending/success/failed입니다. - 일부 필수 슬롯이 시간 내 완료되지 않으면
partial로 전이되고report.failedwebhook이 전송됩니다(무한 대기 방지). - 필수 슬롯이 모두 실패하는 등 회복 불가능한 하드 실패에서는 finalize가
failed로 기록하고report.failedwebhook을 전송합니다.
폴링으로 완료 확인
webhook은 완료 알림용입니다. 신뢰할 수 있는 완료 확인은 GET /reports/{id}를 폴링해 status가
published가 되는 시점으로 판단합니다(summary_status는 완료도를 나타내는 보조 값일 뿐 종료 기준이 아닙니다).
share_url은 생성 시점부터 제공되므로 완료 판단 기준이 아닙니다. 폴링은 "그 URL이 열람 가능해졌는지"만 확인하면 됩니다.
429나 5xx 응답을 받으면 지수 백오프로 재시도하세요.
공개 정책 — 자동 공개와 수동 검토
- 자동 공개(대부분의 파트너): 분석이 끝나면 리포트가 자동으로 공개되고 공유 링크가 생성됩니다.
POST /reports/{id}/publish는 호출하지 않아도 됩니다. - 수동 검토: 사람이 검토한 뒤 공개합니다. 이때만
POST /reports/{id}/publish가 필요합니다.
자동 공개 주의
자동 공개는 필수 슬롯이 다 찼는지(완전성)만 검사하고, 분석값의 정확성은 판단하지 않습니다.
잘못 판독된 리포트가 외부에 노출되면 POST /reports/{id}/unpublish 또는 DELETE /reports/{id}/share로 즉시 회수하세요.
소셜 공유 미리보기 (OG 카드)
share_url(/r/{token})을 카카오톡·문자·슬랙 등에 붙여넣으면 차량 맞춤형 미리보기 카드가 자동으로 함께 표시됩니다. 별도 설정은 필요 없습니다.
- 자동 생성: 카드 이미지는 리포트가 공개(publish)되는 시점에 미리 생성·저장되므로, 링크를 붙여넣는 즉시 미리보기가 뜹니다(생성 지연이나 빈 이미지가 없습니다). CRM 등으로 링크를 자동 발송해도 동일합니다.
- 구성: 차량 번호 + AI 요약 문구 + 가장 심각한 타이어의 트레드 사진(홈 깊이 mm·등급 색 오버레이).
- 자동 갱신: 이후 마모값이 수정되거나 재분석되어 결과가 달라지면 카드도 자동으로 다시 생성됩니다.
같은 링크라도 리포트 상태에 따라 이렇게 다르게 보입니다.
정상 리포트 — 초록 정상 배지, "양호" 요약:
교체가 필요한 리포트 — 빨강 즉시 교체 권장 배지, 교체 안내 요약:
