본문으로 건너뛰기

Changelog

규격서 버전별 변경 이력입니다. 각 버전의 전체 규격은 우측 상단 버전 드롭다운에서 선택합니다.

v0.305 — 2026-09-20​

19.3. bmrmember-order POST — 원스톱 배송 주문별 목적지 지정 (BMR-869)

  • isOneStop: true 주문은 리터니즈 검품센터를 거치지 않고 목적지로 바로 배송. 목적지는 요청의 dropAddress 등 drop* 입력값 → 브랜드에 등록된 반품지(대표 반품지 → 물류창고 → 첫 번째) → 리터니즈 검품센터 순으로 접수 시점에 결정되어 저장됨
  • drop* 필드(dropName/dropPhoneNumber/dropZipcode/dropAddress/dropAddressDetail)는 isOneStop: true일 때만 적용. isOneStop: false(기본값) 주문은 입력값과 관계없이 검품센터로 배송
  • 우체국(계약소포) 수거 주문의 목적지는 리터니즈 스태프룸에서 우체국 공급지로 등록된 브랜드 반품지여야 접수 가능(미등록 시 수거 접수 보류)
  • 19.1. bmrmember-order GET 응답 isOneStop 비고에 목적지 회신 필드(drop*) 설명 추가

19.1. bmrmember-order GET — 반품 아이템[returnItem] 응답 필드 표 코드값 정정 및 누락 필드 추가

  • 코드값 정정 (기존 표가 구버전 기준이었음)
    • statuses: inspecting(검품중) 추가 → 총 16개
    • inspectProduct: omitted(제품 없음), wrong_product(타사 제품) 추가 → 총 6개
    • inspectPackage: 값 의미 정정 — correct 미개봉 / incorrect 포장 개봉 / reused 포장 재사용(신규) / check 클라이언트 확인요청. unknown은 과거 데이터 표시용(신규 입력 없음)
    • reasonItemDamaged: 배열로 회신. 현행 14개(missed, parts, fastenerDamaged, foundation, etcFoundation, winkles, fabricDamaged, sewing, hole, odor, laundary, leatherScratch, sizeWrong, colorWrong) + 과거 데이터용 5개(opened, dyed, strechedout, furwinkls, etc). dirty는 존재하지 않는 코드로 삭제
    • statusInspect: reused_usable, reused_unusable 추가 → 총 7개
    • confirm: waitDelivery(출고대기) 추가 → 총 6개
    • quantityOrder: 데이터 타입 String → Integer 정정
  • 누락 필드 추가 (응답에 포함되나 표에 없던 필드)
    • customerReferenceKey: 아이템 단위 고객사 참조키 (String, max 100, 미기록 시 빈 문자열, quantityOrder > 1 분할 시 각 아이템에 동일 값 복사, BMR-865)
    • productPrice, requestMemo, isBundle: 접수 시 전달한 값 회신
    • ecommerce: 아이템이 속한 주문의 브랜드 정보(주문 ecommerce와 동일, parentEcommerceId 포함)
    • statusInspectRequest: 검품 전달사항 확인 상태 (confirm / unknown / 빈 문자열)
    • lastInspectAt, outAt, shippingAllowedAt: 최종 검품일시 / 출고 완료일시 / 출고 가능 시각 (DateTime, 없으면 null)
    • product, categories, inspectionGuideCategory: 연동 제품 정보 / 카테고리 목록 / 카테고리 검품 가이드
  • 미제공 필드 표기 (표에는 있으나 응답에 없는 필드)
    • plan, measureWidth, measureDepth, measureHeight, measureWeight, isWeightInspected는 현재 bmrmember-order GET 응답에 포함되지 않으므로 기초코드 등록 불필요
  • 호출 결과 예시 JSON 정정
    • returnItems 항목에 customerReferenceKey 추가
    • confirm 예시값 confirm → wait 정정 (confirm은 유효하지 않은 값)
    • inspectedAt → lastInspectAt 정정 (실제 응답 필드명)
  • 반품 브랜드 ID(ecommerceId) 전달 기준 명시
    • 주문(bmrmember-order) 단위로 ecommerceId 1개만 전달. returnItem 단위 브랜드 ID 입력 필드는 없음
    • GET 응답 returnItems[].ecommerce는 주문 브랜드를 그대로 회신 (상위 브랜드는 parentEcommerceId로 확인)
    • 한 주문에 여러 하위 브랜드 상품이 섞이면 전달한 대표 브랜드로 집계·정산되므로, 브랜드별 구분이 필요하면 브랜드 단위로 주문 분리 접수 권장

v0.304 — 2026-09-16​

19.1. bmrmember-order GET — 반품 아이템[returnItem] 포장 상태(inspectPackage) 값 추가 및 검품 상태(statusInspect) 값 추가 (BMR-866)

  • returnItems[].inspectPackage (검품 포장 상태, String, 읽기 전용, 리터니즈 검품원 입력)
    • correct: 미개봉 (개봉 검사 미진행, 내용물 정상으로 확정)
    • incorrect: 포장 개봉 (개봉 검사 후 포장 교체)
    • reused: 포장 재사용 (개봉 검사 후 기존 포장 재사용) — 신규
    • check: 클라이언트 확인요청 / 빈 문자열: 미입력
  • returnItems[].statusInspect (검품 상태, String, 읽기 전용, 포장/내용물 상태로 자동 산출)
    • normal: 미개봉 / usable: 포장 개봉·본품정상 / unusable: 포장 개봉·본품불량
    • reused_usable: 포장 재사용·본품정상 / reused_unusable: 포장 재사용·본품불량 — 신규
    • check: 클라이언트 확인 요청 / not_completed: 검품 미완료

19. 일반회원 주문(bmrmember-order) — 반품 아이템[returnItem] 단위 고객사 참조키 customerReferenceKey 추가 (BMR-865)

  • 주문 단위 customerReferenceKey와 별개로, 반품 아이템마다 임의의 참조 코드를 기록 (String, 선택값, max length=100, 미기록 시 빈 값)
  • 19.3. bmrmember-order POST 요청 파라미터 returnItems[].customerReferenceKey
  • 19.1. bmrmember-order GET 응답 returnItems[].customerReferenceKey — quantityOrder > 1인 경우 분할된 각 반품 아이템에 동일 값이 복사됨
  • 19.8. bmrmember-order/{bulkNumber}/reference-info PATCH 명세 추가
    • 주문 단위 참조 정보(customerReferenceKey / originOrderCreatedAt / originOrderNumber) 수정 API
    • 요청 파라미터 returnItems[] 추가 (itemCode 지정하여 아이템 단위 참조키 수정)
  • 19.1. bmrmember-order GET 조회 필터: itemCustomerReferenceKey(부분 일치) / itemCustomerReferenceKey_exact(정확 일치) 추가 — 해당 참조키를 가진 반품 아이템이 1개 이상 포함된 주문을 조회

19. 일반회원 주문(bmrmember-order) — 반품 아이템[returnItem] 사은품(부속품) 목록 추가

  • 사은품은 별도 반품 아이템이 아니라 반품 아이템의 부속품으로 관리. 반품 아이템당 N개 등록 가능
  • gifts (사은품 목록, List, 선택값): 19.3 POST 요청 파라미터 returnItems[].gifts 및 19.1 GET 응답
    • 각 항목: name(String, 필수, max length=500), productCode(String, 선택, max length=100)
    • quantityOrder > 1인 경우 분할된 각 반품 아이템에 동일 목록이 복사됨
    • GET 응답의 각 항목에는 id, returned(항목별 회수 여부, Boolean, 리터니즈 검품원 입력)가 추가됨
  • giftReturned (사은품 회수 여부, Boolean, 읽기 전용): gifts 집계값, 1개 이상 returned=true이면 true
  • 사은품 촬영 이미지: 별도 필드 없이 inspectImages(검품 이미지 리스트)에 포함 (본품·포장 사진과 구분 없음)

19. 일반회원 주문(bmrmember-order) — externalServiceExchangeReturn(외부 서비스 교환/반품, String) 응답 필드 추가

  • 19.1 / 19.2 응답 및 19.4 / 19.5 / 19.6 응답(results)에 포함
  • 값: exchange(교환) / return(반품) / 빈 문자열(미입력)
  • 연동 쇼핑몰(CAFE24, 메이크샵 등) 주문은 접수 시 쇼핑몰 주문 상태 기준으로 자동 설정. 19.3 POST 접수 주문은 요청 파라미터로 전달한 값 반환

19.1. bmrmember-order GET — 조회 조건 파라미터(Query String) 명세

  • page_size, ordering, customerReferenceKey/_exact, itemCustomerReferenceKey/_exact, originOrderNumber/_exact, customerNumber/_exact, bulkNumber/_exact, orderNumber/_exact, ecommerceId, statuses, itemCode/productCode/productName, confirm, pickupName, entryChannelName, 기간 필터, search

전 섹션 공통 — 인증 헤더 표기 정정

  • Authorization: Api-Key {APIKEY} → Api-Key: {APIKEY}. 헤더명은 Api-Key, 값은 발급받은 API KEY 원문. Authorization 헤더로 보내면 인증되지 않음

v0.303 — 2026-09-09​

1. 브랜드(ecommerce) — isUsePickupService 필드 추가

  • 수거 서비스 사용 여부, Boolean, 기본값 true. GET 응답 및 POST/PATCH 요청 파라미터
  • isUsePickupService=false 브랜드의 주문은 운송사 회수 자동 접수 대상에서 제외
  • 19.3. bmrmember-order POST: 픽업지 정보(pickupName, pickupAddress, pickupContact)를 필수 → 조건부 필수로 변경. isUsePickupService=false(수거 서비스 사용 안 함) 브랜드는 미입력 가능

19. 일반회원 주문(bmrmember-order) — 참조 정보 필드 추가

  • customerReferenceKey: 고객사 참조키 (String, max length=100)
  • originOrderCreatedAt: 원 주문 접수일 (DateTime)
  • originOrderNumber: 원 송장번호 (String, max length=50)

v0.302 — 2026-07-12​

  • 19.3. bmrmember-order POST: entryChannelName(주문 유입 채널명/판매 플랫폼) 접수 시 저장 지원
  • 19.3 POST / 응답: externalServiceExchangeReturn(외부 서비스 교환/반품 구분: exchange / return) 필드 추가

v0.301 — 2025-12-09​

v0.300 — 2025-11-25​

v0.299 — 2025-09-09​

v0.298 — 2025-07-14​

  • bmrmember-order에 entryChannelName(주문 접수 경로명) 필드 추가

v0.297 — 2025-06-25​

  • API에 대한 설명 상세 추가
  • 에러코드 추가: 19.3. bmrmember-order POST err_code — NO_PERMISSION_ECOMMERCE → E_COMMERCE_NOT_FOUND
  • returnItem의 productName(200자 → 500자), option(100자 → 500자) 최대 길이 변경

v0.296 이하​

v0.293 ~ v0.296 의 변경 이력은 사내 Notion "[리터놀] 리터니즈 API" 하위의 각 버전 페이지를 참조하세요.