Skip to content

shipping

Jump to bottom
LeeSangHoon edited this page Apr 24, 2023 · 2 revisions

API 목록

API Description
PUT /api/shipping/address/:addressId 배송지 수정
DELETE /api/shipping/address/:addressId 배송지 삭제
PATCH /api/shipping/address/:addressId/prime 기본 배송지 변경
GET /api/shipping/request 배송 요청 목록 조회
POST /api/shipping/request 배송 요청 등록
GET /api/shipping/request/:requestId 배송 요청 상세 조회
DELETE /api/shipping/request/:requestId 배송 요청 삭제
POST /api/shipping/request/:requestId/payment 결제 검증
POST /api/shipping/request/:requestId/refund 결제 환불
POST /api/shipping/request/:requestId/approve 발송 완료 처리

배송지 수정

PUT /api/shipping/address/:addressId

  • 배송지 정보를 수정합니다.

Request Parameters

Parameter Target Type Description
addressId param number 배송지 ID
address body Object 수정할 주소 정보
address.name body string 배송지 이름
address.recipient body string 수령인 이름
address.contact body string 연락처
address.postcode body string 우편 번호
address.address body string 주소
address.addressDetail body string 상세 주소
address.requirement body string 배송 요청사항
address.prime body number 기본 배송지 여부

Response

{
    "_status": 200,
    "message": "배송지 정보를 수정했어요."
}
{
    "_status": 404,
    "message": "수정하려는 배송지의 데이터가 서버에 존재하지 않아요."
}

배송지 삭제

DELETE /api/shipping/address/:addressId

  • 배송지를 삭제합니다.

Request Parameters

Parameter Target Type Description
addressId param number 배송지 ID

Response

{
    "_status": 200,
    "message": "배송지 삭제했어요."
}
{
    "_status": 404,
    "message": "삭제하려는 배송지의 데이터가 서버에 존재하지 않아요."
}

기본 배송지 변경

PATCH /api/shipping/address/:addressId/prime

  • 자신의 기본 배송지를 변경합니다.

Request Parameters

Parameter Target Type Description
addressId param number 배송지 ID

Response

{
    "_status": 200,
    "message": "기본 배송지를 변경했어요."
}
{
    "_status": 404,
    "message": "수정하려는 배송지의 데이터가 서버에 존재하지 않아요."
}

배송 요청 목록 조회

GET /api/shipping/request

  • 해당 검색 필터에 해당하는 배송 요청 목록을 조회합니다.

Request Parameters

Parameter Target Type Description
pageParam query number 페이지 번호
filter query Object 검색 필터
filter.userNames query string[] 조회할 요청자 아이디 목록
filter.shippingState query "all" or "waiting" or "shipped" 조회할 요청의 배송 상태
filter.paymentState query "all" or "waiting" or "paid" or "forgeried" 조회할 요청의 결제 상태

Response

{
    "_status": 200,
    "message": "배송 요청 목록을 조회했어요.",
    "shippings": [
        {
            "requestId": 6,
            "state": "waiting",
            "writtenTime": "2023-04-21T17:49:16.000Z",
            "address": {
                "recipient": "김영희",
                "contact": "010-3333-3333",
                "postcode": "11611",
                "address": "경기 의정부시 가금로 29 (지승메디컬프라자)",
                "addressDetail": "303호",
                "requirement": "부재 시 택배함에 놓아주세요."
            },
            "payment": {
                "state": "waiting"
            },
            "author": {
                "userId": 5,
                "username": "wannav",
                "nickname": "와나비",
                "imageName": "5_1681972320438.jpg"
            },
            "voucher": {
                "amount": 2,
                "represent": {
                    "name": "BUTTER",
                    "imageName": "149_1681838478041.png"
                }
            }
        }
    ],
    "paging": {
        "pageParam": 0,
        "hasNextPage": false
    }
}

배송 요청 등록

POST /api/shipping/request

  • 자신의 실물 포토카드 수령 의사를 관리자가 확인할 수 있게끔 배송 요청을 등록합니다.

Request Parameters

Parameter Target Type Description
voucherIds body number[] 배송 받으려는 소유권 ID 목록
address body Object 수정할 주소 정보
address.name body string 배송지 이름
address.recipient body string 수령인 이름
address.contact body string 연락처
address.postcode body string 우편 번호
address.address body string 주소
address.addressDetail body string 상세 주소
address.requirement body string 배송 요청사항
address.prime body number 기본 배송지 여부

Response

{
    "_status": 200,
    "message": "배송 요청글을 작성했어요. 이어서 배송비를 결제해주세요.",
    "requestId": 5
}
{
    "_status": 403,
    "message": "당신의 소유권이 아니에요."
}
{
    "_status": 403,
    "message": "배송 요청하려는 소유권 중에 이용가능 상태가 아닌 소유권이 있어요."
}
{
    "_status": 404,
    "message": "사용하려는 소유권을 찾지 못했어요."
}

배송 요청 상세 조회

GET /api/shipping/request/:requestId

  • 배송 요청의 상세 정보를 조회합니다.

Request Parameters

Parameter Target Type Description
requestId param number 배송 요청 ID

Response

{
    "_status": 200,
    "message": "배송 요청 상세 정보를 조회했어요.",
    "shipping": {
        "requestId": 6,
        "state": "waiting",
        "writtenTime": "2023-04-21T17:49:16.000Z",
        "address": {
            "recipient": "김영희",
            "contact": "010-3333-3333",
            "postcode": "11611",
            "address": "경기 의정부시 가금로 29 (지승메디컬프라자)",
            "addressDetail": "303호",
            "requirement": "부재 시 택배함에 놓아주세요."
        },
        "payment": {
            "paymentId": 6,
            "merchantUID": "6eeedbf9b1ac5172b408e933f422c353cdbf9839",
            "impUID": null,
            "amount": 100,
            "state": "waiting"
        },
        "author": {
            "userId": 5,
            "username": "wannav",
            "nickname": "와나비",
            "imageName": "5_1681972320438.jpg"
        }
    },
    "vouchers": [
        {
            "voucherId": 9,
            "state": "shipping",
            "createdTime": "2023-04-19T14:51:11.000Z",
            "photo": {
                "photocardId": 149,
                "name": "BUTTER",
                "imageName": "149_1681838478041.png",
                "groupData": {
                    "groupId": 1,
                    "name": "BTS"
                },
                "memberData": {
                    "memberId": 6,
                    "name": "V"
                }
            },
            "owner": {
                "userId": 5,
                "username": "wannav",
                "nickname": "와나비",
                "imageName": "5_1681972320438.jpg"
            }
        },
        {
            "voucherId": 10,
            "state": "shipping",
            "createdTime": "2023-04-19T14:51:11.000Z",
            "photo": {
                "photocardId": 151,
                "name": "LOVE YOURSELF_ ANSWER",
                "imageName": "151_1681838478042.png",
                "groupData": {
                    "groupId": 1,
                    "name": "BTS"
                },
                "memberData": {
                    "memberId": 6,
                    "name": "V"
                }
            },
            "owner": {
                "userId": 5,
                "username": "wannav",
                "nickname": "와나비",
                "imageName": "5_1681972320438.jpg"
            }
        }
    ]
}
{
    "_status": 404,
    "message": "해당 배송 요청을 찾지 못했어요."
}

배송 요청 삭제

DELETE /api/shipping/request/:requestId

  • 배송 요청을 삭제합니다.

Request Parameters

Parameter Target Type Description
requestId param number 배송 요청 ID

Response

{
    "_status": 200,
    "message": "배송 요청을 취소했어요.",
    "voucherIds": [5, 13]
}
{
    "_status": 400,
    "message": "아직 미결제 상태인 경우에만 삭제할 수 있어요."
}
{
    "_status": 400,
    "message": "관리자가 이미 배송처리한 경우에는 삭제할 수 없어요."
}
{
    "_status": 404,
    "message": "해당 배송 요청을 찾지 못했어요."
}

결제 검증

POST /api/shipping/request/:requestId/payment

  • 리액트 앱에서 아임포트 모듈을 통해 결제한 정보가 위변조 없이 정확하게 되었는지를 확인하고, 결제 상태를 데이터베이스에 업데이트 합니다.

Request Parameters

Parameter Target Type Description
requestId param number 배송 요청 ID
impUID body string 아임포트 결제 고유 ID

Response

{
    "_status": 200,
    "message": "배송비가 결제되었어요."
}
{
    "_status": 200,
    "message": "위조된 결과가 확인되었어요."
}
{
    "_status": 404,
    "message": "해당 배송 요청을 찾지 못했어요."
}
{
    "_status": 404,
    "message": "포트원 결제 정보를 찾지 못했어요."
}

결제 환불

POST /api/shipping/request/:requestId/refund

  • 배송 요청하기 위해 결제했던 배송비를 취소하고 환불 처리합니다.

Request Parameters

Parameter Target Type Description
requestId param number 배송 요청 ID

Response

{
    "_status": 200,
    "message": "결제 금액이 환불되었어요."
}
{
    "_status": 400,
    "message": "${아임포트 결제 모듈로부터 받은 처리 오류 메시지}"
}
{
    "_status": 400,
    "message": "관리자가 이미 배송 처리한 경우에는 취소할 수 없어요."
}
{
    "_status": 404,
    "message": "해당 배송 요청을 찾지 못했어요."
}
{
    "_status": 404,
    "message": "해당 결제 정보를 찾지 못했어요."
}

발송 완료 처리

POST /api/shipping/request/:requestId/approve

  • 관리자가 배송 요청에 대해서 적절하게 발송하고, 그에 따라 배송 요청의 상태를 발송 완료로 변경합니다.

Request Parameters

Parameter Target Type Description
requestId param number 배송 요청 ID

Response

{
    "_status": 200,
    "message": "발송 완료 처리 되었어요."
}
{
    "_status": 400,
    "message": "이미 완료 처리된 요청이에요."
}
{
    "_status": 400,
    "message": "아직 결제되지 않은 배송 요청은 발송 완료할 수 없어요."
}
{
    "_status": 404,
    "message": "해당 배송 요청을 찾지 못했어요."
}
Clone this wiki locally