# XML 网络服务 v4.1：相对于 v4 的变更

Sep 30, 2026 · @Vitaly

## 概述

4.1 版本新增：可选地将货币金额换算为您选择的货币、信用意见中的违约概率、详细的商标数据，以及用于未来字段的扩展点。所有新增内容均为可选。命名空间保持不变：`http://infoproff.com/`。

| 架构 | v4 | v4.1 |
| --- | --- | --- |
| 报告 | `.../v4/report.xsd` | `.../v4.1/report.xsd` |
| 请求 | `.../v4/order.xsd` | `.../v4.1/order.xsd` |
| 信用意见计算器 | `.../v4/creditopinioncalculator.xsd` | 无变更 |

**兼容性。** 我们尽量减少了对架构的修改。任何符合 v4 架构的报告同样符合 v4.1 架构。但是，v4.1 报告不符合 v4 架构。它可能包含 v4 中不存在的元素，例如 `probability_of_default` 和 `converted`。

如果您按 XML 架构校验响应，请在切换到 v4.1 服务时，同时将校验切换到 v4.1 架构。

## 主要变更

1. **换算为其他货币。** 报告请求中新增参数 `currency`。在每条包含货币金额的记录末尾，会出现 `converted` 元素，其中包含汇率以及换算为所选货币的金额。
2. **商标。** 新增元素：所有人、状态、注册号、NICE 类别、指定国家、注册到期日以及 base64 格式的标志。
3. **违约概率。** 信用意见中新增元素 `probability_of_default`。
4. **放宽架构限制。** 部分元素改为可选，注册代码的最小长度减少为一个字符。这样，数据不完整的报告也能通过架构校验。
5. **架构可扩展性。** 新增元素 `extension`，可在不发布新架构版本的情况下添加新的部分。

## 请求：目标货币

`GetReportRequest` 中新增可选元素 `currency`，位于 `lang` 之后。其值为大写的 ISO 4217 货币代码，例如 `USD`。架构会拒绝小写或不完整的代码（`usd`、`US`）。

```xml
<GetReportRequest>
    <order_id>119641</order_id>
    <lang>en</lang>
    <currency>USD</currency>
</GetReportRequest>
```

如果不提供 `currency`，或设置为 `xsi:nil="true"`，报告仅包含原始货币，与 v4 相同。

## 货币换算

如果请求中包含 `currency`，每个货币金额仍保留在原始元素中，并使用原始货币。在同一父元素的末尾会添加一个 `converted` 元素，其中包含换算后的金额。`converted` 的子元素名称与原始元素相同。

```xml
<item>
    <issued_capital>1612640</issued_capital>
    ...
    <start_date>2020-09-11</start_date>
    ...
    <converted currency="USD" scale="1" rate="1.1812" rate_date="2020-09-11"
               rate_source="ECB" src_currency="EUR">
        <issued_capital>1904850.37</issued_capital>
    </converted>
</item>
```

| 属性 | 含义 |
| --- | --- |
| `currency` | 目标货币（ISO 4217） |
| `src_currency` | 金额的原始货币 |
| `rate` | 交叉汇率：每单位原始货币对应的目标货币数量 |
| `rate_date` | 实际使用的汇率日期（最接近原始数据日期的可用汇率） |
| `rate_source` | 汇率来源：`ECB`、`other` 或 `same`（货币相同，汇率为 `1`） |
| `scale` | 换算后金额的单位：`1`、`1000`、`1000000` 或 `1000000000` |
| `id`、`rate_ref` | 财务报表中汇率与金额之间的关联（见下文） |

换算后的金额（原始单位取自原始元素）：

```latex
\text{converted} = \frac{\text{original} \times \text{original scale} \times \text{rate}}{\text{scale}}
```

如果没有需要换算的金额或找不到汇率，则不输出 `converted`。如果原始货币与目标货币相同，则输出 `converted`，汇率为 `1`，来源为 `same`。

`negative_information/debts/item` 中可能有两个 `converted` 元素。第一个包含 `currency` 货币的 `amount` 和 `remainder`；如果 `penalty_currency` 与 `currency` 相同或未指定，还包含 `penalty`。第二个包含 `penalty`，仅当 `penalty_currency` 与 `currency` 不同时输出。

**财务报表。** 每个 `position` 中输出 `<converted rate_ref="..."><value>...</value></converted>`，不带汇率属性。每份报表只给出一次汇率：位于 `financial_statement` 末尾、带有对应 `id` 的空 `converted` 元素中。`id` 仅在同一份报告内有效。下次下载时，`id` 的值可能会改变。

```xml
<position>
    <position_code>1000</position_code>
    <value>161047000.00</value>
    <converted rate_ref="fx_fs_45c963c5"><value>197620773.70</value></converted>
</position>
...
<converted id="fx_fs_45c963c5" currency="USD" scale="1" rate="1.2271"
           rate_date="2020-12-31" rate_source="ECB" src_currency="EUR"/>
```

类型为“Key Ratios”的文档中的项目不进行换算，因为它们包含非货币值。Working capital 除外。

**换算输出位置**

| 报告元素 | 换算的值 |
| --- | --- |
| `summary/credit_rating_limit` | `credit_rating_limit` |
| `summary/latest_turnovers/item` | `value` |
| `credit_opinions/item` | `credit_limit`、`latest_turnover_range` |
| `general_data/capital_data/item` | `issued_capital`、`share_value`、`authorized_capital`、`paid_amount` |
| `shareholders/item` | `share_amount` |
| `subsidiaries_data/item` | `share_book_value` |
| `export_import_data/*/item`、`.../details/item` | `total_amount`、`amount` |
| `assets_data/real_estate_data/item` | `value` |
| `assets_data/vehicles/item` | `value` |
| `commercial_pledge_data/item/pledge_amounts/item` | `pledge_amount` |
| `negative_information/litigations/item` | `amount_of_claim` |
| `negative_information/debts/item` | `amount`、`remainder`、`penalty` |
| `financial_statements_data/financial_statement` | 项目的 `value` |
| `paid_taxes/item` | `amount` |
| `tenders/item` | `amount` |

## 商标

`general_data/trade_names_data/item` 现在包含商标注册数据。为了与 v4 架构兼容，所有新元素均为可选。它们位于 `name` 与日期之间。

| 元素 | 内容 |
| --- | --- |
| `owner_name` | 商标所有人 |
| `status` | 注册状态，带有 `key` 和 `lang` 属性 |
| `number` | 注册号 |
| `nice_classification/class` | NICE 类别，按来源中的顺序 |
| `designations/item/country_code` | 商标有效的国家，ISO 3166 alpha-3 |
| `expiry_date` | 注册到期日 |
| `logo` | base64 格式的商标图像，带有 `mime_type` 属性（例如 `image/jpeg`） |
| `extension` | 附加元素（见“扩展”） |

## 信用意见：违约概率

`credit_opinions/item` 中新增可选元素 `probability_of_default`，位于 `rating_description` 之后。它表示未来 12 个月内的付款违约概率，以百分比表示，保留两位小数（`13.36` 表示 13.36%）。

```xml
<credit_rating>B</credit_rating>
<rating_description key="7603" lang="en">Normal risk.</rating_description>
<probability_of_default>13.36</probability_of_default>
<credit_limit>3000000</credit_limit>
```

## 放宽的限制

部分在 v4 中必需的元素，现在可以缺失或为空。这样，源数据不完整的报告仍然有效。如果您的解析程序依赖这些元素，请考虑它们可能缺失的情况。

| 元素 | v4 | v4.1 |
| --- | --- | --- |
| `country_economic_overview/data_transparency_index` | 必需 | 可选 |
| `country_economic_overview/country_development_indicators` | 必需 | 可选；如果该国家没有指标，则不输出 |
| `country_economic_overview/economic_forecast` | 必需 | 可选；如果在报告日期前没有发布预测，则不输出 |
| `assets_data/vehicles/item/value` | 必需 | 可选；如果价值未知，则不输出 |
| `tenders/item/amount` | 必需，不可为 nil | 如果金额未知，可以为 `xsi:nil="true"` |
| `registration_code`、`registration_data/item/code` | 3 至 64 个字符 | 1 至 64 个字符 |

## 扩展

新增的可选元素 `extension` 使我们可以在不发布新架构版本的情况下添加字段。它是 `report` 和 `trade_names_data/item` 的最后一个子元素。

```xml
<extension>
    <mark_type>figurative</mark_type>
    <application>
        <number>2021/04512</number>
        <date>2021-04-14</date>
    </application>
</extension>
```

架构不校验 `extension` 的内容，允许任意深度的嵌套。我们会另行通知并说明其中出现的字段。请跳过无法识别的元素。