Guides

3. 첫 리워드 발송하기

상품 선택부터 주문·추적까지, 나에게 테스트 선물을 처음부터 끝까지 보내 봅니다.

Step 1 — 상품 고르기

카탈로그에서 주문 가능한 상품을 찾습니다. 예를 들어 한국 기프트 카드:

curl --request GET \
     --url 'https://biz-sandbox-api.sodagift.com/v1/products?country_code=KR&page=0&size=20' \
     --header 'SODA-API-KEY: YOUR-API-KEY' \
     --header 'accept: application/json'

응답에서 아래 조건을 만족하는 상품을 하나 고릅니다:

  • availability가 ON_SALE — 이 상태의 상품만 주문할 수 있습니다
  • available_delivery_method에 EMAIL 포함
  • amount가 결제될 고정 가격입니다. (일부 상품은 대신 min_amount/max_amount를 반환하며, 이 경우 주문 시 원하는 custom_amount를 지정합니다.)

아래 예시에서는 샌드박스 카탈로그의 세븐일레븐 ₩10,000 상품권(id: 10432)을 사용합니다.

⚠️

상품 ID는 계정·환경마다 다릅니다 — 예시의 id가 아니라 반드시 본인의 카탈로그 응답에 있는 id를 사용하세요.

Step 2 — 주문 생성하기

본인 이메일 주소로 선물을 보내 봅니다. 키와 이메일을 교체하세요:

curl --request POST \
     --url 'https://biz-sandbox-api.sodagift.com/v1/orders' \
     --header 'SODA-API-KEY: YOUR-API-KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "item": {
    "id": 10432
  },
  "delivery": {
    "method": "EMAIL",
    "recipient": {
      "name": "John Smith",
      "email": "[email protected]"
    },
    "sender": {
      "name": "John Smith"
    }
  },
  "message": "Congratulations!",
  "external_reference_id": "myfirstorder001"
}
'

성공 응답은 다음과 같습니다:

{
  "id": 33729,
  "status": "COMPLETED",
  "order_item": {
    "id": 33744,
    "status": "PENDING",
    "price": { "amount": 10000.0, "currency": "KRW" },
    "transaction_fee_rate": 0
  },
  "total_price_charged": {
    "amount": 7.34,
    "currency": "USD",
    "applied_exchange_rate": { "rate": 0.000734, "currency": { "from": "KRW", "to": "USD" } }
  },
  "external_reference_id": "myfirstorder001"
}

눈여겨볼 것 두 가지:

  • 주문은 COMPLETED(잔액에서 결제 완료)이고, 주문 아이템은 PENDING으로 시작합니다 — 선물이 발급·전달되면 COMPLETED로 바뀌며, 보통 수 초에서 수 분 안에 완료됩니다. 주문 라이프사이클을 참고하세요.
  • 상품 가격은 KRW지만 잔액은 계정 통화로 차감됩니다 — total_price_charged에 환산 금액과 적용 환율이 표시됩니다.
📘

external_reference_id는 나만의 중복 방지 키입니다: 같은 요청을 재시도하면 중복 주문 대신 기존 주문이 그대로 반환됩니다. 중복 방지와 재시도를 참고하세요.

Step 3 — 받은편지함 확인 및 주문 추적

리워드가 곧 받은편지함에 도착합니다. API로도 추적할 수 있습니다 (위 응답의 id 사용):

curl --request GET \
     --url 'https://biz-sandbox-api.sodagift.com/v1/orders/33729' \
     --header 'SODA-API-KEY: YOUR-API-KEY' \
     --header 'accept: application/json'

축하합니다 — 연동 준비 완료입니다! 🎉

다음 단계: 선물이 수신자에게 전달되는 방식은 전달 방식, 안정적인 추적 구현은 주문 라이프사이클을 참고하세요.

Updated 17 days ago

Did this page help you?