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

# La tua specifica API

> Scarica e visualizza la specifica OpenAPI della tua organizzazione con la tua API key, e genera un client tipizzato.

Poiché l'API Syrto è configurata per cliente, la tua specifica OpenAPI è il riferimento autorevole per la tua API - elenca esattamente gli endpoint, i parametri e la forma delle risposte predisposti per la tua organizzazione. Viene generata per ogni API key e limitata a ciò che quella key può chiamare, quindi è il modo più rapido per vedere cosa espone davvero la tua API.

<Tip>
  Vuoi prima vedere com'è fatta una specifica? Consulta il [riferimento interattivo](/it/api/reference/overview) per gli endpoint di esempio - viene reso allo stesso modo della tua specifica.
</Tip>

## Visualizzare la tua specifica

La tua specifica è servita come OpenAPI 3.1, in JSON o YAML. Entrambi gli endpoint richiedono la tua API key e non vengono mai addebitati. Crea una key nella [dashboard Syrto](https://dashboard.syrto.ai/api-keys) (solo amministratori), poi scaricala e salvala:

```bash theme={null}
# JSON
curl -s https://api.syrto.ai/openapi.json \
  -H "Authorization: Bearer $SYRTO_API_KEY" -o syrto-openapi.json

# YAML
curl -s https://api.syrto.ai/openapi.yaml \
  -H "Authorization: Bearer $SYRTO_API_KEY" -o syrto-openapi.yaml
```

Poi apri il file salvato in un qualsiasi visualizzatore OpenAPI per sfogliarlo in modo interattivo. Una buona opzione open source è lo [Swagger Editor](https://editor.swagger.io), che rende il file nel tuo browser - la specifica descrive la tua API ma non contiene mai la tua key. Altre opzioni: [Scalar](https://github.com/scalar/scalar) (`npx @scalar/cli`), Postman o un plugin OpenAPI per l'IDE.

<Note>
  Non esiste un visualizzatore della specifica integrato nella pagina, per scelta: la specifica è protetta dalla tua API key segreta. Scaricala con la tua key e visualizzala in uno strumento che controlli tu, anziché incollare la key in una pagina web.
</Note>

## Generare un client

La specifica è un contratto indipendente dal linguaggio, quindi puoi generare un client tipizzato dal file salvato con qualsiasi generatore OpenAPI:

```bash theme={null}
npx openapi-typescript syrto-openapi.json -o syrto.d.ts
```

Ogni operazione ha un `operationId` stabile (lo slug dell'endpoint), così i nomi dei metodi generati restano puliti, e il `code` di errore è un enum tipizzato che copre l'intera [tassonomia degli errori](/it/api/errors) - un client generato vede codici esatti, non una stringa generica.

## Versionamento

Il versionamento è per risorsa e compare nel nome della risorsa, solo quando una modifica romperebbe i chiamanti esistenti:

* La prima versione di un endpoint usa il nome pulito della risorsa - ad esempio `/companies/{taxId}/financials`.
* Una modifica non retrocompatibile viene rilasciata come un **nuovo** endpoint con suffisso `-vN` (ad esempio `/companies/{taxId}/financials-v2`). L'originale continua a funzionare ed è contrassegnato come `deprecated` nella specifica.
* Non esiste un prefisso globale `/v1` - ogni endpoint evolve in modo indipendente, e ogni versione è un'operazione distinta con il proprio schema.

Questo significa che un'integrazione esistente non si rompe mai in silenzio: una nuova versione principale è un nuovo URL a cui aderisci, e la vecchia continua a servire finché non migri.