> ## 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.

# Official documents

> List the registry documents available for a company, retrieve ones already bought, and purchase new ones with organization credits.

Official documents are the authoritative filings a public registry issues for a company - company extracts (*visure*), filed annual accounts (*bilanci*), articles of association (*statuti*), protest records. They are PDFs issued by the registry, not data assembled by Syrto, so they cost credits.

Two tools cover them:

| Tool                              | Costs credits | What it does                                                                                           |
| --------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `syrto_list_official_documents`   | No            | What can be bought and for how much, what the organization already owns, and how many credits are left |
| `syrto_request_official_document` | **Yes**       | Buys one document                                                                                      |

<Warning>
  Purchases belong to the **whole organization**, not to the person who made them. A colleague may already have bought the document you are about to buy - `syrto_list_official_documents` is how you find out, and it costs no credits.
</Warning>

***

## `syrto_list_official_documents`

Lists the official registry documents available for a company, and retrieves ones already bought.

This tool spends no document credits and is safe to call repeatedly. It answers three questions at once: what can be bought and for how much, what this organization has already bought, and how many credits are left.

Use it:

* **Before every purchase.** It supplies the slug, the cost to confirm with the user, and any extra input the document needs, such as a fiscal year.
* **To retrieve a document already bought.** Download links expire after about 6 hours, and this re-issues them at no credit cost - so a dead link needs this tool, never another purchase.
* **To check whether a colleague already bought it.**

### Arguments

<ParamField query="company_id" type="string" required>
  The company ID from [`syrto_find_company`](/mcp/tools/find-company). Either statement basis works - documents belong to the legal entity, so the individual and consolidated IDs of one company return the same documents.
</ParamField>

<ParamField query="language" type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

### Returns

<ResponseField name="target" type="object">
  `id` (the `company_id` you passed), `name`, `consolidated`.
</ResponseField>

<ResponseField name="available_documents" type="object[]">
  Each with:

  * `slug` - pass this to `syrto_request_official_document`
  * `name` - human-readable document name
  * `description`
  * `credit_cost` - the price to confirm with the user
  * `inputs` - extra values this document needs, each with `key`, `label`, `required` and `kind` (for example a `YEAR` for filed accounts). An empty list means no extra input is needed
</ResponseField>

<ResponseField name="purchased_documents" type="object[]">
  What this organization already bought for this company, newest first - `slug`, `name`, `requested_at`, and a `download_url` valid for about 6 hours from now.
</ResponseField>

<ResponseField name="credit_balance" type="object | null">
  `available` and `reserved` credits for the organization. `available` is what a purchase draws on now; `reserved` is held by operations still in flight. Omitted when the credential has no organization the API can resolve credits for.
</ResponseField>

<ResponseField name="download_url_note" type="string">
  The link-expiry rule, worth passing on to anyone you give a link to.
</ResponseField>

***

## `syrto_request_official_document`

Buys one official registry document for a company. **This spends the organization's credits.**

### Before buying

1. Call `syrto_list_official_documents` for the slug, the exact `credit_cost` and any required input.
2. Tell the user the document name and its credit cost, and get their explicit agreement to spend it.
3. Pass that cost as `expected_credit_cost`. The purchase is refused if the live price differs, which catches a price that moved since you read the catalogue - it does not establish that anyone agreed to it, so step 2 still stands on its own.

<Warning>
  The duplicate and price checks run just before the purchase, not atomically with it. They catch a mistake rather than guarantee against one: two purchases of the same document issued at the same moment can both go through.
</Warning>

### When a repeat costs nothing

Two independent things decide whether a repeat is charged:

* The registry API deduplicates a dispatched purchase intent - same company, document, year and `force_new` - for **24 hours**, returning the first document rather than charging again.
* Separately, this tool refuses a document the organization already owns, whether or not that window has passed, **unless** `force_new` is `true`.

So a plain repeat stays protected after 24 hours by the second rule, while a repeat of an intent that already carried `force_new: true` is protected only by the first, and buys a second copy once the window passes. Read the catalogue - which costs nothing - before repeating a forced purchase.

### Timeouts and retries

The call is synchronous and slow: the registry produces the document while the request is open, which usually takes seconds but can take several minutes.

If it times out or fails, call it again with the **same purchase intent** - the same company, document, year and `force_new`. The repeat either returns the first document or reports that the organization already owns it, with a working link, and inside 24 hours neither is a second charge. `expected_credit_cost` and `language` are not part of the intent, so if the price has moved, agree the new figure with the user and send that - it is still the same purchase. If the repeat reports the request is still being processed, wait about 30 seconds and call again.

### Arguments

<ParamField query="company_id" type="string" required>
  The company to buy the document for. Either statement basis works.
</ParamField>

<ParamField query="document_slug" type="string" required>
  Which document, from `syrto_list_official_documents` - for example `"it.company.visura_ordinaria"`.
</ParamField>

<ParamField query="expected_credit_cost" type="integer" required>
  That document's `credit_cost`, as shown to the user.
</ParamField>

<ParamField query="year" type="integer">
  The fiscal year, for documents whose `inputs` require one - filed accounts, typically.
</ParamField>

<ParamField query="force_new" type="boolean">
  Buy another copy of a document already owned - including the same document for a different year, which is the one case the duplicate check cannot distinguish. Charges in full. Default `false`.
</ParamField>

<ParamField query="language" type="string">
  `"en"` for English (default) or `"it"` for Italian.
</ParamField>

### Returns

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

<ResponseField name="document" type="object">
  `slug`, `name`, `requested_at`, and `download_url` - valid for about 6 hours. `syrto_list_official_documents` re-issues it at no credit cost.
</ResponseField>

<ResponseField name="credit_cost" type="integer">
  The document's catalogue price at the time of purchase. The registry API does not report the amount it actually charged, so this is the quoted price rather than a confirmed debit.
</ResponseField>

<ResponseField name="replayed" type="boolean">
  `true` when this call returned a document the organization already had, because an identical purchase within the last 24 hours is not charged twice - nothing was spent on this call.

  `false` is not the opposite proof: it is the normal value for a real purchase, and also what two simultaneous identical calls produce.
</ResponseField>

<ResponseField name="download_url_note" type="string">
  The link-expiry rule; pass it on with the link.
</ResponseField>

## Example

**1. Read the catalogue (free):**

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

**2. Buy the one the user agreed to:**

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