Step 5: 주문 및 결제

견적 조회, 주문 생성, 취소, 배송지 변경 등 주문 관련 전체 프로세스를 안내합니다.

견적 조회

POST /orders/estimate로 주문 전에 가격을 확인합니다. 응답에는 productAmount(제작비) + shippingFee(배송비) + packagingFee(포장비) = totalAmount(합계)가 포함되며,paidCreditAmount는 부가세(10%)가 포함된 실제 차감 금액입니다.

bash

curl -X POST 'https://api-sandbox.sweetbook.com/v1/orders/estimate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    { "bookUid": "bk_3dJTg8WOpR2e", "quantity": 1 }
  ]
}'

json

{
  "success": true,
  "data": {
    "items": [
      {
        "bookUid": "bk_3dJTg8WOpR2e",
        "bookSpecUid": "SQUAREBOOK_HC",
        "pageCount": 32,
        "quantity": 1,
        "unitPrice": 100,
        "itemAmount": 100,
        "packagingFee": 0
      }
    ],
    "productAmount": 100,
    "shippingFee": 0,
    "packagingFee": 0,
    "totalAmount": 100,
    "paidCreditAmount": 110,
    "creditBalance": 100000,
    "creditSufficient": true,
    "currency": "KRW"
  }
}

Sandbox에서는 테스트 가격(100원 이하)이 적용됩니다. Live 환경의 실제 가격은 개별 협의에 따라 결정됩니다.

충전금 잔액 확인

GET /credits로 현재 충전금 잔액을 확인합니다. 주문 생성 전에 잔액이 충분한지 반드시 확인하세요.

bash

curl -X GET 'https://api-sandbox.sweetbook.com/v1/credits' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Sandbox 충전금: 파트너 포털의 충전금 관리에서 테스트 충전금을 직접 원하는 금액으로 입력할 수 있습니다. Live 환경과 완전히 분리되어 있습니다.

주문 생성

POST /orders로 주문을 생성합니다. 주문 생성 즉시 충전금이 차감되며, 배송 정보가 필수입니다.

bash

curl -X POST 'https://api-sandbox.sweetbook.com/v1/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    { "bookUid": "bk_3dJTg8WOpR2e", "quantity": 1 }
  ],
  "shipping": {
    "recipientName": "홍길동",
    "recipientPhone": "010-1234-5678",
    "postalCode": "06236",
    "address1": "서울특별시 강남구 테헤란로 123",
    "address2": "4층"
  }
}'

json

{
  "success": true,
  "data": {
    "orderUid": "ord_a1b2c3d4e5f6",
    "orderStatus": "PAID",
    "totalAmount": 100,
    "paidCreditAmount": 110,
    "items": [
      {
        "itemUid": "itm_x1y2z3w4",
        "bookUid": "bk_3dJTg8WOpR2e",
        "quantity": 1,
        "unitPrice": 100,
        "itemAmount": 100
      }
    ]
  }
}

충전금 부족 (402 에러)

충전금 잔액이 부족한 상태에서 주문을 생성하면 402 Payment Required 응답이 반환됩니다.

json

{
  "success": false,
  "message": "Insufficient credits. Required: 12500, Available: 5000",
  "data": null
}

주문 생성 전에 POST /orders/estimate의 creditSufficient 필드로 잔액 충분 여부를 미리 확인하세요. Live 환경에서는 파트너 포털에서 충전금을 결제하여 충전합니다.

주문 취소

PAID 또는 PDF_READY 상태의 주문만 취소할 수 있습니다. 취소 즉시 충전금이 환불됩니다.

bash

curl -X POST 'https://api-sandbox.sweetbook.com/v1/orders/{orderUid}/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'

취소 불가 상태: CONFIRMED 이후의 주문은 이미 제작이 시작되어 취소할 수 없습니다.
에러 메시지: "주문을 찾을 수 없습니다." 또는 "PAID 또는 PDF_READY 상태의 주문만 취소할 수 있습니다."

배송지 변경

PATCH /orders/{orderUid}/shipping으로 배송지 정보를 변경할 수 있습니다.

bash

curl -X PATCH 'https://api-sandbox.sweetbook.com/v1/orders/{orderUid}/shipping' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipientName": "김철수",
  "recipientPhone": "010-9876-5432",
  "postalCode": "04523",
  "address1": "서울특별시 중구 세종대로 110",
  "address2": "2층"
}'

주문 조회

GET /orders로 주문 목록을, GET /orders/{orderUid}로 개별 주문 상세를 조회합니다.

bash

# 주문 목록 조회
curl -X GET 'https://api-sandbox.sweetbook.com/v1/orders?limit=20&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# 개별 주문 조회
curl -X GET 'https://api-sandbox.sweetbook.com/v1/orders/{orderUid}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

주문 상태 코드

주문은 다음 상태를 순서대로 거칩니다.

Code	상태	설명
`20`	`PAID`	결제 완료 (충전금 차감됨)
`25`	`PDF_READY`	인쇄용 PDF 생성 완료
`30`	`CONFIRMED`	제작 확정
`40`	`IN_PRODUCTION`	제작 진행 중
`50`	`PRODUCTION_COMPLETE`	제작 완료
`60`	`SHIPPED`	배송 출발
`70`	`DELIVERED`	배송 완료
`80`	`CANCELLED`	주문 취소
`81`	`CANCELLED_REFUND`	취소 및 환불 완료

취소는 PAID(20) 또는 PDF_READY(25) 상태에서만 가능합니다.CONFIRMED(30) 이후에는 이미 제작이 시작되어 API를 통한 취소가 불가능합니다.

다음 단계

Step 6: 웹훅으로 상태 추적 — 주문 상태 변경을 실시간으로 수신
충전금 시스템 — 충전금 잔액 관리 및 거래 내역
Orders API 레퍼런스 — 전체 Orders API 상세 문서