본문으로 건너뛰기

19.3. bmrmember-order POST

팁

리터니즈에 반품 주문을 접수

POST[DOMAIN]/api/bmrmember-order/

Headers: Api-Key: {APIKEY}

호출 결과 코드

status	err_code	설명
`SUCCESS`		성공. `results`에 접수된 주문 정보(19.1 참조)
`FAIL`	`CUSTOMER_NUMBER_DUPLICATE`	브랜드 내에 동일 고객주문번호의 반품 주문[Order]가 이미 리터니즈에 접수되어 있음. `results`에 중복된 주문 정보 응답
`FAIL`	`E_COMMERCE_NOT_FOUND`	요청 시 입력한 브랜드 ID[ecommerceId]에 대한 권한이 없거나 등록된 브랜드가 아님. 해당 브랜드 담당자가 리터니즈 서비스 연동 페이지에서 연동 완료 필요 (https://returneeds.com/external)

요청 parameter (Body, form-data 또는 JSON)

파라미터 명	필수여부	데이터 타입	값	제한 사항 / 비고
`ecommerceId`	필수	String	반품 브랜드 ID	알파벳 3자리. 주문 단위로 1개만 전달 (반품 아이템 단위 브랜드 ID는 없음)
`customerNumber`	필수	String	고객주문번호	브랜드에서 고유(unique)한 값
`pickupName`	조건부 필수	String	픽업지 고객명	max length=50. 브랜드의 수거 서비스 사용 여부(isUsePickupService)가 `true`인 경우 필수, `false` 브랜드는 미입력 가능 (BMR-845)
`pickupAddress`	조건부 필수	String	픽업지 주소	min length=5, max length=100. 위와 동일 조건
`pickupAddressDetail`		String	픽업지 상세주소	max length=100, default=''
`pickupContact`	조건부 필수	String	픽업지 연락처	max length=50. 위와 동일 조건
`orderNumber`		String	송장번호	max length=50. 반품 수거 운송장 번호(미입력 시 리터니즈 수거 접수 시 채번)
`requestInspect`		String	검품 요청사항	max length=100, default=''
`pickupMemo`		String	픽업 메모	수거 운송장 배송메시지. max length=50, default=''
`dropoffMemo`		String	반품지 메모	max length=100, default=''
`returnItems`		Array	반품 아이템 리스트	항목 구조는 반품 아이템 (returnItem) 요청 파라미터 참조
`boxQuantity`		Integer	박스 수량	default=1
`boxTypeC`		String	고객입력 박스타입	`A` / `B` / `C` / `D1` / `D2` / `E` / `F` (박스 타입)
`isOneStop`		Boolean	원스톱 배송 여부	default=false. `true`면 리터니즈 검품센터를 거치지 않고 *목적지(아래 `drop` 필드)로 바로 배송*. 목적지 결정 순서: 요청의 `dropAddress` 입력값 → 브랜드에 등록된 반품지(대표 반품지 → 물류창고 → 첫 번째) → 리터니즈 검품센터. `false`면 `drop` 입력값과 관계없이 검품센터로 배송 (BMR-869)
`dropName`		String	목적지(반품지) 성명	max length=50. `isOneStop: true`일 때만 적용. 미입력 시 `{브랜드명}[리터니즈]`
`dropPhoneNumber`		String	목적지(반품지) 연락처	max length=50. `isOneStop: true`일 때만 적용
`dropZipcode`		String	목적지(반품지) 우편번호	max length=60. `isOneStop: true`일 때만 적용. 미입력 시 주소로 자동 조회
`dropAddress`		String	목적지(반품지) 주소	max length=200. `isOneStop: true`일 때만 적용
`dropAddressDetail`		String	목적지(반품지) 상세주소	max length=200. `isOneStop: true`일 때만 적용
`orderType`		String	주문 타입	`return`: 반품 (기본값, 반품주문) / `sale`: 판매 (판매자 상품 검품건, 구매주문)
`originBulkNumber`		String	원 주문번호	max length=50. 판매자 상품 검품건의 반품 주문인 경우 원 주문의 주문번호
`originReturnItemCodes`		Array	원주문 반품아이템 코드 리스트	`orderType: sale` 경우만 입력. 원주문(판매자 상품 검품, 구매주문)의 반품 아이템 중 반품할 아이템코드 리스트. 예: `["AAA0000000", "AAA0000001"]`
`entryChannelName`		String	주문 접수 경로명(판매 플랫폼)	max length=300
`externalServiceExchangeReturn`		String	외부 서비스 교환/반품	`exchange`: 교환 / `return`: 반품. default='' (미입력 시 빈 값)
`originOrderNumber`		String	원 송장번호	max length=50, default=''. 최초 상품 출고에 사용된 원 주문의 송장번호. 고객사가 API로 직접 기록. 반품 수거 송장번호(orderNumber)와는 별개의 참조값 (BMR-740)
`originOrderCreatedAt`		DateTime	원 주문 접수일	날짜(`YYYY-MM-DD`) 또는 ISO-8601 일시. 최초 상품 출고에 사용된 원 주문의 접수일. 입력 예시: `2026-09-09`, `2026-09-09T13:05:00+09:00`, `2026-09-09 13:05:00`. 시간 미입력(날짜만) 시 해당일 00:00:00(KST)로 저장 (BMR-845)
`customerReferenceKey`		String	고객사 참조키	max length=100, default=''. 고객사(브랜드 BO)가 자사 시스템 식별을 위해 기록하는 임의의 코드. 리터니즈는 값의 형식/중복을 검증하지 않음 (BMR-845)

반품 브랜드 ID 전달 기준

브랜드 ID(ecommerceId)는 주문 단위로 1개만 전달하며, returnItems[] 단위의 브랜드 ID 입력 필드는 없습니다.
GET 응답의 returnItems[].ecommerce는 주문의 브랜드를 그대로 회신합니다(상위 브랜드는 parentEcommerceId로 확인).
한 주문에 여러 하위 브랜드 상품이 섞이면 전달한 대표 브랜드로 집계·정산되므로, 브랜드별 구분이 필요하면 브랜드 단위로 주문을 분리 접수하세요.

호출 예시

{
    "pickupName": "TEST5",
    "pickupAddress": "부산광역시 성북구 대사관로8길 12132(성북동)",
    "pickupContact": "010-0000-0000",
    "ecommerceId": "AAA",
    "customerNumber": "1111112",
    "orderNumber": "4321",
    "boxQuantity": 5,
    "customerReferenceKey": "ETN-2026-000123",
    "originOrderNumber": "6001234567890",
    "originOrderCreatedAt": "2026-09-01T10:00:00+09:00",
    "externalServiceExchangeReturn": "return",
    "returnItems": [
        {
            "productName": "테스트",
            "option": "L",
            "productCode": "P-001",
            "quantityOrder": 2,
            "productPrice": 35000,
            "customerReferenceKey": "ETN-ITEM-0001",
            "gifts": [{"name": "쇼핑백"}, {"name": "샘플파우치", "productCode": "G-01"}]
        },
        {"productName": "테스트2", "productPrice": 100}
    ]
}

호출 결과 코드
요청 parameter (Body, form-data 또는 JSON)
호출 예시