# Servizio web XML v4.1: modifiche rispetto alla v4

## Panoramica

La versione 4.1 aggiunge la conversione facoltativa degli importi monetari nella valuta scelta, la probabilità di insolvenza nel parere di credito, i dati dettagliati dei marchi e un punto di estensione per i campi futuri. Tutte le aggiunte sono facoltative. Il namespace non cambia: `http://infoproff.com/`.

| Schema | v4 | v4.1 |
| --- | --- | --- |
| Rapporto | `.../v4/report.xsd` | `.../v4.1/report.xsd` |
| Richiesta | `.../v4/order.xsd` | `.../v4.1/order.xsd` |
| Calcolatore del parere di credito | `.../v4/creditopinioncalculator.xsd` | invariato |

**Compatibilità.** Abbiamo cercato di ridurre al minimo le modifiche allo schema. Qualsiasi rapporto valido secondo lo schema v4 è valido anche secondo lo schema v4.1. Tuttavia, un rapporto v4.1 non è valido secondo lo schema v4. Può contenere elementi che non esistono nella v4, ad esempio `probability_of_default` e `converted`.

Se convalidate le risposte con lo schema XML, al passaggio al servizio v4.1 passate anche alla convalida con lo schema v4.1.

## Modifiche principali

1. **Conversione in un'altra valuta.** Nella richiesta del rapporto è stato aggiunto il nuovo parametro `currency`. Alla fine di ogni record con importi monetari compare l'elemento `converted`, che contiene il tasso di cambio e gli importi convertiti nella valuta scelta.
2. **Marchi.** Sono stati aggiunti nuovi elementi: titolare, stato, numero di registrazione, classi NICE, paesi designati, data di scadenza della registrazione e logo in formato base64.
3. **Probabilità di insolvenza.** Nel parere di credito è stato aggiunto il nuovo elemento `probability_of_default`.
4. **Allentamento dei vincoli dello schema.** Alcuni elementi sono diventati facoltativi e la lunghezza minima dei codici di registrazione è stata ridotta a un carattere. In questo modo i rapporti con dati incompleti superano la convalida con lo schema.
5. **Estensibilità dello schema.** È stato aggiunto l'elemento `extension`, che consentirà di aggiungere nuove sezioni senza pubblicare una nuova versione dello schema.

## Richiesta: valuta di destinazione

`GetReportRequest` contiene il nuovo elemento facoltativo `currency`, posizionato dopo `lang`. Il valore è un codice valuta ISO 4217 in maiuscolo, ad esempio `USD`. Lo schema rifiuta i codici in minuscolo o incompleti (`usd`, `US`).

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

Senza `currency`, oppure con `xsi:nil="true"`, il rapporto contiene solo le valute originali, come nella v4.

## Conversione di valuta

Se la richiesta contiene `currency`, ogni importo monetario resta nel suo elemento originale e nella sua valuta originale. Come ultimo elemento figlio dello stesso elemento padre viene aggiunto un elemento `converted` con gli importi convertiti. Gli elementi figli di `converted` hanno gli stessi nomi degli elementi originali.

```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>
```

| Attributo | Significato |
| --- | --- |
| `currency` | Valuta di destinazione (ISO 4217) |
| `src_currency` | Valuta originale degli importi |
| `rate` | Tasso incrociato: unità della valuta di destinazione per unità della valuta originale |
| `rate_date` | Data del tasso effettivamente applicato (il più vicino disponibile alla data dei dati originali) |
| `rate_source` | Fonte del tasso: `ECB`, `other` o `same` (le valute coincidono, tasso `1`) |
| `scale` | Scala degli importi convertiti: `1`, `1000`, `1000000` o `1000000000` |
| `id`, `rate_ref` | Collegamento tra il tasso e gli importi nei bilanci (vedi sotto) |

Importo convertito (la scala originale è presa dall'elemento originale):

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

`converted` non viene restituito se non c'è nulla da convertire o se il tasso non viene trovato. Se la valuta originale coincide con la valuta di destinazione, `converted` viene restituito con tasso `1` e fonte `same`.

`negative_information/debts/item` può contenere due elementi `converted`. Il primo contiene `amount` e `remainder` nella valuta `currency`, e anche `penalty` se `penalty_currency` coincide con `currency` o non è indicata. Il secondo contiene `penalty` e viene restituito se `penalty_currency` è diversa da `currency`.

**Bilanci.** In ogni `position` viene restituito `<converted rate_ref="..."><value>...</value></converted>` senza attributi del tasso. Il tasso è indicato una sola volta per bilancio: in un elemento `converted` vuoto con l'`id` corrispondente alla fine di `financial_statement`. L'`id` è valido solo all'interno di un singolo rapporto. Al download successivo il valore di `id` può cambiare.

```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"/>
```

Le voci del documento di tipo «Key Ratios» non vengono convertite, perché contengono valori non monetari. Fa eccezione Working capital.

**Dove compare la conversione**

| Elemento del rapporto | Importi convertiti |
| --- | --- |
| `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` delle voci |
| `paid_taxes/item` | `amount` |
| `tenders/item` | `amount` |

## Marchi

`general_data/trade_names_data/item` contiene ora i dati di registrazione del marchio. Tutti i nuovi elementi sono stati aggiunti come facoltativi per la compatibilità con lo schema v4. Si trovano tra `name` e le date.

| Elemento | Contenuto |
| --- | --- |
| `owner_name` | Titolare del marchio |
| `status` | Stato della registrazione, con gli attributi `key` e `lang` |
| `number` | Numero di registrazione |
| `nice_classification/class` | Classi NICE, nell'ordine della fonte |
| `designations/item/country_code` | Paesi in cui il marchio è designato, ISO 3166 alpha-3 |
| `expiry_date` | Data di scadenza della registrazione |
| `logo` | Immagine del marchio in base64, con l'attributo `mime_type` (ad esempio `image/jpeg`) |
| `extension` | Elementi aggiuntivi (vedi «Estensione») |

## Parere di credito: probabilità di insolvenza

`credit_opinions/item` contiene il nuovo elemento facoltativo `probability_of_default`, posizionato dopo `rating_description`. È la probabilità di insolvenza nei pagamenti nei prossimi 12 mesi, in percentuale, con due cifre decimali (`13.36` significa 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>
```

## Vincoli allentati

Alcuni elementi obbligatori nella v4 ora possono essere assenti o vuoti. In questo modo i rapporti con dati di origine incompleti restano validi. Se il vostro parser si aspetta questi elementi, tenete conto della loro possibile assenza.

| Elemento | v4 | v4.1 |
| --- | --- | --- |
| `country_economic_overview/data_transparency_index` | Obbligatorio | Facoltativo |
| `country_economic_overview/country_development_indicators` | Obbligatorio | Facoltativo; non viene restituito se non ci sono indicatori per il paese |
| `country_economic_overview/economic_forecast` | Obbligatorio | Facoltativo; non viene restituito se nessuna previsione è stata pubblicata entro la data del rapporto |
| `assets_data/vehicles/item/value` | Obbligatorio | Facoltativo; non viene restituito se il valore non è noto |
| `tenders/item/amount` | Obbligatorio, senza `nil` | Può essere `xsi:nil="true"` se l'importo non è noto |
| `registration_code`, `registration_data/item/code` | Da 3 a 64 caratteri | Da 1 a 64 caratteri |

## Estensione

Il nuovo elemento facoltativo `extension` ci consente di aggiungere campi senza pubblicare una nuova versione dello schema. È l'ultimo elemento figlio di `report` e di `trade_names_data/item`.

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

Lo schema non convalida il contenuto di `extension` ed è ammessa una nidificazione di qualsiasi profondità. Annunciamo e descriviamo separatamente i campi che vi compaiono. Ignorate gli elementi che non riconoscete.