오류 응답#

유효성 검사 오류는 다음 형식을 사용할 수 있습니다.

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

message의 텍스트는 달라질 수 있습니다. 프로그램 로직에는 HTTP 상태 코드와 문서화된 응답 필드를 사용하세요.

재시도 및 복구 안내#

• 작업이 pending 또는 running인 동안 2~5초마다 폴링하세요.
• 429, 500, 502 및 503 응답에는 지터를 포함한 지수 백오프를 사용하고 최대 재시도 횟수를 설정하세요.
• 요청 또는 인증 정보를 수정하지 않은 채 400, 401 또는 403 응답을 자동 재시도하지 마세요.
• 409 후에는 활성 작업이 completed 또는 failed 상태에 도달할 때까지 기다리세요.
• 응답을 받기 전에 제출이 시간 초과되면 배치를 다시 제출하기 전에 상태 엔드포인트를 조회하세요.
• 가져오기는 생성 또는 수정 방식이므로 동일한 SKU로 같은 상품을 재시도해도 안전합니다.
• 항목별 실패가 있는 완료 작업 후에는 실패한 상품만 포함한 새 배치를 제출하세요.
• 작업 수준 실패 후에도 successCount에 집계된 상품은 이미 수정되었을 수 있습니다. 동일한 SKU로 원래 배치를 다시 제출해도 안전합니다.
• 요청이 503을 반환해도 삭제가 이미 적용되었을 수 있습니다. 동일한 삭제 요청은 안전하게 재시도할 수 있습니다.

상태 엔드포인트는 영구적인 가져오기 이력이 아니라 활성 또는 가장 최근 작업 추적용입니다. 대사 및 지원을 위해 제출한 배치, jobId, 상태 응답 및 최종 결과를 자체 시스템에 보관하세요.

운영 체크리스트#

• Client Secret을 비밀 정보 관리자 또는 보호된 서버 환경에 보관하세요.
• 각 상품에 안정적이고 고유한 SKU를 사용하세요.
• 요청당 상품은 500개 이하로 보내세요.
• 이미지 URL이 공개적으로 접근 가능하고 처리 중에도 계속 사용 가능한지 확인하세요.
• 이미지 전처리가 필요하고 이미지당 1크레딧의 처리 비용을 수락하는 경우에만 processImages: true를 명시적으로 설정하세요. 그 외에는 생략하거나 false로 설정하세요.
• 바닥재 이미지 분할은 processImages와 processFloorImages를 모두 true로 설정하여 활성화하세요.
• 각 상품에 name, imageUrl, productUrl, width, height 및 지원되는 productType을 제공하세요.
• status를 제공하면 active, inactive, out_of_stock 또는 invalid로 설정하세요.
• 지원 단위를 포함한 양수로 치수를 보내거나 단위를 생략하여 인치를 사용하세요. 저장 값은 인치로 정규화됩니다.
• 반환된 jobId를 보관하고 이후 상태 응답과 비교하세요.
• completed이면서 failedCount > 0이면 부분 성공으로 처리하세요.
• 제한 없는 카탈로그를 요청하지 말고 상품 목록을 페이지 단위로 순회하세요.
• 삭제 작업에는 productId 또는 sku 중 정확히 하나만 제공하세요.
• 지수 백오프와 지터를 사용하여 횟수가 제한된 재시도를 구현하세요.

인증 정보, 초기 설정 값, 상품 유형 매핑 또는 지속되는 연동 문제는 Ideal House 연동 담당자에게 문의하세요.