리포트 생성 흐름

모든 흐름은 POST /reports에서 시작합니다. 고객 URL 모드는 이 호출 하나로 분석이 시작되고, Pre-Signed 모드는 ATRACE가 발급한 URL에 PUT한 뒤 asset_id와 슬롯을 /images에 등록합니다. 그 이후 분석, 콘텐츠 생성, 공개는 플랫폼이 자동으로 처리하고, 완료는 webhook으로 알립니다.

큰 그림

핵심 동작:

• 이미지를 등록하면 분석이 자동으로 시작됩니다. 일괄 analyze 호출은 필요 없습니다.
• 공유 링크(share_url)는 생성 응답에서 미리 받습니다. 바로 저장해 두면 되고, 분석·공개가 끝나면 그 URL이 자동으로 열람 가능해집니다.
• 완료는 report.completed webhook으로 알립니다. 다만 신뢰할 수 있는 완료 확인은 GET /reports/{id} 폴링으로 합니다(webhook은 알림용).
• 자체 렌더링 데이터는 GET /reports/{id}와 GET /reports/{id}/content에서 읽습니다. webhook 본문의 요약은 조회를 대체하지 않습니다.

모드 A — 고객 URL (이미지 URL 보유 시)

자사 스토리지의 공개 이미지 URL을 줄 수 있다면 가장 간단합니다. POST /reports 요청에 이미지 URL을 넣으면 한 번의 호출로 흐름이 시작됩니다.

모드 B — Pre-Signed (자체 스토리지가 없을 때)

이미지를 호스팅할 곳이 없다면 ATRACE가 발급한 URL에 직접 업로드합니다. 이미지 바이트는 Report API JSON 요청 본문으로 보내지 않습니다.

자세한 비교는 이미지 수집을 보세요.

리포트 상태 전이

• analysis_status와 publication_status는 분리된 상태 축입니다. 분석 완료가 곧 공유 공개를 뜻한다고 가정하지 마세요.
• DELETE /reports/{id}는 리포트·공유 접근을 회수하고 폐기 상태로 전환합니다. 반복 호출은 멱등입니다. GET /reports/{id}는 이미지, 슬롯, share_url 없이 폐기 시각과 식별 메타데이터만 담은 tombstone을 반환합니다.
• summary_status는 리포트 전체의 완료도를 나타냅니다: pending / complete / partial / failed.
• 각 슬롯의 status는 pending / success / failed 입니다.
• template.requirements[].minimum_success_count를 충족하지 못한 partial 리포트는 공개할 수 없습니다. 부족한 슬롯을 재분석하거나 새 원본으로 교체해 성공 개수 조건을 충족해야 합니다.

폴링으로 완료 확인

webhook은 완료 알림용입니다. 신뢰할 수 있는 결과는 인증된 GET /reports/{id}에서 확인합니다. 자체 렌더링은 analysis_status == "complete", ATRACE 공유 화면은 publication_status == "published"를 각각 종료 조건으로 사용하세요.

생성 응답의 share_url은 미리 발급된 URL이므로 완료 판단 기준이 아닙니다. GET /reports/{id}의 links.share는 게시가 완료되고 링크가 회수·만료되지 않은 경우에만 반환됩니다. partial 또는 failed라면 실패 슬롯을 복구한 뒤 다시 확인합니다. analysis_status == "complete"가 되면 links.content를 조회해 status == "ready"인 콘텐츠를 사용하세요. 준비 중 202에는 Retry-After가 포함됩니다. 429나 5xx 응답을 받으면 지수 백오프로 재시도하세요.

만료·재촬영·재분석

Pre-Signed upload_url은 발급 후 2시간(7200초) 동안 유효합니다. 만료됐거나 이미지를 재촬영할 때는 POST /reports/{id}/upload-targets에 필요한 slots를 보내 새 asset_id와 URL을 발급받습니다. 새 원본을 PUT한 뒤 POST /reports/{id}/images?replace=true에 새 asset_id와 같은 슬롯 참조를 등록하세요. PUT에는 타깃의 required_headers에 포함된 Cache-Control: max-age=60도 반드시 전송해야 합니다.

현재 슬롯에 이미 적용된 같은 asset_id의 /images 등록 재시도는 멱등입니다. 재촬영 원본은 반드시 새 asset_id를 사용합니다. 교체 또는 POST /reports/{id}/analyze 재분석을 시작하면 기존 공유 URL은 일시적으로 비공개되고, 분석이 성공하면 같은 공유 흐름으로 자동 재공개됩니다.

폐기된 리포트에는 이미지 등록·타깃 발급·재분석을 포함한 모든 변경 요청이 409 report_discarded로 거절됩니다. 새 검사는 새 external_inspection_id로 POST /reports를 호출해 시작합니다.

공개 정책 — 자동 공개와 수동 검토

• 자동 공개(대부분의 파트너): 분석이 끝나면 리포트가 자동으로 공개되고 생성 시 받은 공유 링크가 열람 가능해집니다. POST /reports/{id}/publish는 호출하지 않아도 됩니다.
• 수동 검토: 사람이 검토한 뒤 공개합니다. 이때만 POST /reports/{id}/publish가 필요합니다. 이 호출도 템플릿의 성공 개수 조건을 충족하기 전에는 422로 거절됩니다.

공유 링크 관리

생성 응답의 share_url은 바로 보관하세요. report 본문의 links.share에는 현재 활성 링크만 나옵니다. 만료·회수 상태의 기준은 GET /reports/{id}/share이며 share_url·expires_at· revoked_at을 반환합니다. 재활성화·링크 회전·만료 설정은 POST /reports/{id}/share에 JSON 본문 { "expires_in": 86400, "regenerate": true }로 요청하고, DELETE /reports/{id}/share는 링크만 회수합니다. 링크만 회수해도 리포트 자체의 publication_status는 바뀌지 않으며, GET /reports/{id}의 links.share만 null이 됩니다.

소셜 공유 미리보기 (OG 카드)

share_url(/r/{token})을 카카오톡·문자·슬랙 등에 붙여넣으면 차량 맞춤형 미리보기 카드가 자동으로 함께 표시됩니다. 별도 설정은 필요 없습니다.

• 자동 생성: 카드 이미지는 리포트가 공개(publish)되는 시점에 미리 생성·저장되므로, 링크를 붙여넣는 즉시 미리보기가 뜹니다(생성 지연이나 빈 이미지가 없습니다). CRM 등으로 링크를 자동 발송해도 동일합니다.
• 구성: 차량 번호 + AI 요약 문구 + 가장 심각한 타이어의 트레드 사진(홈 깊이 mm·등급 색 오버레이).
• 자동 갱신: 이후 마모값이 수정되거나 재분석되어 결과가 달라지면 카드도 자동으로 다시 생성됩니다.

같은 링크라도 리포트 상태에 따라 이렇게 다르게 보입니다.

정상 리포트 — 초록 정상 배지, "양호" 요약:

교체가 필요한 리포트 — 빨강 즉시 교체 권장 배지, 교체 안내 요약:

다음 단계