전달 방식

주문 생성 시 선택하는 delivery.method가 선물이 수신자에게 전달되는 방식 — 그리고 어떤 정보를 입력해야 하는지 — 를 결정합니다.

방식 선택하기

방식	전달 방법	필수 입력	적합한 용도
`EMAIL`	바우처를 수신자에게 이메일로 발송	`recipient.name`, `recipient.email`, `sender.name`	대부분의 디지털 기프팅
`TEXT`	바우처를 SMS로 발송	`recipient.name`, `recipient.phone_number`(상품 국가 형식), `sender.name`	전화번호를 확보한 수신자
`LINK`	보안 바우처 URL을 발신자가 받아 자체 채널(앱, 채팅, 푸시 등)로 직접 전달	`recipient.name`, `sender.name`	인앱 리워드, 전달 UX 직접 제어
`DIRECT_SHIPPING`	입력한 주소로 실물 상품 배송	`recipient.name`, `recipient.address`, `sender.name`	주소를 이미 확보한 실물 선물
`CODE`	전달 없이 바우처 원본(값/PIN/URL)을 직접 수령	없음 (수신자·발신자 정보 불필요)	지갑 충전, 코드 인쇄, 자체 fulfillment

상품마다 지원하는 방식이 다릅니다 — 주문 전에 상품 카탈로그의 available_delivery_method를 확인하세요.

위 표에서 해당 방식의 필수 입력 항목만 보내고 나머지는 빼세요. 방식이 쓰지 않는 필드를 함께 보내는 것은 지원하지 않으며, 앞으로는 받지 않을 수 있습니다.

⚠️
LINK에는 recipient.email을 넣지 마세요. 바우처 링크는 발신자가 직접 전달하므로 SodaGift는 이 주소를 쓰지 않습니다. 이 조합은 더 이상 권장하지 않습니다.

한국과 일본 번호는 검사 전에 정규화합니다. 그래서 국가번호와 하이픈은 넣어도 되고 빼도 됩니다. 한국 상품이라면 아래가 모두 통과하고 01012345678로 저장됩니다.

01012345678 · 010-1234-5678 · 1012345678 · 821012345678 · +821012345678 · +82 10-1234-5678

정규화한 뒤에는 올바른 한국 휴대폰 번호여야 합니다. 01로 시작하는 10자리 또는 11자리입니다. 유선번호처럼 이 조건을 벗어나면 invalid_phone_number_format 오류가 납니다.

그 밖의 국가는 상품 국가의 현지 형식으로 넣으세요.

LINK와 CODE는 주문 생성 응답에 바우처가 포함되지 않습니다. GET /v1/orders/{id}로 가져오세요:

LINK → order_items[].delivery.link — 수신자용 보안 URL.
CODE → order_items[].delivery.code — { value, pin, url, expired_at }. value / pin / url 중 어떤 필드가 채워지는지는 상품마다 다릅니다 — 코드 문자열만 오는 상품도, 교환 URL만 오는 상품도, 조합으로 오는 상품도 있습니다. 각 필드는 null일 수 있으므로 모든 조합을 처리하세요.

⚠️
링크와 코드는 시크릿으로 다루세요. URL이나 코드를 손에 넣은 사람은 누구나 선물을 사용할 수 있습니다. 반드시 의도한 수신자에게만 전달하고, 절대 로그에 남기지 마세요.

일부 상품은 배송 정보(예: 배송지 주소)를 발신자가 미리 수집하는 대신 수신자가 보안 링크를 통해 직접 입력하게 할 수 있습니다. 이 동작은 상품의 recipient_info_provided_by 필드로 결정됩니다:

["SENDER"] — 주문 시점에 발신자가 모든 전달 정보를 입력합니다.
["RECIPIENT"] 또는 ["SENDER", "RECIPIENT"] — 수신자가 직접 정보를 입력하도록 요청할 수 있습니다. 보안 링크는 EMAIL이나 LINK로 (그리고 MERCHANDISE 상품을 TEXT로 주문한 경우 SMS로) 전달됩니다.

수신자 직접 입력 플로우에서는:

수신자가 정보를 제출("수락")할 때까지 주문 아이템은 PENDING 상태에 머뭅니다. order_items[].delivery.recipient.acceptance — { status: PENDING | ACCEPTED | EXPIRED, expiry_date }로 추적하세요.
수신자가 응답하기 전에 수락 링크가 만료되면 해당 아이템은 이행되지 않습니다.
개인정보 보호를 위해, 수신자가 직접 입력한 전달 정보(전화번호, 주소)는 주문 조회 응답에서 null로 반환됩니다.

MERCHANDISE 상품은 발송 후 order_items[].delivery.shipping — { tracking_number, courier } 에서 추적 정보를 확인할 수 있습니다.