시작하기

ATRACE Report API로 첫 호출까지 안내합니다.

0. 키 발급/온보딩

API Key는 셀프서비스 콘솔에서 직접 발급합니다. 조직 관리자가 콘솔에 로그인해 프로젝트(test 또는 live 모드)를 만들고, 그 프로젝트 안에서 API Key를 발급하면 됩니다. 전체 키 값은 발급 시 한 번만 표시되니 안전한 곳에 저장하세요. 더 쓰지 않는 키는 콘솔에서 폐기(revoke)할 수 있습니다. 테스트 프로젝트는 조직당 1개(무료)이고, 라이브 프로젝트는 필요한 만큼 만들 수 있습니다. 발급받은 키로 아래 인증 절차를 그대로 따르면 됩니다.

1. 인증

모든 요청에 발급받은 API Key를 Authorization: Bearer <API Key> 형태로 넣습니다. 발급받은 키를 그대로 보내면 됩니다.

Authorization: Bearer atr_test_xxxxxxxxxxxxxxxxxxxx

키는 프로젝트 단위로 발급됩니다. 프로젝트는 조직에 속하며, 데이터는 프로젝트별로 격리됩니다(한 키는 자신의 프로젝트 데이터에만 접근).
키에는 권한 범위(scope)가 있습니다. 대부분의 파트너는 report:*를 받습니다.
키는 클라이언트(브라우저·모바일앱)에 노출하지 마세요. 서버 간 통신에만 사용합니다.

2. 호스트와 모드

호스트는 하나이고, API 키가 모드를 결정합니다(별도의 샌드박스 호스트는 없습니다).

모드	키 접두사	개수	용도
테스트	`atr_test_…`	조직당 1개	무료 연동 시험 (실데이터 아님)
라이브	`atr_live_…`	필요한 만큼	실서비스

ATRACE Report API: https://app.atrace.ai/api/v1

키는 프로젝트 단위로 발급됩니다. 개발은 무료 테스트 프로젝트 키로 시작하고, 같은 코드에서 키만 라이브로 바꾸면 실서비스로 전환됩니다(호스트 변경 없음). 라이브 프로젝트는 리전·플릿 등 필요에 따라 여러 개를 둘 수 있습니다.

3. 첫 호출 — 리포트 생성

바로 실행해 보고 싶다면

미리 준비된 샘플 이미지로 복사–실행만으로 동작하는 예제가 필요하면 퀵스타트로 가세요. 고객 URL 모드 한 번의 호출과 Pre-Signed 업로드를 대신 해 주는 bash 스크립트를 모두 제공합니다.

가장 단순한 시작은 고객 URL 모드입니다(이미 이미지 URL을 가지고 있을 때). 요청에 이미지를 함께 보내면 분석이 시작됩니다. URL은 HTTPS 공개 URL이어야 하며 자격 증명을 포함할 수 없습니다. 리디렉션은 최대 3회까지 허용되고 각 대상 URL을 다시 검증합니다. 20MB 이하의 성공 이미지 응답이 15초 안에 반환되어야 합니다. plate_number는 선택 필드입니다. 신차·번호판 미장착·고객사 자체 QR 사용 등으로 번호판이 없으면 생략할 수 있습니다. 같은 차량의 리포트를 묶고 싶다면 external_vehicle_id(선택)에 파트너 측 차량 ID를 넣으세요. 번호판은 바뀌거나 다른 차량으로 재사용될 수 있어, 차량 단위 관리에는 이 필드를 권장합니다. template은 촬영 구성을 정합니다(템플릿 설명 참고).

curl -X POST https://app.atrace.ai/api/v1/reports \
  -H "Authorization: Bearer $ATRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partner-INSP-0001" \
  -d '{
    "plate_number": "12가3456",
    "external_inspection_id": "partner-INSP-0001",
    "external_vehicle_id": "partner-VEH-0001",
    "template": "tire_4t_2s",
    "content_profile": { "key": "speedmate-ko", "version": "1.0", "locale": "ko-KR" },
    "callback_url": "https://partner.example.com/atrace/webhook",
    "images": [
      { "module_type": "tire", "slot": { "position": "front_left", "image_type": "tread" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/tread-a-8mm.jpg", "client_asset_id": "partner-FL-tread" } },
      { "module_type": "tire", "slot": { "position": "front_right", "image_type": "tread" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/tread-a-6mm.jpg" } },
      { "module_type": "tire", "slot": { "position": "rear_left", "image_type": "tread" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/tread-b-4mm.jpg" } },
      { "module_type": "tire", "slot": { "position": "rear_right", "image_type": "tread" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/tread-c-2mm.jpg" } },
      { "module_type": "tire", "slot": { "position": "front_left", "image_type": "sidewall" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/sidewall-205-55R16.jpg" } },
      { "module_type": "tire", "slot": { "position": "rear_right", "image_type": "sidewall" },
        "source": { "url": "https://docs.atrace.ai/samples/tire/sidewall-205-65R15.jpg" } }
    ]
  }'

응답:

{
  "report_id": "123e4567-e89b-42d3-a456-426614174000",
  "status": "processing",
  "share_url": "https://app.atrace.ai/r/sh_abcdef"
}

share_url은 생성 응답에 이미 포함됩니다. 바로 저장해 두면 되고, 완료를 기다렸다가 다시 조회할 필요가 없습니다.

이미지를 호스팅할 곳이 없다면 Pre-Signed 모드를 씁니다. images를 생략하면 업로드용 URL을 돌려줍니다. 이미지 수집에서 다룹니다.

4. 결과 받기

두 가지 방법이 있습니다.

Polling (권장): GET /reports/{report_id}로 상태를 확인합니다. 신뢰 가능한 완료 확인은 이 폴링으로 하세요.
Webhook: 완료 시 report.completed 이벤트가 callback_url로 전송됩니다. 이벤트 알림용입니다. Webhooks.

GET /reports/{report_id}는 report.v1 객관 데이터 계약을 반환합니다. 분석 완료는 analysis_status == "complete", ATRACE 공유 화면의 공개 완료는 publication_status == "published"로 각각 판단합니다. 두 상태는 서로 다른 축입니다. template.requirements[].minimum_success_count를 충족하지 못하면 POST /reports/{id}/publish도 거절되므로, 부족한 슬롯을 재분석하거나 새 원본으로 교체한 뒤 다시 확인하세요.

curl https://app.atrace.ai/api/v1/reports/123e4567-e89b-42d3-a456-426614174000 \
  -H "Authorization: Bearer $ATRACE_API_KEY"

자체 화면을 렌더링하려면 report 응답의 links.content를 이어서 호출합니다.

curl "https://app.atrace.ai/api/v1/reports/123e4567-e89b-42d3-a456-426614174000/content" \
  -H "Authorization: Bearer $ATRACE_API_KEY"

콘텐츠가 준비되면 report-content.v1의 문구·섹션·시각화 수치가 반환됩니다. 준비 중인 202 응답은 Retry-After 뒤에 다시 조회하세요. 상세 필드와 JSON 예시는 리포트 데이터와 콘텐츠를 보세요.

5. 멱등성

POST /reports에는 Idempotency-Key 헤더나 external_inspection_id를 사용하세요. 같은 키로 재시도하면 새 리포트를 또 만들지 않고 같은 결과를 돌려줍니다. 네트워크 재시도가 안전해집니다. 두 값은 멱등성 범위가 다릅니다. Idempotency-Key는 요청 단위 중복 제거, external_inspection_id는 검사 단위 식별이므로 둘을 함께 써도 됩니다.

리포트가 변경 가능한 동안 같은 Idempotency-Key와 같은 본문을 재전송하면 최초 저장 응답을 그대로 반환합니다. 폐기 후에는 409 report_discarded입니다. 저장 응답의 Pre-Signed URL이 만료됐다면 POST /reports/{id}/upload-targets로 필요한 슬롯만 새로 발급받으세요. 동일 요청의 최초 생성 처리가 아직 끝나지 않았다면 409 idempotency_in_progress와 retryable: true를 반환하므로 같은 키·본문으로 잠시 후 다시 시도하세요.

0. 키 발급/온보딩

1. 인증

2. 호스트와 모드

3. 첫 호출 — 리포트 생성

4. 결과 받기

5. 멱등성

다음 단계

퀵스타트 — 예제 리포트 만들기

리포트 생성 흐름

리포트 데이터와 콘텐츠

이미지 수집

에러 처리

On this page