0 Fork 0

Files

T

HeuJung b16c5c38a5 fix(core,board,ecommerce,page,pay): 예외→응답 매핑 정비와 저장 배송지 승계 결함 수정

generic catch 가 4xx 를 돌려주면 인프라 장애가 입력 오류로 위장돼 장애 인지가
늦어지고, 이미 번역된 예외 메시지를 응답의 메시지 키 자리에 넘기면 키 해석에
실패해 원문이 그대로 화면에 나간다. 두 형태를 코어와 전 번들 확장에서 함께
정리하고, 판정기를 한 확장이 아닌 코어 모집단에 두어 확장 밖 동형 결함도
red 가 되게 했다 — 그 사각에 실제로 15건이 있었다.

주소록에서 해외 배송지를 고르면 국내 6필드만 옮겨 담아 해외 주소가 통째로
사라지던 결함도 함께 고쳤다. 저장은 200 으로 성공 처리돼 주문 상세를 다시
열기 전에는 드러나지 않았다.

2026-08-16 00:53:21 +09:00

4.3 KiB

Raw Blame History

에스크로 API 레퍼런스

소유: 플러그인 sirsoft-pay_nicepayments. 관리자 주문 상세의 에스크로 배송 등록 화면이 쓰는 JSON API 표면이다. 결제대행사 서버가 직접 호출하는 통보 경로(vbank.md)와는 인증·접근 제어가 다르다.

TL;DR (5초 요약)

1. 에스크로(EscrowYN=Y) 결제 건의 TID/상태를 조회하고, 배송 정보를 나이스페이먼츠에 등록한다
2. 두 경로 모두 Bearer 토큰 + admin 미들웨어 + 이커머스 주문 권한이 필요하다
3. 배송 등록이 성공하면 구매자에게 구매확정 안내가 결제대행사를 통해 자동 발송된다
4. 결제대행사 호출 실패는 502 로 구분된다 — 응답 본문에 예외 원문을 싣지 않는다
5. 대상 TID 를 찾지 못하면 422 (등록 가능한 에스크로 결제가 아님)

공통 규약

항목	값
인증	`Authorization: Bearer {token}` (`auth:sanctum` + `admin`)
응답 봉투	코어 `ResponseHelper` 표준 (`success` / `message` / `data`)
권한	조회 `sirsoft-ecommerce.orders.read` · 등록 `sirsoft-ecommerce.orders.update`

에스크로 결제 목록 조회

항목	값
라우트명	`api.plugins.sirsoft-pay_nicepayments.admin.orders.escrow-payments`
메서드/URI	`GET /api/plugins/sirsoft-pay_nicepayments/admin/orders/{orderNumber}/escrow-payments`
권한	`sirsoft-ecommerce.orders.read`

경로 파라미터

이름	타입	필수	설명
`orderNumber`	string	예	주문번호

응답 필드 (data.escrow_payments[])

필드	타입	설명
`id`	integer	결제 레코드 ID
`transaction_id`	string	나이스페이먼츠 TID
`payment_method`	string	결제수단 (가상계좌·카드 등)
`payment_status`	string	결제 상태

해당 주문에 에스크로 결제가 없으면 escrow_payments 는 빈 배열이다.

응답 예시

{
  "success": true,
  "message": "요청이 성공했습니다.",
  "data": {
    "escrow_payments": [
      {
        "id": 812,
        "transaction_id": "nicepay20260814012345",
        "payment_method": "vbank",
        "payment_status": "paid"
      }
    ]
  }
}

에스크로 배송 등록

항목	값
라우트명	`api.plugins.sirsoft-pay_nicepayments.admin.escrow.register-delivery`
메서드/URI	`POST /api/plugins/sirsoft-pay_nicepayments/admin/escrow/register-delivery`
권한	`sirsoft-ecommerce.orders.update`

요청 파라미터

이름	타입	필수	제약	설명
`tid`	string	예	—	대상 에스크로 결제의 나이스페이먼츠 TID
`delivery_name`	string	예	최대 100자	택배사명
`tracking_number`	string	예	최대 100자	송장번호
`buyer_address`	string	예	최대 200자	구매자 배송지
`register_name`	string	예	최대 50자	등록자명

동작

나이스페이먼츠에 배송 정보를 등록한다. 등록이 완료되면 구매자에게 구매확정 안내가 결제대행사를 통해 자동 발송된다.