WAUG PARTNER API Document

Table of Contents

Introduction API 응답 공통 형식(JSON) API 응답 코드 계정 생성 인증 결제 API 호출 제한 상품 조회 주문 입력 정보 동적 주문 입력 정보 주문 생성 주문 상태 환불 요청 Webhook Changelog API 명세

Introduction

- WAUG PARTNER API는 WAUG 서비스에서 제공하는 일련의 기능들을 사용할 수 있도록 공개한 API입니다.

- WAUG PARTNER API의 최신 버전은 v1.0.0입니다.

- WAUG PARTNER API는 HTTP/1.1 요청/응답 으로 통신하며 모든 접근은 HTTPS 로 해야합니다. 데이터 송수신 포맷은 JSON 을 사용하며 문자 인코딩 방식은 UTF-8 을 사용합니다.

- WAUG PARTNER API는 BETA 환경과 PRODUCTION 환경을 제공합니다.

- BETA 환경은 일반적으로 개발 과정 중 테스트 용도로 사용되며, PRODUCTION 환경과 동일하지 않음을 유의해주시기 바랍니다.

- BETA 환경과 PRODUCTION 환경의 URL은 다음과 같습니다.

BETA API URL : https://beta-partner-api.waug.com

PRODUCTION API URL : https://partner-api.waug.com

API 응답 공통 형식(JSON)

데이터 송수신에 JSON을 사용하며 응답 공통 형식은 아래와 같습니다.

    {
        "responseCode": "000",
        "message": "this is message",
        "data": { //or [] },
        "count": 1,
        "version": "v1",
        "uri": "/v1/test",
        "service": "WAUG_PARTNER_API"
    }

속성	타입	설명
responseCode	string	응답 상태를 표현하는 응답 코드. 아래 "API 응답 코드" 섹션을 참고해주시길 바랍니다.
message	string	응답 메시지
data	object, array	응답 데이터. JSON 오브젝트 또는 JSON 배열으로 표현합니다.
count	int	응답 데이터의 총 갯수
version	string	WAUG PARTNER API 버전
uri	string	요청한 URI
service	string	WAUG PARTNER API 서비스명

API 응답 코드

WAUG PARTNER API 응답 공통 형식 중 "responseCode" 속성에 사용하는 응답 코드입니다.

범주	코드	설명
성공	000
실패	100	유효하지 않은 요청입니다
	101	유효하지 않은 인증입니다
	102	유효하지 않은 파라미터입니다
	103	데이터가 존재하지 않습니다
	104	잔액이 부족합니다
	105	상품정보가 변경되었습니다
	106	주문정보가 유효하지 않습니다
	107	환불 불가능한 상품입니다
	108	응답 시간이 초과되었습니다
	109	가격이 다릅니다
	110	파일 크기 제한을 초과했습니다
	111	api 호출 횟수 제한을 초과했습니다

계정 생성

WAUG PARTNER API를 사용하기 위해서는 계정 생성과 인증 토큰을 발급 받기 위한 Client Id, Client Secret 생성이 필요합니다.

현재 계정 생성 및 Client Id, Client Secret 생성은 별도의 절차를 통해 진행하고 있으며, 담당자 메일 로 문의해주시기 바랍니다.

인증

인증 토큰 발급 기능을 제외한 모든 요청은 인증 토큰이 필요 하며, 인증 토큰은 HTTP 요청 헤더 중 Authorization 헤더 에 추가하여 전송합니다.

인증 토큰 발급은 다음 절차를 통해 수행합니다.

1. 별도의 절차를 통해 인증 토큰 발급에 사용할 Client Id, Client Secret을 발급 받습니다.

2. WAUG PARTNER API의 인증 토큰 발급 기능을 통해 인증 토큰을 발급 받습니다. HTTP 인증 방식 중 Basic 방식 으로 Client Id와 Client Secret을 사용하여 요청합니다. 아래는 Curl을 사용할 경우의 예시입니다.

ex)
curl -X POST -u {Client Id}:{Client Secret} {WAUG PARTNER API URL}/v1/token

응답 내용은 아래와 같습니다.

ex)
{
    "accessToken": "ExampleTokenValue",
    "tokenType": "bearer",
    "expiresIn": "43199"
}

3. 인증 토큰 응답 중 "accessToken" 속성의 값을 Authorization 헤더에 아래와 같이 추가하여 전송합니다.

ex)
Authorization: Bearer ExampleTokenValue

결제

현재 WAUG PARTNER API의 결제는 선급금 잔액 차감으로 이뤄지며, 잔액이 결제 금액보다 부족한 경우 주문이 불가합니다.

결제 관련 문의는 담당자 메일로 문의해주시기 바랍니다.

API 호출 제한

API 호출은 100회/10초 로 제한됩니다. 호출 제한을 넘어서는 호출은 111 (api 호출 횟수 제한을 초과했습니다) 응답 코드를 받게 됩니다. 10초 마다 제한은 해제 됩니다.

예) 초기화 후 6초간 100회 호출 -> 4초간 모든 호출은 111 오류 응답 받음 -> 초기화 되어 정상 호출

예외) 예약 생성 api 호출에는 이 규칙이 적용되지 않습니다.

상품 조회

WAUG PARTNER API로 WAUG의 상품 정보를 조회할 수 있습니다.

WAUG의 상품 정보는 계층 구조로 표현되며 상품(Goods), 상품 옵션(Goods Option), 상품 옵션 항목(Goods Option Item)으로 분류합니다.

주문할 상품을 선택하는 과정의 예시는 아래와 같습니다.

1. 사용자가 상품 목록을 조회하여 원하는 상품을 선택합니다.

2. 사용자가 선택한 상품의 날짜별 상품 가격 목록을 조회하여 원하는 사용예정일의 상품 가격을 확인합니다.

3-1. 원하는 날짜의 상품 가격이 존재할 경우 선택한 상품은 해당 사용예정일에 주문 가능한 상품입니다.

3-2. 원하는 날짜의 상품 가격이 존재하지 않을 경우 선택한 상품은 해당 사용예정일에 주문 불가한 상품입니다.

4. 주문 가능한 상품 가격에서 원하는 상품 옵션과 상품 옵션 항목을 선택합니다.

5. WAUG PARTNER API의 기능을 통해 선택한 상품 옵션과 상품 옵션 항목의 정보를 확인합니다.

주문 입력 정보

상품을 주문할 때 입력해야 하는 정보가 존재합니다. 이러한 주문 입력 정보는 상품에 따라 상이합니다.

주문 입력 정보 그룹(Group)과 주문 입력 정보 필드(Field)로 구성됩니다.

하나의 상품에 해당하는 주문 입력 정보는 여러 그룹이 포함되며, 하나의 그룹에 여러 필드가 포함되어 있습니다.

아래는 하나의 상품에 대한 주문 입력 정보 예시입니다.

    [
        {
            "groupCategory": "ORDER",
            "fields": [
                {
                    "fieldId": 4,
                    "fieldName": "여권상 영문명",
                    "fieldExplain": "",
                    "fieldPlaceholder": "",
                    "fieldOption": "",
                    "fieldType": "engname",
                    "required": true
                },
                {
                    "fieldId": 2,
                    "fieldName": "휴대전화번호",
                    "fieldExplain": "",
                    "fieldPlaceholder": "",
                    "fieldOption": "",
                    "fieldType": "mobile",
                    "required": true
                },
                {
                    "fieldId": 8,
                    "fieldName": "이메일",
                    "fieldExplain": "",
                    "fieldPlaceholder": "",
                    "fieldOption": "",
                    "fieldType": "email",
                    "required": true
                }
            ]
        },
        {
            "groupCategory": "GOODS",
            "fields": [
                {
                    "fieldId": 67,
                    "fieldName": "호텔명",
                    "fieldExplain": "호텔명을 입력해주세요",
                    "fieldPlaceholder": "",
                    "fieldOption": "",
                    "fieldType": "text",
                    "required": true
                }
            ]
        },
        {
            "groupCategory": "EACH",
            "fields": [
                {
                    "fieldId": 8,
                    "fieldName": "이메일",
                    "fieldExplain": "",
                    "fieldPlaceholder": "",
                    "fieldOption": "",
                    "fieldType": "email",
                    "required": true
                }
            ]
        }
    ]

주문 입력 정보 그룹 범주

주문 입력 정보 그룹은 아래와 같이 3가지 범주로 나눠지며 각기 다른 그룹으로 구성됩니다. 범주에 대한 설명은 아래와 같습니다.

범주	설명
ORDER	주문 전체에 해당되는 주문 공통 입력 정보입니다.
GOODS	특정 주문 상품에 적용되는 주문 상품 입력 정보입니다.
EACH	특정 주문 상품에 적용되는 주문 입력 정보 중 수량만큼 입력해야 하는 정보입니다.

주문 입력 정보 필드 타입

주문 입력 정보 필드는 여러 가지의 타입 중 하나에 포함됩니다. 필드 타입에 대한 설명은 아래와 같습니다.

타입명	설명	예시
text textarea text_short text_middle	텍스트를 입력합니다.	ex) ExampleText
date	"yyyy-MM-dd" 형식으로 표현한 날짜를 입력합니다.	ex) 1980-01-22
birthdate	"yyyy-MM-dd" 형식으로 표현한 생년월일을 입력합니다.	ex) 1980-01-22
email	이메일 주소를 입력합니다.	ex) guest1@waug.com
engname	여권상 영문명을 입력합니다.	ex) HONG GILDONG
time	"HH:mm" 또는 "HH:mm:ss" 형식으로 표현한 시간을 입력합니다.	ex) 09:00
mobile	휴대전화번호를 입력합니다.	ex) 8201012341234
tel	유선전화번호를 입력합니다.	ex) 021231111
number	숫자를 입력합니다.	ex) 7
radio	화면에서 라디오버튼으로 표현되는 필드 타입입니다.
select	화면에서 셀렉트박스로 표현되는 필드 타입입니다.
checkbox	화면에서 체크박스로 표현되는 필드 타입입니다.

동적 주문 입력 정보

상품 정보를 조회할 때 다음과 같은 정보가 나옵니다.

상품 조회 API : /v1/goods/{goodsId}

{
  "instantVoucher": true,
  "goodsId": 0,
  "availableDate": 0,
  "availableTime": 0,

  ...

  "isRealtime": true,
  "isDynamicOrderInfo": true,

  ...
}

여기서 isDynamicOrderInfo: true 인 경우 이 상품은 동적 예약자 정보 상품을 뜻합니다.

동적 예약자 정보 상품의 경우 기존에 사용하셨던 /v1/goods/{goodsId}/order-infos 가 아닌

/v1/goods/{goodsId}/order-infos/{goodsOptionId} API 를 사용하여야 주문에 필요한 모든 정보를 얻으실 수 있습니다.

정리하면 다음과 같습니다.

isDynamicOrderInfo: false 인 경우 주문 입력 정보 조회시 기존대로 하시면 되고
isDynamicOrderInfo: true 인 경우에는 주문 입력 정보 조회시 새로운 API 를 통해 조회하시면 됩니다.

/v1/goods/{goodsId}/order-infos/{goodsOptionId} 에 대한 내용은 API 명세에 추가해 두었습니다.

주문 생성

WAUG PARTNER API로 주문을 생성할 수 있습니다.

주문을 생성하기 전에 요청할 주문 생성 정보가 주문 가능한지 확인할 수 있는 주문 가능 여부 확인 기능을 제공합니다.

WAUG의 주문 정보는 주문(Order), 주문 상품(Order Goods), 주문 옵션(Order Option)이 계층적으로 구성되어 있습니다.

주문(Order)에는 공통된 주문 정보가 포함됩니다.

주문 상품(Order Goods)에는 주문할 상품의 정보가 포함됩니다. 대표적으로 상품 ID가 있습니다.

주문 옵션(Order Option)에는 주문할 상품의 옵션 및 옵션 항목 정보가 포함됩니다. 대표적으로 상품 옵션 ID, 옵션 항목 ID가 있습니다.

주문 입력 정보는 그룹 범주에 따라 주문에 포함되거나 주문 상품에 포함됩니다.

주문을 생성할 때에도 위와 동일한 구성으로 요청 정보를 작성하며 그림으로 표현하면 아래와 같습니다.

주문 생성 요청 정보의 예시는 아래와 같습니다.

ex)
{
  "locale": "ko",
  "orderGoods": [
    {
      "goodsId": 107278,
      "useDate": "2019-04-01",
      "orderOptions": [
        {
          "goodsOptionId": 28919,
          "goodsOptionItemId": 61849,
          "quantity": 1,
          "price": 37080,
          "goodsOptionTimeslotId": 0
        },
        {
          "goodsOptionId": 28919,
          "goodsOptionItemId": 61850,
          "quantity": 2,
          "price": 22000,
          "goodsOptionTimeslotId": 0
        }
      ],
      "orderInfos": [
        {
          "fieldId": 26,
          "groupCategory": "GOODS",
          "values": [
            "ExampleGoodsOrderInfo1"
          ]
        },
        {
          "fieldId": 63,
          "groupCategory": "GOODS",
          "values": [
            "ExampleGoodsOrderInfo1"
          ]
        },
        {
          "fieldId": 4,
          "groupCategory": "EACH",
          "values": [
            "Foo", "Bar", "Example"
          ]
        }
      ]
    },
    {
      "goodsId": 109329,
      "useDate": "2019-04-05",
      "additionalInput": "this is additional input example.",
      "orderOptions": [
        {
          "goodsOptionId": 31451,
          "goodsOptionItemId": 74509,
          "quantity": 1,
          "price": 20580.0,
          "goodsOptionTimeslotId": 0
        }
      ],
      "orderInfos": [
        {
          "fieldId": 6,
          "groupCategory": "GOODS",
          "values": [
            "ExampleGoodsOrderInfo1"
          ]
        }
      ]
    }
  ],
  "orderInfos": [
    {
      "fieldId": 1,
      "groupCategory": "ORDER",
      "values": [
        "ExampleOrderUserKoreanName"
      ]
    },
    {
      "fieldId": 4,
      "groupCategory": "ORDER",
      "values": [
        "ExampleOrderUserEnglishName"
      ]
    },
    {
      "fieldId": 2,
      "groupCategory": "ORDER",
      "values": [
        "ExampleOrderUserContact"
      ]
    },
    {
      "fieldId": 8,
      "groupCategory": "ORDER",
      "values": [
        "example@example.com"
      ]
    }
  ]
}

주문을 생성하는 과정의 예시는 아래와 같습니다.

1. 사용자가 상품의 정보를 조회하고 주문할 상품을 선택합니다.

2. 주문할 상품의 주문 입력 정보를 조회합니다.

3. 주문 생성 요청 정보를 형식에 맞게 작성합니다.

4. 작성한 주문 생성 요청 정보가 주문 가능한 정보인지 여부를 확인합니다.

5. 주문 가능한 주문 생성 요청 정보인 경우 주문 생성을 요청합니다.

6-1. WAUG PARTNER API에서 검증을 통과한 경우 주문이 생성됩니다.

6-2. WAUG PARTNER API에서 검증을 통과하지 못한 경우 주문 불가 응답이 반환됩니다.

7. WAUG PARTNER API에서 주문 생성 후 바우처 즉시 발급 여부를 확인합니다.

8-1. 바우처 즉시 발급 상품인 경우 바우처를 즉시 발급합니다.

8-2. 바우처 즉시 발급 상품이 아닌 경우 일정 시간 경과 후 바우처를 발급합니다.

주문 상태

WAUG PARTNER API에서 주문할 때 여러 상품들을 한 번에 묶어서 주문할 수 있습니다.

따라서 주문과 각각의 주문 상품마다 주문 상태가 존재합니다.

주문상품(OrderGood) 상태의 설명은 아래와 같습니다.

코드	상태	설명
STATUS_WAIT	결제 대기	주문은 생성되었지만, 결제가 완료되지 않은 상태
STATUS_CANCEL	예약 취소	주문은 생성되었지만, 결제가 완료되지 않은 상태에서 주문을 취소한 상태
STATUS_PAID	주문 완료	주문은 생성이 되었고, 결제도 완료된 상태
STATUS_IN_PROGRESS	바우처 발급 진행중	바우처 발급이 진행 중인 상태
STATUS_CONFIRMED	바우처 발급 완료	바우처 발급이 완료된 상태
STATUS_REFUND_REQUESTED	환불 요청	해당 주문의 환불이 요청된 상태
STATUS_REFUND_COMPLETED	환불 완료	환불 요청이 처리되어 환불이 완료된 상태
STATUS_PARTIAL_REFUND_COMPLETED	부분 환불 완료	환불 요청이 처리되어 부분 환불이 완료된 상태

주문(Order) 상태의 설명은 아래와 같습니다.

코드	상태	설명
STATUS_WAIT	결제 대기	주문은 생성되었지만, 결제가 완료되지 않은 상태
STATUS_PAID	주문 완료	주문이 생성되고, 결제도 완료된 상태
STATUS_REFUND_REQUESTED	환불 요청	해당 주문의 환불이 요청된 상태
STATUS_PARTIAL_REFUND_REQUESTED	부분 환불 요청	해당 주문의 부분 환불이 요청된 상태
STATUS_REFUND_COMPLETED	환불 완료	환불 요청이 처리되어 환불이 완료된 상태
STATUS_PARTIAL_REFUND_COMPLETED	부분 환불 완료	부분 환불 요청이 처리되어 환불이 완료된 상태

환불 요청

WAUG PARTNER API로 특정 주문의 환불을 요청할 수 있습니다.

해당 기능은 주문을 환불 요청 상태로 변경하며 실제 환불 진행은 별도의 절차를 통해 진행됩니다.

주문에 포함되어 있는 상품 중 환불 불가 상품이 있을 경우 환불 요청이 거부됩니다.

환불 가능 상품 여부는 상품 정보 중 refundable 속성으로 알 수 있습니다.

특정 주문을 환불 요청하는 과정의 예시는 아래와 같습니다.

1. 사용자가 환불 요청할 주문을 확인합니다.

2. 사용자가 주문 번호로 환불을 요청합니다.

3. WAUG PARTNER API에서 환불 요청한 주문에 포함된 상품 중 환불 불가 상품이 있는지 확인합니다.

4-1. 환불 불가 상품이 아니면 환불 요청이 성공합니다.

4-2. 환불 불가 상품이면 환불 요청이 실패합니다.

Webhook

WAUG PARTNER API는 특정 이벤트에 대한 Webhook 기능을 제공합니다.

Webhook 기능에 대한 문의는 담당자 메일로 부탁드립니다.

상품 정보 변경 알림 Webhook

상품의 정보 변경 시 알림 Webhook을 제공합니다.

Webhook 내용은 아래와 같습니다.

{
    "goodsId": 1,
    "type": "GOODS_UPDATE",
    "updatedAt": {
        "date": "yyyy-MM-dd HH:mm:ss.SSS",
        "timezone_type": 3,
        "timezone": "Asia/Seoul"
    }
}

다만 상품 정보 변경이 수시로 발생하므로 상품 정보 동기화를 1일 1회 이상 권장합니다.

주문 상태 변경 알림 Webhook

주문의 상태 변경 시 알림 Webhook을 제공합니다.

Webhook 내용은 아래와 같습니다.

    {
        "orderNumber": "exampleOrderNumber",
        "orderGoodsId": 1,
        "type": "ORDER_UPDATE",
        "orderStatus": "STATUS_CONFIRMED"
        "updatedAt": {
            "date": "yyyy-MM-dd HH:mm:ss.SSS",
            "timezone_type": 3,
            "timezone": "Asia/Seoul"
        }
    }

다만 WAUG PARTNER API의 환불 요청 기능을 사용하여 변경되는 경우는 Webhook을 발송하지 않습니다.

주문 상태에 대한 설명은 주문 상태에서 확인 하실 수 있습니다.

Changelog

- 2019-04-02 : WAUG PARTNER API 문서 v1.0.0 공개

- 2019-11-11 : /v1/goods/{goodsId} 호출 시 voucherType 필드 추가

- 2019-11-25 : 환불 요청 상태에서 ordergood의 status가 STATUS_REFUND_REQUESTED로 안나오는 버그 수정

- 2019-11-25 : /v1/orders , v1/orders/{orderNumber}, v1/orders-partner/{partnerOrderNumber}, /v1/orders/{orderNumber}/refund-request 호출 시 order의 status 나오도록 수정

- 2019-12-16 : api 호출 throttling 기능 추가 (100회/10초)

- 2020-01-09 : 환불요청 api v2 추가(환불요청 api v1 2020-03-17 삭제예정)

- 2020-02-17 : 환불요청 api v2 수정(요청 파라미터 수정)

- 2020-04-02 : /v1/goods/{goodsId}/comments api max page size 변경(10000->100)

- 2020-04-06 : 환불요청 api v2 잠정적 폐쇄(내부 시스템 업데이트 된후 재오픈 예정)

- 2020-06-10 : 환불요청 api v2 재오픈(슬랙알림만 가능)

- 2020-10-12 : /v1/orders 호출 시 요청 파라미터로 startDate, endDate 추가

- 2021-04-09 : /v1/goods/{goodsId} 호출 시 응답 필드에 availableTime 추가

- 2021-12-22 : /v1/goods/{goodsId} 호출 시 응답 필드에 notification 추가

- 2022-08-19 : /v1/goods/{goodsId} 호출 시 응답 필드에 useAvailableTime 추가

- 2024-10-17 : 동적 주문 입력 정보 API 추가

API 명세

Singapore : 541 Orchard Road, #17-01 Liat Towers Singapore

日本 : 101-0053 3F, Daiichitoei Bldg., 11-2 Kanda Mitoshirocho, Chiyoda-Ku, Tokyo, Japan

Republic of Korea : 20F, DMC DigitalCube Bldg, 34 Sangamsan-ro, Mapo-gu, Seoul, South Korea

Customer Support Center : +82 ) 070-4353-5959 ( AM 10:00 - PM 7:00 (GMT+9) )

WAUG Travel Inc. is a sales broker, we are not responsible for any product information and transactions.

Communication Sales Business Report 2017-서울마포-0310 Business License

WAUG Travel Inc. ┃ CEO Yoon Sunwoo