주문·상품 번호
주문번호·상품주문번호·클레임번호·상품번호·조합 번호의 형식과 조회·표기 방법
모든 주문·상품에는 API 식별자(orderId·productId 등) 외에 숫자 번호가 붙습니다. 숫자 번호는 고객 응대(전화·ARS)와 화면 표기에 씁니다.
API 경로의 식별자는 계속 orderId·productId입니다. 번호는 서버가 만들고 만든 뒤에는 바뀌지 않습니다.
번호 형식
| 번호 | 필드 | 형식 | 예 |
|---|---|---|---|
| 주문번호 | orderNo | 주문일(한국 시간) YYMMDD + 숫자 8자리, 14자리 | 26100284731592 |
| 상품주문번호 | items[].orderItemNo | 주문번호 + 주문 안 순번 2자리(01부터) | 2610028473159201 |
| 클레임번호 | claimNo | C + 접수일(한국 시간) YYMMDD + 숫자 8자리 | C26100591027384 |
| 상품번호 | productNo | 상점별 1부터 증가하는 숫자 | 482 |
| 조합 번호 | variants[].variantNo | 상품번호 + - + 조합 순번 2자리 | 482-03 |
- 주문번호·클레임번호의 뒷자리는 무작위 숫자입니다. 번호로 주문 수를 짐작할 수 없습니다.
- 상품번호와 조합 번호는 상점 안에서 유일합니다. 다른 상점과는 같은 번호가 있을 수 있습니다. 상품을 지워도 그 번호를 다시 쓰지 않습니다.
- 순번 2자리는 최소 자릿수입니다. 주문 줄이나 조합이 100개를 넘으면 3자리가 됩니다.
- 조합 번호는 시스템이 매기는 SKU입니다. 조합을 지워도 그 순번을 다시 쓰지 않습니다. 셀러가 입력하는
sku·sellerCode와 별개입니다. - 날짜 부분은 서버 위치와 관계없이 한국 시간 기준입니다. 한국 시간 자정이 지나면 다음 날짜로 바뀝니다.
- 번호 체계를 도입하기 전에 만든 주문·상품에도 번호가 채워져 있습니다. 주문번호의 날짜는 주문 시각 기준입니다.
응답 필드
| API | 필드 |
|---|---|
관리 API 주문 목록·상세 GET /v1/orders·GET /v1/orders/{orderId} | orderNo, items[].orderItemNo |
관리 API 주문상품 변경분 GET /v1/order-items | orderItemNo |
관리 API 클레임 GET /v1/claims·GET /v1/claims/{claimId} | claimNo |
관리 API 상품 GET /v1/products·GET /v1/products/{productId} | productNo, variants[].variantNo |
관리 API 결제 내역 GET /v1/payments·GET /v1/payments/{paymentId} | pgOrderId, attempts[].pgOrderId |
| 스토어프론트 내 주문·비회원 주문 조회 | orderNo, items[].orderItemNo |
| 스토어프론트 클레임 접수·내 클레임 | claimNo |
| 스토어프론트 상품 목록·상세 | productNo, 상세 variants[].variantNo |
| 스토어프론트 장바구니 | items[].productNo |
웹훅 ORDER.* | data.orderNo |
웹훅 CLAIM.* | data.claimNo |
SDK는 옛 응답에 필드가 없으면 null로 읽습니다.
번호로 찾기
- 관리 API
GET /v1/orders?orderNo=26100284731592— 주문 기간(orderedFrom) 없이 그 주문만 찾습니다. 하이픈을 넣어도 됩니다(2610-0284-7315-92). 형식이 아니면400 INVALID_PARAMETER입니다.keyword에 주문번호를 넣어도 찾습니다(기간 안). - 관리 API
GET /v1/products?productNo=482— 이 상점의 그 번호 상품만 찾습니다. 숫자가 아니면400 INVALID_PARAMETER입니다. - 스토어프론트
GET /products/{productId}— 경로에 숫자 상품번호를 넣어도 됩니다. 상점 코드로 정해진 상점 안에서 찾습니다. 상품 주소를/products/482처럼 만드십시오. 상품 리뷰GET /products/{productId}/reviews와 상품 문의 목록GET /products/{productId}/inquiries도 상품번호를 받습니다. 장바구니 담기·주문서 같은 요청에는 계속productId를 보냅니다. - 스토어프론트 비회원 주문 조회
POST /guest/orders/{orderId}— 경로에 주문번호를 넣어도 됩니다. 주문 id와 주문번호의 시도 횟수는 함께 셉니다.
화면 표기
formatOrderNo(@sayren/store-sdk·@sayren/storefront-sdk)는 숫자를 4자리씩 하이픈으로 나눕니다. 숫자가 아닌 값(클레임번호)은 그대로 돌려줍니다.
import { formatOrderNo } from "@sayren/storefront-sdk";
formatOrderNo("26100284731592"); // "2610-0284-7315-92"
formatOrderNo("2610028473159201"); // "2610-0284-7315-9201"표기는 화면용입니다. API에는 원래 값을 보내십시오.
상품 주소
기본 스토어프론트 템플릿의 상품 주소는 /products/{productNo}입니다. 예전 주소(/products/prod_…)로 들어오면 상품번호 주소로 영구 이동(301)합니다.
장바구니 응답의 items[].productNo로 장바구니에서도 같은 주소를 만듭니다.
PG 주문번호
토스페이먼츠·포트원 관리자 화면의 주문번호(토스페이먼츠 orderId, 포트원 paymentId)는 {주문번호}-{결제 시도 순번 2자리}입니다(예: 26100284731592-01).
같은 주문을 다른 결제수단으로 다시 시도하면 순번이 올라갑니다. 결제 내역 API의 pgOrderId가 이 값입니다.
번호 체계 이전의 결제는 PG 주문번호가 결제 시도 id(att_…)이고 pgOrderId도 그 값입니다. 구매자 화면에는 PG 주문번호를 보이지 않습니다.