## 東琉線提供 API

### POST_新增訂單

- Request

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

"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

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

// 取得多筆票券資料
[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

"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

"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

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

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

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？
> 可以