sayren Docs
주문

주문 목록 조회

주문 시각 범위(최대 31일)로 주문 요약을 최신순으로 조회한다. 스코프 `order:r`. - `status`는 그 상태의 주문상품이 하나라도 있는 주문을 고른다. - `representativeStatus`는 첫 주문상품의 상태다. - `orderNo`(숫자 14자리 주문번호, 하이픈 허용)를 주면 기간 없이 그 주문만 찾는다. `keyword`도 주문번호를 받는다. - 테스트 결제(샌드박스 결제) 주문은 `testPayment: true`다. 실제로 돈이 오가지 않았으므로 상품을 발송하지 않도록 주의한다. `testPayment` 쿼리로 테스트 결제만(`true`)·실결제만(`false`) 볼 수 있다. - method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다(`payment.approvedMethod` — 매출 리포트·스토어프론트·환불 원장과 같은 값). 간편결제면 `payment.easyPayProvider`에 간편결제사가 함께 온다.

GET
/v1/orders

주문 시각 범위(최대 31일)로 주문 요약을 최신순으로 조회한다. 스코프 order:r.

  • status는 그 상태의 주문상품이 하나라도 있는 주문을 고른다.
  • representativeStatus는 첫 주문상품의 상태다.
  • orderNo(숫자 14자리 주문번호, 하이픈 허용)를 주면 기간 없이 그 주문만 찾는다. keyword도 주문번호를 받는다.
  • 테스트 결제(샌드박스 결제) 주문은 testPayment: true다. 실제로 돈이 오가지 않았으므로 상품을 발송하지 않도록 주의한다. testPayment 쿼리로 테스트 결제만(true)·실결제만(false) 볼 수 있다.
  • method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다(payment.approvedMethod — 매출 리포트·스토어프론트·환불 원장과 같은 값). 간편결제면 payment.easyPayProvider에 간편결제사가 함께 온다.

Authorization

accessToken
AuthorizationBearer <token>

Sayren 계정 토큰(로그인 토큰 또는 개인 액세스 토큰, RFC 9068 JWT)

In: header

Query Parameters

orderedFrom?string

조회 시작 시각 (ISO 8601 날짜 또는 일시, 포함). orderNo가 없으면 필수

orderedTo?string

조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 31일

status?string

주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문

Value in

  • "PAYMENT_WAITING"
  • "PAID"
  • "CONFIRMED"
  • "DISPATCHED"
  • "DELIVERING"
  • "DELIVERED"
  • "PURCHASE_DECIDED"
  • "CANCELED"
keyword?string

주문 id·주문번호(일치, 하이픈 허용)·주문자명·수령인명(포함) 검색

page?string

페이지 번호 (1부터, 기본 1)

size?string

페이지 크기 (기본 20, 최대 100)

testPayment?string

테스트 결제(샌드박스 결제) 필터. true면 테스트 결제만, false면 실결제만, 생략하면 전부입니다

Value in

  • "true"
  • "false"
fulfillmentType?string

상품 유형 필터(이슈 #48) — 이 유형(SHIPPING·MANUAL)의 주문상품이 하나라도 있는 주문

orderNo?string

주문번호 조회(이슈 #107) — 숫자 14자리, 하이픈 허용(2610-0284-7315-92). 주면 기간 조건 없이 그 주문만 찾습니다. 형식이 아니면 400 INVALID_PARAMETER

Header Parameters

X-Store-Id*string

대상 상점 id. 토큰의 상점 범위 밖이면 403 STORE_NOT_GRANTED, 없으면 400 STORE_ID_REQUIRED다

Response Body

application/json

curl -X GET "https://example.com/v1/orders" \  -H "X-Store-Id: string"
{  "meta": {    "status": 200,    "code": "OK",    "message": "OK",    "isSuccess": true  },  "data": {    "page": 0,    "size": 0,    "totalElements": 0,    "totalPages": 0,    "contents": [      {        "orderId": "string",        "orderNo": null,        "ordererName": "string",        "itemCount": 0,        "totalAmount": 0,        "representativeStatus": "PAYMENT_WAITING",        "progressStatus": "PAYMENT_WAITING",        "orderedAt": "string",        "testPayment": true      }    ]  },  "error": null}

주문상품 플로우에 상점 사건 보내기 POST

현장 단말·연동이 보내는 사건(`custom.<이름>`, 예: 티켓 입장 `custom.CHECKED_IN`)을 플로우에 넣는다. 지금 상태에 그 사건을 받는 연결선이 없으면 409 `FLOW_EVENT_NOT_ACCEPTED`, `custom.`·`app.`으로 시작하지 않으면 400 `FLOW_EVENT_KEY_INVALID`다. 앱 사건 `app.<handle>.<이름>`은 그 앱의 설치 토큰으로만 보내고 매니페스트 `flow.events`에 있는 이름이어야 한다(아니면 403 `FLOW_EVENT_APP_FORBIDDEN`). `Idempotency-Key`로 재시도가 안전하다.

주문 상세 조회 GET

주문자·배송지·결제 금액과 주문상품 전체를 조회한다. 스코프 `order:r`. 테스트 결제(샌드박스 결제) 주문은 `testPayment: true`다. 실제로 돈이 오가지 않았으므로 상품을 발송하지 않도록 주의한다. `testPayment` 쿼리로 테스트 결제만(`true`)·실결제만(`false`) 볼 수 있다. method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다(`payment.approvedMethod` — 매출 리포트·스토어프론트·환불 원장과 같은 값). 간편결제면 `payment.easyPayProvider`에 간편결제사가 함께 온다.