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

# Introduzione

> Un'API REST personalizzata, per singolo cliente, per i dati finanziari di Syrto sulle aziende italiane.

<Info>
  L'API Syrto è un'offerta personalizzata, per singolo cliente. Syrto predispone un'API dedicata per un'organizzazione su richiesta, per casi d'uso specifici - non è un prodotto self-service pubblico. Questa sezione si applica solo se Syrto ha configurato un'API per la tua organizzazione. Per richiederne una, contatta il team commerciale.
</Info>

L'API Syrto è un livello REST sopra il database finanziario di Syrto. Ogni organizzazione ha la propria API, adattata al suo caso d'uso: gli endpoint disponibili, il loro prezzo e la forma delle risposte sono configurati per cliente. La tua [specifica OpenAPI](/it/api/openapi) - scaricata con la tua API key - è il riferimento autorevole per ciò che la tua API espone.

Le pagine di questa sezione documentano le convenzioni condivise da ogni API Syrto (autenticazione, struttura della risposta, errori, rate limit, versionamento) e illustrano endpoint di esempio che mostrano il tipo di risorse che Syrto può predisporre.

## URL di base

```
https://api.syrto.ai
```

Tutti gli endpoint sono serviti su HTTPS. La tua API key determina quale API dell'organizzazione raggiungi e quali endpoint puoi chiamare - vedi [Autenticazione](/it/api/authentication).

## I tuoi endpoint

Poiché gli endpoint sono configurati per cliente, non esiste un unico elenco fisso. Gli endpoint predisposti per la tua organizzazione sono descritti nella [tua specifica](/it/api/openapi), che puoi scaricare e visualizzare con la tua API key.

Gli [endpoint di esempio](/it/api/endpoints/company-financials) qui sotto mostrano il tipo di risorse che Syrto espone comunemente - la tua API può includerne alcuni, tutti o varianti su misura:

<CardGroup cols={2}>
  <Card title="Dati finanziari" icon="chart-line" href="/it/api/endpoints/company-financials">
    Uno snapshot finanziario di una singola azienda tramite codice fiscale.
  </Card>

  <Card title="Credit report" icon="file-shield" href="/it/api/endpoints/company-credit-report">
    Un credit report completo - identità, indicatori di rischio, assetto proprietario, cariche e dati finanziari recenti.
  </Card>

  <Card title="Profilo aziendale" icon="building" href="/it/api/endpoints/company-profile">
    Un profilo che si adatta alla dimensione: peer per le grandi aziende, una vista di rischio più approfondita per le più piccole.
  </Card>

  <Card title="Report aziendale" icon="file-invoice" href="/it/api/endpoints/company-report">
    Un report completo con bilanci pluriennali, sedi secondarie e titolari effettivi.
  </Card>
</CardGroup>

## Struttura della risposta

Ogni risposta di successo è un oggetto JSON con due campi di primo livello: `data` e `meta`.

```json theme={null}
{
  "data": { "...": "risorsa specifica dell'endpoint" },
  "meta": {
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "endpoint": "company-financials",
    "usage": { "quantity": 5, "unit": "credits" }
  }
}
```

<ResponseField name="data" type="object">
  La risorsa dell'endpoint. In una risposta `200` il campo `data` è sempre presente e non nullo - una richiesta che non corrisponde ad alcuna azienda restituisce invece [`404 not_found`](/it/api/errors), mai un `200` con corpo vuoto.
</ResponseField>

<ResponseField name="meta" type="object">
  Metadati sulla chiamata:

  * `requestId` - un id univoco della richiesta (`req_` seguito da un UUID). Citalo nelle richieste di supporto.
  * `endpoint` - lo slug dell'endpoint che ha servito la richiesta.
  * `usage` - la misura d'uso registrata per la chiamata, come `{ quantity, unit }`.
</ResponseField>

## Header della risposta

Oltre al corpo JSON, le risposte includono alcuni header:

| Header                                                              | Quando                      | Descrizione                                                  |
| ------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------ |
| `X-Request-Id`                                                      | ogni risposta               | L'id della richiesta, uguale a `meta.requestId`.             |
| `X-Syrto-Endpoint`                                                  | successo                    | Lo slug dell'endpoint che ha servito la richiesta.           |
| `X-Usage-Quantity`                                                  | successo                    | La quantità d'uso registrata per la chiamata.                |
| `X-Usage-Unit`                                                      | successo                    | L'unità d'uso (es. `credits` o `calls`).                     |
| `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` | ogni chiamata a un endpoint | Il tuo budget attuale di [rate limit](/it/api/rate-limits).  |
| `Retry-After`                                                       | `429` / `503`               | Secondi da attendere prima di riprovare, quando applicabile. |

## Avvio rapido

Una volta che Syrto ha predisposto la tua API e disponi di una key, chiama uno dei tuoi endpoint (il percorso esatto dipende dalla tua specifica):

```bash theme={null}
curl -H "Authorization: Bearer $SYRTO_API_KEY" \
  https://api.syrto.ai/companies/01654010345/financials
```

Una chiamata riuscita restituisce `200` con un corpo `{ data, meta }`. Se la key manca o non è valida ottieni `401`; se nessuna azienda corrisponde, `404`. Vedi [Errori](/it/api/errors) per l'elenco completo.

## Supporto

* **Email:** [support@syrto.ai](mailto:support@syrto.ai)
* **Sito web:** [syrto.ai](https://www.syrto.ai)