# XML-веб-сервис v4.1: изменения относительно v4

## Обзор

Версия 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`. Первый содержит `amount` и `remainder` в валюте `currency`, а также `penalty`, если `penalty_currency` совпадает с `currency` или не указана. Второй содержит `penalty` и выводится, если `penalty_currency` отличается от `currency`.

**Финансовая отчётность.** В каждой `position` выводится `<converted rate_ref="..."><value>...</value></converted>` без атрибутов курса. Курс указывается один раз на отчёт: в пустом элементе `converted` с соответствующим `id` в конце `financial_statement`. `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`, допускается вложенность любой глубины. О полях, которые там появляются, мы сообщаем и описываем их отдельно. Незнакомые элементы пропускайте.