Guida introduttiva

Questa guida ti accompagna nella valutazione del tuo primo strumento a reddito fisso utilizzando l'API. Al termine, saprai come calcolare il prezzo, il rendimento e i flussi di cassa di un'obbligazione.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Una chiave API valida (contatta il tuo amministratore se non ne hai una)
• curl o un client HTTP a tua scelta
• Familiarità di base con i concetti delle obbligazioni (cedole, scadenza, rendimento a scadenza)

note

Tutti gli endpoint dell'API richiedono l'autenticazione tramite l'header Authorization. Gli esempi seguenti presuppongono che tu abbia impostato la tua chiave nella variabile d'ambiente API_KEY.

Il tuo primo calcolo

L'operazione più comune consiste nel valutare un'obbligazione partendo dal suo prezzo per ottenere il rendimento, oppure dal suo rendimento per ottenere il prezzo. L'API espone questo tramite l'endpoint /v1/calculate.

Passo 1: Costruire la richiesta

Ogni richiesta di calcolo deve identificare lo strumento, descrivere l'input che stai fornendo e indicare quali risultati vuoi ottenere. Ecco una richiesta minima che valuta un'obbligazione a partire dal suo prezzo clean:

{
  "instrument_id": "US912828YK89",
  "input_kind": "PRICE_QUANTITY",
  "rate_type": "EFFECTIVE",
  "day_count": "ACT/ACT.ICMA",
  "options": {
    "with_cashflows": true
  }
}

I campi hanno il seguente significato:

Campo	Descrizione
instrument_id	L'identificativo dello strumento da valutare (ISIN, CUSIP o codice interno).
input_kind	Cosa stai fornendo. Usa PRICE_QUANTITY quando parti da un prezzo.
rate_type	Come viene composto il rendimento: NOMINAL o EFFECTIVE.
day_count	La convenzione di conteggio dei giorni, ad esempio ACT/ACT.ICMA o BUS/252.
options	Flag aggiuntivi. Imposta with_cashflows su true per ricevere il calendario completo dei flussi di cassa.

Passo 2: Inviare la richiesta

curl -X POST https://api.example.com/v1/calculate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument_id": "US912828YK89",
    "input_kind": "PRICE_QUANTITY",
    "rate_type": "EFFECTIVE",
    "day_count": "ACT/ACT.ICMA",
    "options": { "with_cashflows": true }
  }'

suggerimento

Se lavori con titoli di Stato brasiliani, usa day_count impostato su BUS/252, che conteggia i giorni lavorativi secondo il calendario ANBIMA. Per la maggior parte delle obbligazioni denominate in euro, ACT/ACT.ICMA è il valore predefinito corretto.

Passo 3: Leggere la risposta

La risposta contiene i risultati calcolati. Quando richiedi un clean_price come input, l'API restituisce il yield corrispondente, insieme ad altri valori derivati:

{
  "calculation_code": "OK",
  "yield": 0.0432,
  "clean_price": 98.75,
  "amount_kind": "AT_MATURITY",
  "cashflows": [
    { "date": "2025-06-30", "amount": 2.125 },
    { "date": "2025-12-31", "amount": 2.125 }
  ]
}

Il campo calculation_code indica sempre l'esito. Un valore pari a OK significa che il calcolo è andato a buon fine. Eventuali altri valori segnalano che alcuni input necessitano di attenzione.

Comprendere i tipi di input

L'API supporta diversi valori di input_kind a seconda di cosa conosci in anticipo:

• PRICE_QUANTITY — parti da un prezzo e ottieni il rendimento. È il caso d'uso più comune.
• Quando parti da un rendimento, l'API risolve il prezzo per te.

Il valore rate_type controlla l'interpretazione del rendimento. Un rendimento NOMINAL è composto in modo semplice all'interno del periodo, mentre un rendimento EFFECTIVE tiene conto della capitalizzazione composta. La scelta sbagliata produce prezzi che si discostano leggermente da quelli del tuo sistema di controparte, quindi verifica sempre questa impostazione confrontandola con i tuoi dati di riferimento.

Passi successivi

• Consulta il riferimento dei tipi di calcolo per l'elenco completo delle modalità supportate.
• Approfondisci le convenzioni di conteggio dei giorni per capire come ogni convenzione influisce sui ratei.
• Per le obbligazioni a scadenza unica, vedi come amount_kind impostato su AT_MATURITY modifica il calendario dei flussi di cassa.

informazioni

Tutte le date nelle risposte dell'API sono in UTC e seguono il formato ISO 8601. I flussi di cassa sono ordinati cronologicamente, dalla data più vicina alla più lontana.