Skip to main content
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:
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.

​
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

​
string
required
The company ID from syrto_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.
​
string
"en" for English (default) or "it" for Italian.

​
Returns

​
object
id (the company_id you passed), name, consolidated.
​
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
​
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.
​
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.
​
string
The link-expiry rule, worth passing on to anyone you give a link to.

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

​
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

​
string
required
The company to buy the document for. Either statement basis works.
​
string
required
Which document, from syrto_list_official_documents - for example "it.company.visura_ordinaria".
​
integer
required
That document’s credit_cost, as shown to the user.
​
integer
The fiscal year, for documents whose inputs require one - filed accounts, typically.
​
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.
​
string
"en" for English (default) or "it" for Italian.

​
Returns

​
object
id, name, consolidated.
​
object
slug, name, requested_at, and download_url - valid for about 6 hours. syrto_list_official_documents re-issues it at no credit cost.
​
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.
​
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.
​
string
The link-expiry rule; pass it on with the link.

​
Example

1. Read the catalogue (free):
2. Buy the one the user agreed to: