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

# Endpoint standard

> Il pacchetto standard di endpoint sulle aziende italiane: cosa restituisce ciascuno e quanto costa.

Il pacchetto standard copre dati aziendali, proprietà, bilanci, ricerca e aggregati di mercato sulle aziende italiane. Viene attivato per un'organizzazione in blocco: un'API predisposta con il pacchetto standard serve tutti gli endpoint qui sotto. La tua [specifica OpenAPI](https://docs.syrto.ai/it/api/openapi.md) resta l'elenco di riferimento per la tua key.

Ogni endpoint è disponibile anche, con dati sintetici e senza alcun addebito, nella [sandbox](https://docs.syrto.ai/it/api/sandbox.md). Gli schemi completi di richiesta e risposta sono nel [riferimento interattivo](https://docs.syrto.ai/it/api/reference/standard-overview.md).

## Endpoint e crediti

I prezzi sono in crediti; il valore di un credito è definito nel tuo contratto. `meta.usage` in ogni risposta riporta quanto ha consumato la chiamata. Non viene addebitato nulla per un id non risolto, un anno non depositato o una pagina vuota, e gli errori non vengono mai addebitati.

| Endpoint | Crediti |
| - | - |
| [`GET /companies/{id}/overview`](https://docs.syrto.ai/it/api/reference/standard/company-overview) | 10 |
| [`POST /companies/anagraphic`](https://docs.syrto.ai/it/api/reference/standard/company-anagraphic) | 10 per record restituito |
| [`POST /companies/negativities`](https://docs.syrto.ai/it/api/reference/standard/company-negativities) | 10 per persona giuridica restituita |
| [`POST /companies/rna`](https://docs.syrto.ai/it/api/reference/standard/company-rna) | 10 per persona giuridica restituita |
| [`GET /companies/{id}/branches`](https://docs.syrto.ai/it/api/reference/standard/company-branches) | 5 |
| [`POST /companies/bundle`](https://docs.syrto.ai/it/api/reference/standard/company-bundle) | 25 per record restituito |
| [`POST /companies/structure`](https://docs.syrto.ai/it/api/reference/standard/company-structure) | 35 per persona giuridica restituita |
| [`GET /companies/{id}/financials`](https://docs.syrto.ai/it/api/reference/standard/company-financials) | 50, più 10 con `includeMarketData` |
| [`GET /companies/{id}/reclassified`](https://docs.syrto.ai/it/api/reference/standard/company-reclassified) | 70 |
| [`GET /companies/{id}/analysis`](https://docs.syrto.ai/it/api/reference/standard/company-analysis) | 150 con 5 anni inclusi, più 30 per ogni anno ulteriore restituito |
| [`GET /companies/{id}/spider`](https://docs.syrto.ai/it/api/reference/standard/company-spider) | 50 con 1 anno incluso, più 10 per ogni anno ulteriore restituito |
| [`GET /companies/{id}/similar`](https://docs.syrto.ai/it/api/reference/standard/company-similar) | 150 |
| [`POST /companies/search`](https://docs.syrto.ai/it/api/reference/standard/company-search) | Per azienda restituita, in base al livello di ricerca: base 3, plus 6, pro 10 |
| [`POST /market/base`](https://docs.syrto.ai/it/api/reference/standard/market-base) | 150, più 50 con una ripartizione |
| [`POST /market/pro`](https://docs.syrto.ai/it/api/reference/standard/market-pro) | 750, più 250 con una ripartizione |
| [`GET /metrics`](https://docs.syrto.ai/it/api/reference/standard/metrics) | Gratuito |

> [!NOTE]
>
> `similar` e i due endpoint di mercato rispondono `404` quando non trovano aziende comparabili o nessuna azienda con bilancio depositato. Questa risposta non viene mai addebitata.

## Base di addebito

* `negativities`, `rna` e `structure` addebitano una volta per persona giuridica: il record individuale e quello consolidato della stessa azienda contano una volta.
* Ogni altro endpoint addebita per record, o per chiamata, quindi il record individuale e quello consolidato di un'azienda contano separatamente.
* Un codice fiscale o una partita IVA si risolve sempre in un solo record, scelto da `statementBasis` (individuale per impostazione predefinita). Un'azienda viene addebitata due volte solo se vengono passati entrambi i suoi company id.
* Una chiamata di mercato ha un prezzo per chiamata, qualunque sia la dimensione dell'insieme. Omettere `filters` e `seedId`, o inviare `filters: {}`, aggrega tutta l'Italia allo stesso prezzo. L'extra per la ripartizione si paga una volta per chiamata.
* Il livello di ricerca è determinato dal filtro più avanzato usato, mai dai campi restituiti. Invia `maxTier` per fissare un tetto: un filtro oltre il tetto fallisce con `422` prima che venga eseguito qualsiasi lavoro. `limit` (1-200) limita la pagina, quindi `limit x prezzo del livello` limita qualsiasi chiamata di ricerca.

## Convenzioni

* **Struttura della risposta.** Il successo è `200 { data, meta }`, dove `meta` contiene `requestId`, `endpoint`, `usage` e `warnings`. `warnings` è sempre presente, vuoto quando non ci sono avvisi. Per la forma dei fallimenti vedi [errori](https://docs.syrto.ai/it/api/errors.md).
* **Riferimenti alle aziende.** `{id}` e gli `ids` dei batch accettano un company id (l'id Syrto di un record di bilancio) o un codice fiscale (partita IVA di 11 cifre o codice fiscale di 16 caratteri). Un codice fiscale si risolve nel record scelto da `statementBasis`.
* **Batch.** Gli endpoint batch accettano fino a 20 id e rispondono `{ items, notFound: [{ position, input, reason }] }`. Usano `POST` solo perché hanno un corpo; sono di sola lettura e idempotenti.
* **Null.** Ogni campo è sempre presente. Un valore sconosciuto è `null`, mai `false` o `0`.
* **Unità.** `pct` è una frazione (0,15 significa 15%), gli importi `eur` sono in euro, `eur_per_head` è per dipendente.
* **Lingua.** `language=it|en` localizza nomi ed etichette, mai i nomi dei campi o gli slug.
* **Anni.** Si usa l'ultimo bilancio depositato salvo che sia indicato `year`. Gli anni previsionali non vengono mai restituiti.
* **Date.** `financialStatementDate` è presente su ogni valore che deriva da un bilancio: la data di chiusura dell'esercizio.
* **Ordinamento della ricerca.** I risultati sono ordinati per denominazione, A-Z, salvo che `sortBy` chieda `matchScore` (richiede `semanticSearch`) o il valore di una metrica in un anno. `direction` è `desc` per impostazione predefinita.
* **Timeout.** Una chiamata oltre il limite di tempo è `504 upstream_timeout`, mai addebitata, con `Retry-After: 30`. La prima chiamata su un insieme ampio può essere lenta; la stessa chiamata dopo l'attesa è di solito veloce.
* **Rate limit.** Vedi [rate limit](https://docs.syrto.ai/it/api/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.