# 居民价集成

{% hint style="info" %}
遇到 API 接入问题时，可登录 [Eva](https://www.atriptech.com/) 寻求帮助。
{% endhint %}

当你需要支持西班牙国内居民票价时，使用这个页面。

### 什么时候使用这条流程

只有在以下场景才使用居民价流程：

* 乘客符合西班牙居民或家庭折扣资格
* 航线属于支持的西班牙国内航线
* 你能在下单时采集必需证明字段
* 航司支持居民票价

### 支持的航司

* `FR`
* `VY`

### 适用旅客范围

该流程适用于以下地区的合法居民：

* Canary Islands
* Balearic Islands
* Ceuta
* Melilla

根据票价类型，需要提供居民身份证明，例如 `DNI` 或 `NIE`。

### 适用航线

只支持西班牙国内航线，且行程必须符合居民计划规则。

| 居民地区   | 允许的航线范围                       | 示例          |
| ------ | ----------------------------- | ----------- |
| 加那利群岛  | 西班牙任意机场 ↔ 加那利群岛任意机场           | `MAD → TFS` |
| 巴利阿里群岛 | 西班牙任意机场 ↔ 巴利阿里群岛任意机场          | `VLC → PMI` |
| 休达     | `JCU` ↔ `SVQ` / `XRY` / `AGP` | `JCU → AGP` |

### 折扣适用范围

居民折扣可作用于：

* base fare
* first baggage piece per passenger per segment
* infant fee
* mandatory seat selection fee

政府税费**不参与**折扣。

### 折扣码

在搜索请求中传 `residentCode`。

| 折扣类型         | `residentCode` | 折扣    |
| ------------ | -------------- | ----- |
| 家庭折扣         | `DSC2`         | `5%`  |
| 大家庭折扣        | `DSC3`         | `10%` |
| SARA 居民折扣    | `DSC1`         | `75%` |
| SARA + 家庭折扣  | `DSC4`         | `80%` |
| SARA + 大家庭折扣 | `DSC5`         | `85%` |

### 集成流程

{% stepper %}
{% step %}

### 搜索时传 `residentCode`

在搜索请求中传入 `residentCode`，以获取居民价。

如果旅客和航线都符合条件，搜索结果会返回折扣后价格。
{% endstep %}

{% step %}

### 验价并创建订单

后续按标准流程继续验价和建单。

只要初始搜索使用了 `residentCode`，后续步骤会继续沿用居民价逻辑。
{% endstep %}

{% step %}

### 在建单或出票流程中传 `residentInfo`

为每位符合条件的乘客传入居民证明字段。
{% endstep %}

{% step %}

### 航司做最终核验

航司会在出票后核验居民资格。
{% endstep %}
{% endstepper %}

### 搜索请求示例

```json
{
  "tripType": "1",
  "adultNum": 1,
  "childNum": 0,
  "infantNum": 0,
  "fromCity": "SVQ",
  "toCity": "OVD",
  "fromDate": "20251103",
  "retDate": "20250603",
  "includeMultipleFareFamily": true,
  "currency": "",
  "requestSource": "",
  "residentCode": "DSC2"
}
```

### 必需的乘客证明字段

为每位符合条件的乘客传 `residentInfo`。

| 字段                | 说明                             |
| ----------------- | ------------------------------ |
| `docType`         | 证件类型。支持 `D`、`E`、`U`            |
| `docNum`          | 当 `docType` 为 `D` 或 `E` 时必填    |
| `municipality`    | `DSC1`、`DSC4`、`DSC5` 必填        |
| `largeFamilyCert` | `DSC2`、`DSC3`、`DSC4`、`DSC5` 必填 |
| `community`       | `DSC2`、`DSC3`、`DSC4`、`DSC5` 必填 |

### 建单请求示例

```json
{
  "cid": "******",
  "sessionId": "5475cdb2-ce22-4e52-8c2f-8ef2e81e462c",
  "passengers": [
    {
      "name": "TEST/ONE",
      "passengerType": 0,
      "birthday": "19900101",
      "gender": "M",
      "cardNum": "00000000",
      "cardType": "PP",
      "cardIssuePlace": "SG",
      "cardExpired": "20301231",
      "nationality": "SG",
      "ancillaries": [],
      "residentInfo": {
        "docType": "D",
        "docNum": "99999999Z",
        "municipality": "",
        "largeFamilyCert": "06-9999-99",
        "community": "502973"
      }
    }
  ],
  "contact": {
    "name": "TEST/TEST",
    "address": null,
    "postcode": null,
    "email": "test@test.com",
    "mobile": "0086-13928109091"
  },
  "requestSource": ""
}
```

### 按折扣码区分的字段要求

| `residentCode` | `docType` | `docNum`                  | `municipality` | `largeFamilyCert` | `community` |
| -------------- | --------- | ------------------------- | -------------- | ----------------- | ----------- |
| `DSC2`         | 必填        | `docType` 为 `D` 或 `E` 时必填 | 非必填            | 必填                | 必填          |
| `DSC3`         | 必填        | `docType` 为 `D` 或 `E` 时必填 | 非必填            | 必填                | 必填          |
| `DSC1`         | 必填        | `docType` 为 `D` 或 `E` 时必填 | 必填             | 非必填               | 非必填         |
| `DSC4`         | 必填        | `docType` 为 `D` 或 `E` 时必填 | 必填             | 必填                | 必填          |
| `DSC5`         | 必填        | `docType` 为 `D` 或 `E` 时必填 | 必填             | 必填                | 必填          |

### 编码字段参考文件

下面两个文件可用于把名称映射成编码值。

#### Municipality 编码

`municipality` 是一个 6 位编码，由 `CPOR + CMUN + DC` 组成。

{% file src="<https://content.gitbook.com/content/ClIWQjtgO3wtMk0oYDks/blobs/1r16SxxCNoLvnFyI90AM/25codmun.xlsx>" %}

#### Community 编码

{% file src="<https://content.gitbook.com/content/ClIWQjtgO3wtMk0oYDks/blobs/PuerZ9Se7WS2y55o5tsd/community.xlsx>" %}

### 最终核验行为

Atlas 会在履约阶段把居民价信息传给航司。

航司会在出票后核验资格。\
如果核验失败：

* 订单不会自动取消
* 旅客可能需要在机场出示原件

请确保旅客提前准备好原始证明材料。

### 相关页面

* [搜索](https://resources.atriptech.com/api-wen-dang/ji-cheng-zhi-nan/yu-ding-liu-cheng-gai-lan/sou-suo)
* [创建订单](https://resources.atriptech.com/api-wen-dang/ji-cheng-zhi-nan/yu-ding-liu-cheng-gai-lan/chuang-jian-ding-dan)
* [支付与出票](https://resources.atriptech.com/api-wen-dang/ji-cheng-zhi-nan/yu-ding-liu-cheng-gai-lan/zhi-fu-yu-chu-piao)
* [特殊集成](https://resources.atriptech.com/api-wen-dang/ji-cheng-zhi-nan/te-shu-ji-cheng)