> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syrto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Documenti ufficiali

> Elenca i documenti camerali disponibili per un'azienda, recupera quelli già acquistati e acquistane di nuovi con i crediti dell'organizzazione.

I documenti ufficiali sono i documenti che un registro pubblico rilascia per un'azienda: visure, bilanci depositati, statuti, certificazioni sui protesti. Sono PDF emessi dal registro, non dati elaborati da Syrto, e per questo costano crediti.

Se ne occupano due strumenti:

| Strumento                         | Costa crediti | Che cosa fa                                                                                                |
| --------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| `syrto_list_official_documents`   | No            | Che cosa si può acquistare e a che prezzo, che cosa l'organizzazione possiede già e quanti crediti restano |
| `syrto_request_official_document` | **Sì**        | Acquista un documento                                                                                      |

<Warning>
  Gli acquisti appartengono all'**intera organizzazione**, non a chi li ha effettuati. Un collega potrebbe aver già acquistato il documento che stai per comprare: `syrto_list_official_documents` è il modo per scoprirlo, e non costa crediti.
</Warning>

***

## `syrto_list_official_documents`

Elenca i documenti camerali disponibili per un'azienda e recupera quelli già acquistati.

Questo strumento non spende crediti documento ed è sicuro da chiamare ripetutamente. Risponde a tre domande in una volta sola: che cosa si può acquistare e a quanto, che cosa questa organizzazione ha già acquistato e quanti crediti restano.

Usalo:

* **Prima di ogni acquisto.** Fornisce lo slug, il costo da confermare con l'utente e gli eventuali dati aggiuntivi richiesti dal documento, come l'anno fiscale.
* **Per recuperare un documento già acquistato.** I link di download scadono dopo circa 6 ore, e questo strumento li rigenera senza costo di crediti - quindi un link scaduto richiede questo strumento, mai un nuovo acquisto.
* **Per verificare se un collega lo ha già acquistato.**

### Argomenti

<ParamField query="company_id" type="string" required>
  L'ID aziendale da [`syrto_find_company`](/it/mcp/tools/find-company). Funziona con entrambe le basi di bilancio - i documenti appartengono all'entità giuridica, quindi l'ID individuale e quello consolidato della stessa azienda restituiscono gli stessi documenti.
</ParamField>

<ParamField query="language" type="string">
  `"en"` per inglese (predefinito) o `"it"` per italiano.
</ParamField>

### Risposta

<ResponseField name="target" type="object">
  `id` (il `company_id` che hai passato), `name`, `consolidated`.
</ResponseField>

<ResponseField name="available_documents" type="object[]">
  Ciascuno con:

  * `slug` - da passare a `syrto_request_official_document`
  * `name` - nome leggibile del documento
  * `description`
  * `credit_cost` - il prezzo da confermare con l'utente
  * `inputs` - i valori aggiuntivi richiesti da questo documento, ciascuno con `key`, `label`, `required` e `kind` (per esempio un `YEAR` per i bilanci depositati). Una lista vuota significa che non serve alcun dato aggiuntivo
</ResponseField>

<ResponseField name="purchased_documents" type="object[]">
  Ciò che questa organizzazione ha già acquistato per questa azienda, dal più recente - `slug`, `name`, `requested_at` e un `download_url` valido per circa 6 ore da adesso.
</ResponseField>

<ResponseField name="credit_balance" type="object | null">
  Crediti `available` e `reserved` dell'organizzazione. `available` è ciò su cui attinge un acquisto ora; `reserved` è trattenuto da operazioni ancora in corso. Omesso quando la credenziale non ha un'organizzazione per cui l'API possa risolvere i crediti.
</ResponseField>

<ResponseField name="download_url_note" type="string">
  La regola di scadenza dei link, utile da riferire a chiunque riceva un link.
</ResponseField>

***

## `syrto_request_official_document`

Acquista un documento camerale per un'azienda. **Questo spende i crediti dell'organizzazione.**

### Prima di acquistare

1. Chiama `syrto_list_official_documents` per lo slug, il `credit_cost` esatto e gli eventuali dati richiesti.
2. Comunica all'utente il nome del documento e il suo costo in crediti, e ottieni il suo consenso esplicito a spenderli.
3. Passa quel costo come `expected_credit_cost`. L'acquisto viene rifiutato se il prezzo corrente è diverso, il che intercetta un prezzo cambiato da quando hai letto il catalogo - non attesta che qualcuno lo abbia approvato, quindi il passo 2 resta indispensabile.

<Warning>
  I controlli su duplicati e prezzo vengono eseguiti immediatamente prima dell'acquisto, non in modo atomico con esso. Intercettano un errore, non lo escludono: due acquisti dello stesso documento emessi nello stesso istante possono andare a buon fine entrambi.
</Warning>

### Quando una ripetizione non costa nulla

Due meccanismi indipendenti determinano se una ripetizione viene addebitata:

* L'API del registro deduplica un'intenzione di acquisto già inviata - stessa azienda, documento, anno e `force_new` - per **24 ore**, restituendo il primo documento invece di addebitare di nuovo.
* Separatamente, questo strumento rifiuta un documento che l'organizzazione possiede già, che quella finestra sia trascorsa o meno, **a meno che** `force_new` non sia `true`.

Quindi una ripetizione semplice resta protetta anche dopo 24 ore dalla seconda regola, mentre la ripetizione di un'intenzione che già portava `force_new: true` è protetta solo dalla prima, e acquista una seconda copia una volta trascorsa la finestra. Leggi il catalogo - che non costa nulla - prima di ripetere un acquisto forzato.

### Timeout e ritentativi

La chiamata è sincrona e lenta: il registro produce il documento mentre la richiesta è aperta, cosa che di solito richiede secondi ma può richiedere diversi minuti.

Se va in timeout o fallisce, richiamala con la **stessa intenzione di acquisto** - stessa azienda, documento, anno e `force_new`. La ripetizione restituisce il primo documento oppure segnala che l'organizzazione lo possiede già, con un link funzionante, e entro le 24 ore né l'una né l'altra è un secondo addebito. `expected_credit_cost` e `language` non fanno parte dell'intenzione, quindi se il prezzo è cambiato concorda la nuova cifra con l'utente e invia quella - resta lo stesso acquisto. Se la ripetizione segnala che la richiesta è ancora in elaborazione, attendi circa 30 secondi e richiama.

### Argomenti

<ParamField query="company_id" type="string" required>
  L'azienda per cui acquistare il documento. Funziona con entrambe le basi di bilancio.
</ParamField>

<ParamField query="document_slug" type="string" required>
  Quale documento, da `syrto_list_official_documents` - per esempio `"it.company.visura_ordinaria"`.
</ParamField>

<ParamField query="expected_credit_cost" type="integer" required>
  Il `credit_cost` di quel documento, come mostrato all'utente.
</ParamField>

<ParamField query="year" type="integer">
  L'anno fiscale, per i documenti i cui `inputs` lo richiedono - tipicamente i bilanci depositati.
</ParamField>

<ParamField query="force_new" type="boolean">
  Acquista un'altra copia di un documento già posseduto - incluso lo stesso documento per un anno diverso, l'unico caso che il controllo sui duplicati non riesce a distinguere. Addebita l'intero costo. Predefinito `false`.
</ParamField>

<ParamField query="language" type="string">
  `"en"` per inglese (predefinito) o `"it"` per italiano.
</ParamField>

### Risposta

<ResponseField name="target" type="object">
  `id`, `name`, `consolidated`.
</ResponseField>

<ResponseField name="document" type="object">
  `slug`, `name`, `requested_at` e `download_url` - valido per circa 6 ore. `syrto_list_official_documents` lo rigenera senza costo di crediti.
</ResponseField>

<ResponseField name="credit_cost" type="integer">
  Il prezzo di listino del documento al momento dell'acquisto. L'API del registro non riporta l'importo effettivamente addebitato, quindi questo è il prezzo quotato e non un addebito confermato.
</ResponseField>

<ResponseField name="replayed" type="boolean">
  `true` quando questa chiamata ha restituito un documento che l'organizzazione già possedeva, perché un acquisto identico nelle ultime 24 ore non viene addebitato due volte - questa chiamata non ha speso nulla.

  `false` non è la prova del contrario: è il valore normale di un acquisto reale, ed è anche ciò che producono due chiamate identiche simultanee.
</ResponseField>

<ResponseField name="download_url_note" type="string">
  La regola di scadenza dei link; riferiscila insieme al link.
</ResponseField>

## Esempio

**1. Leggere il catalogo (gratuito):**

```json theme={null}
{
  "company_id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox"
}
```

**2. Acquistare quello concordato con l'utente:**

```json theme={null}
{
  "company_id": "Zm86SVRfMDE2NTQwMTAzNDVfVTox",
  "document_slug": "it.company.visura_ordinaria",
  "expected_credit_cost": 5
}
```