---
# System prepended metadata

title: 東琉線 API

---

## 東琉線提供 API

### POST_新增訂單

- Request

```json
header: { X-API-KEY: <key> }

"orderDetails": [
  { 
    "passengerId": "A123456789",
    "passengerMobile": "0912345678",
    "passengerName": "王小明",
    "passengerBirthday": "1990-01-01",
    "departureDate": "2023-06-01",
    "ticketType": 1 // 票種類型
  　"status": 1
  },
  { 
    "passengerId": "A123456789",
    "passengerMobile": "0912345678",
    "passengerName": "王小明",
    "passengerBirthday": "1990-01-01",
    "departureDate": "2023-06-01",
    "ticketType": 2 // 票種類型
  　"status": 1
  },
  { 
    "passengerId": "A123456789",
    "passengerMobile": "0912345678",
    "passengerName": "王小明",
    "passengerBirthday": "1990-01-01",
    "departureDate": "2023-06-01",
    "ticketType": 1 // 票種類型
  　"status": 1
  },
]
```
- Request Schema

| 屬性名稱            | 型別      | 描述                     |是否允許為null|
|-------------------|----------|------------------------|---------|
| `passengerId`     | `string` | 乘客的證件號碼               |是|
| `passengerMobile` | `string` | 乘客的手機號碼               |是|
| `passengerName`   | `string` | 乘客的姓名                 |是|
| `passengerBirthday` | `string` | 乘客的生日（格式：YYYY-MM-DD） |是|
| `departureDate`   | `string` | 出發日期（格式：YYYY-MM-DD）  |否|
| `ticketType`      | `number` | 票種類型 1: 來回全票、2: 來回半票           |否|
| `status`     | 1、2、3、4 | 票卷狀態   |否|

- Responce
```json
"statusCode": 200, // 200成功、400失敗、401驗證失敗
"message": "string",
"contents": {
  "orderDetails": [
    { 
      "orderDetailGid": "7afed1e1-3e32-4598-fc5e-08dc1e42c939", // 重要唯一識別碼，請回存
      "orderNumber": "0123456789",
      "passengerId": "A123456789",
      "passengerMobile": "0912345678",
      "passengerName": "王小明",
      "passengerBirthday": "1990-01-01",
      "departureDate": "2023-06-01",
      "ticketType": 1
    　"status": 1
    },
    { 
      "orderDetailGid": "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
      "orderNumber": "0123456789",
      "passengerId": "A123456789",
      "passengerMobile": "0912345678",
      "passengerName": "王小明",
      "passengerBirthday": "1990-01-01",
      "departureDate": "2023-06-01",
      "ticketType": 2
    　"status": 1
    },
    { 
      "orderDetailGid": "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
      "orderNumber": "0123456789",
      "passengerId": "A123456789",
      "passengerMobile": "0912345678",
      "passengerName": "王小明",
      "passengerBirthday": "1990-01-01",
      "departureDate": "2023-06-01",
      "ticketType": 1
    　"status": 1
    }
  ]
}

```

- Responce Schema

| 屬性名稱                | 型別        | 描述                             |
|-----------------------|------------|--------------------------------|
| `statusCode`          | `number`   | 狀態碼（例如 200 成功、400 失敗、401 驗證失敗） |
| `message`             | `string`   | 回應消息                         |
| `contents`            | `object`   | 包含訂單詳細信息的物件                |
| `contents.orderDetails` | `array`   | 訂單明細列表                       |
| `orderDetailGid`      | `string`   | 訂單詳細的唯一識別碼                   |
| `orderNumber`         | `string`   | 訂單代碼                       |
| `passengerId`         | `string`   | 乘客的證件號碼                       |
| `passengerMobile`     | `string`   | 乘客的手機號碼                       |
| `passengerName`       | `string`   | 乘客的姓名                         |
| `passengerBirthday`   | `string`   | 乘客的生日（格式：YYYY-MM-DD）         |
| `departureDate`       | `string`   | 出發日期（格式：YYYY-MM-DD）          |
| `ticketType`          | `number`   | 票種類型（整數）                    |
| `status`         | 1、2、3、4  | 票卷狀態           |


- Fetch Example

```javascript=
async function postOrderDetails(orderDetails) {
  const url = 'YOUR_API_URL';
  const apiKey = 'YOUR_API_KEY';

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': apiKey
      },
      body: JSON.stringify({ orderDetails })
    });

    if (!response.ok) {
      throw new Error('Network response was not ok');
    }

    const data = await response.json();
    console.log('Success:', data);
  } catch (error) {
    console.error('Error:', error);
  }
}

// 使用範例
const orderDetails = [
  {
    "passengerId": "A123456789",
    "passengerMobile": "0912345678",
    "passengerName": "王小明",
    "passengerBirthday": "1990-01-01",
    "departureDate": "2023-06-01",
    "ticketType": 1
  }
];
```

- 問題記錄

1. header 中除了要帶 X-API-KEY 之外，有沒有需要帶 token？
    > 只需要代 X-API-KEY 就好，除此之外我們還會檢查 domain name 白名單
3. passengerId 為空時，要帶的值是什麼？
    > 代 `null` 即可
5. passengerMobile、passengerName 有沒有 Regex 限制？
    > 因為聯營處需求變來變去，目前都沒限制了
7. 如果要訂 2 全 2 半且只有訂票人資料時，orderDetails 應該怎麼傳？
    > 考量到你們會有個資不齊的情況，目前個資那四個欄位都改為選填
9. isCollected 為 true 時，會寫入當下取票日期，是指說型別會變成 `[boolean,timestamp()]` 嗎？
    > 不是，你們只要給我們 boolean 就好，該註解是為了告知此動作會回寫取票時間

### GET_取得訂單
- Request
```url=
// 取得多筆票券資料
[GET] https://{domain name}/api/*/orderList/{startDate}/{endDate}
[Example] https://{domain name}/api/*/orderList/2024-01-01/2024-01-01

// 取得指定票券資料
[GET] https://{domain name}/api/*/orderList/{orderDetailGid}
[Example] https://{domain name}/api/*/orderList/7afed1e1-3e32-4598-fc5e-08dc1e42c939
```
- Request Schema

| 屬性名稱            | 型別      | 描述                     |
|-------------------|----------|------------------------|
| `orderDetailGid`  | `string` | 乘客的唯一 ID（票號）     |
| `startDate`  | `string` | 啟程日期起始     |
| `endDate`  | `string` | 啟程日期結束     |

- Responce
```json
"statusCode": 200, // 200成功、400失敗、401驗證失敗
"message": "string",
"contents": {
  "orderDetails": [
    { 
      "orderDetailGid": "7afed1e1-3e32-4598-fc5e-08dc1e42c939", // 重要唯一識別碼
      "orderNumber": "0123456789",
      "passengerId": "A123456789",
      "passengerMobile": "0912345678",
      "passengerName": "王小明",
      "passengerBirthday": "1990-01-01",
      "departureDate": "2023-06-01",
      "ticketType": 1
    　"status": 1
    },
    { 
      "orderDetailGid": "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
      "orderNumber": "0123456789",
      "passengerId": "A123456789",
      "passengerMobile": "0912345678",
      "passengerName": "王小明",
      "passengerBirthday": "1990-01-01",
      "departureDate": "2023-06-01",
      "ticketType": 2
    　"status": 1
    },
    { 
      "orderDetailGid": "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
      "orderNumber": "0123456789",
      "passengerId": "A123456789",
      "passengerMobile": "0912345678",
      "passengerName": "王小明",
      "passengerBirthday": "1990-01-01",
      "departureDate": "2023-06-01",
      "ticketType": 1
    　"status": 1
    }
  ]
}

```

### DELETE_取消訂單
- Request
```json
"orderDetailGid": [
  "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
  "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
  "7afed1e1-3e32-4598-fc5e-08dc1e42c939"
]
```
- Request Schema

| 屬性名稱            | 型別      | 描述                     |
|-------------------|----------|------------------------|
| `orderDetailGid`  | `string[]` | 乘客的唯一 ID（票號         |

- Responce

```
"statusCode": 200, // 200成功、400失敗、401驗證失敗
"message": "string"
```

- Responce Schema

| 屬性名稱                | 型別        | 描述                             |
|-----------------------|------------|--------------------------------|
| `statusCode`          | `number`   | 狀態碼（例如 200 成功、400 失敗、401 驗證失敗） |
| `message`             | `string`   | 回應消息                         |


- Fetch Example

```javascript=
async function postOrderDetailGids(orderDetailGids) {
  const url = 'YOUR_API_URL'; // 替換成您的 API URL
  const apiKey = 'YOUR_API_KEY'; // 替換成您的 API 密鑰

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': apiKey
      },
      body: JSON.stringify({ orderDetailGid: orderDetailGids })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Success:', data);
  } catch (error) {
    console.error('Error:', error);
  }
}

// 使用範例
const orderDetailGids = [
  "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
  "7afed1e1-3e32-4598-fc5e-08dc1e42c939",
  "7afed1e1-3e32-4598-fc5e-08dc1e42c939"
];

postOrderDetailGids(orderDetailGids);

```

- 問題記錄

1. header 中是否需要帶 X-API-KEY、token？
    > 要代 X-API-KEY
3. 取消的權限到哪裡？ ex：只能取消未取票
    > 目前系統機制是，如果「已經登船」（掃票上船後）不允許退票
5. 是否能多回傳目前有效票數，例如全部有 5 張票，取消 3 張，回傳內容會顯示還剩 2 張有效票。
    > 如果你們有回存 `orderDetailGid` 應該針對其 ID 更新取票狀態即可，不用依賴此 API 回傳有效票數；另外也可以從 GET 訂單列表 API 取得狀態

---
## 星宸數位提供 API

### POST_接收取票通知

- Request

```javascript=
header: { AuthToken: <key> }


{
    "orderNumber": "{{orderNumber}}",
    "orderDetails": [
        {
            "orderDetailGid": "{{orderDetailGid}}",
            "status": 2 // 1:未取|2:已取|3:登船|4:取消
        }
    ]
}
```
- Request Schema

| 屬性名稱            | 型別      | 描述                     |
|-------------------|----------|------------------------|
| `orderNumber`  | `string` | 訂單編號         |
| `orderDetails`  | `Array<object>` | 乘客的唯一 ID（票號）、票卷狀態         |

- Responce

```
"statusCode": 200, // 200成功、400失敗、401驗證失敗
"message": "string"
```

- Responce Schema

| 屬性名稱                | 型別        | 描述                             |
|-----------------------|------------|--------------------------------|
| `statusCode`          | `number`   | 狀態碼（例如 200 成功、400 失敗、401 驗證失敗） |
| `message`             | `string`   | 回應消息                         |


- Fetch Example

```javascript=
async function postCollectStatus(orderDetailGids) {
  const url = 'YOUR_API_URL'; // 替換成您的 API URL
  const apiKey = 'YOUR_API_KEY'; // 替換成您的 API 密鑰

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'AuthToken': 'token'
      },
      body: JSON.stringify({ orderDetailGid: orderDetailGids })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Success:', data);
  } catch (error) {
    console.error('Error:', error);
  }
}

postCollectStatus(orderDetailGids);

```

- 問題記錄

1. header 中的 AuthToken 為固定值，用於辨識請求來源用，介接時星宸提供。

---

## 額外問題

- 是否也能提供一支可以取得所有訂單的 GET？
    > 可以