oneapi
Autentificare
Financiar v1 / TitluriStat

Randament la o maturitate cerută

Randamentul suveran la o maturitate care nu are punct publicat — „cât e la 7 ani?" — obţinut
prin interpolare între punctele vecine.

Metoda e liniară, şi ruta nu pretinde altceva. Măsurat pe toate cele 3.929 de zile,
reconstruind puncte publicate din vecinii lor mai îndepărtaţi: eroarea medie e 0,06–0,15 puncte, cu
maxime de 0,43–0,81. Acelea sunt goluri de 2–7 ori mai mari decât cele reale, deci între puncte
adiacente eroarea e mult mai mică — dar cifrele arată că curba are curbură, iar liniarul e o
aproximare. De aceea metoda e declarată şi ambele puncte vecine vin în răspuns, în intre: cine
vrea alt model are de unde porni.

Nu se extrapolează. Peste 10 ani sau sub 6 luni, răspunsul e 404 cu in_afara_curbei şi
intervalul acoperit — extrapolarea unei curbe de randament dincolo de ultimul punct e nesigură, iar
un număr plauzibil şi nefondat e exact ce evităm.

Un punct publicat cerut exact se întoarce ca atare, cu interpolat: false, nu recalculat.

Bid şi ask se interpolează separat, deci rezultă şi un spread la maturitatea cerută.

GET
https://oneapi.ro/api/financiar/v1/titluri-stat/randament

Parametri de interogare

NumeTipDescriereValori acceptate
maturitateobligatoriu string Obligatoriu. Trei scrieri, neambigue: 84 (luni), 7Y (ani), 18M (luni). Între 6 luni şi 10 ani. ex. 7Yex. 18Mex. 3M
dataopțional string | null Opţional, YYYY-MM-DD. Implicit ultimul fixing publicat. Nu poate fi în viitor. ex. 2024-06-14

Cum se comportă

  • Randamentul suveran românesc la o maturitate care nu are punct publicat. BNR publică cinci puncte — 6 luni, 12 luni, 3, 5 şi 10 ani; ruta răspunde la întrebarea „cât e la 7 ani?", interpolând între vecini.
  • Metoda e liniară şi ruta nu pretinde altceva. Măsurat pe toate cele 3.929 de zile, reconstruind fiecare punct publicat din vecinii lui mai îndepărtaţi: eroarea medie e 0,06 puncte la 12 luni, 0,16 la 3 ani, 0,14 la 5 ani, cu maxime de 0,43, 0,56 şi 0,81. Acelea sunt goluri de 2–7 ori mai mari decât cele reale, deci între puncte adiacente eroarea e mult mai mică — dar cifrele arată clar că curba are curbură, iar liniarul rămâne o aproximare.
  • De aceea metoda e declarată în răspuns, iar în intre vin ambele puncte vecine, întregi. Cine vrea alt model — spline, Nelson-Siegel — are de unde porni, fără să mai ceară curba separat.
  • Nu se extrapolează. Sub 6 luni sau peste 10 ani răspunsul e 404 in_afara_curbei, cu intervalul acoperit. Prelungirea unei curbe de randament dincolo de ultimul punct e nesigură, iar un număr plauzibil şi nefondat e exact ce evităm.
  • O maturitate cu punct publicat se întoarce ca atare, cu interpolat: false şi metoda: null — valoarea din fixing, nu una recalculată. Şi primeşte eticheta curbei: 12 luni e 12M, nu 1Y.
  • Bid şi ask se interpolează separat, deci rezultă un spread propriu maturităţii cerute. Ca peste tot la titluri, bid > ask: sunt randamente, nu preţuri.
  • Ziua fără publicare primeşte ultimul fixing anterior, cel mult 10 zile în urmă, marcat prin exact_ziua şi zile_inapoi. Interpolarea se face pe puncte din ACEEAŞI zi.

La ce folosește

  • Actualizarea unui flux de numerar cu scadenţă care nu cade pe un punct publicat.
  • Evaluarea unei obligaţiuni corporative prin adăugarea unui spread la randamentul suveran de aceeaşi maturitate.
  • Construirea unei curbe cu pas fix, punct cu punct, pentru un model propriu.

Structura răspunsului

CâmpTipDescriere
data.luni integer Maturitatea cerută, în luni.
data.maturitate_ceruta string Eticheta ei. Când coincide cu un punct publicat, e eticheta curbei (12M, nu 1Y).
data.data string Ziua cerută, exact cum ai trimis-o.
data.data_ceruta string Data cerută de client, înainte de alinierea la o zi cu date.
data.exact_ziua boolean true doar dacă ziua întoarsă e cea cerută.
data.zile_inapoi integer Câte zile s-a mers înapoi până la ultimul fixing.
data.unitate string Mereu procent_pe_an.
data.interpolat boolean false înseamnă valoare publicată, nu calculată.
data.metoda string liniara când s-a interpolat, null când punctul e publicat.
data.bid string Randamentul bid la maturitatea cerută. Mai MARE decât ask.
data.ask string Randamentul ask la maturitatea cerută.
data.mid string Media dintre bid şi ask.
data.spread string bid − ask, în puncte procentuale. Deja pozitiv.
data.intre.stanga object Punctul publicat imediat sub maturitatea cerută, întreg. null când nu s-a interpolat.
data.intre.stanga.maturitate string
data.intre.stanga.denumire string Denumirea, aşa cum o publică sursa.
data.intre.stanga.luni integer Numărul de luni acoperite.
data.intre.stanga.bid string
data.intre.stanga.ask string
data.intre.stanga.mid string
data.intre.stanga.spread string
data.intre.dreapta object Punctul publicat imediat peste. null când nu s-a interpolat.
data.intre.dreapta.maturitate string
data.intre.dreapta.denumire string Denumirea, aşa cum o publică sursa.
data.intre.dreapta.luni integer Numărul de luni acoperite.
data.intre.dreapta.bid string
data.intre.dreapta.ask string
data.intre.dreapta.mid string
data.intre.dreapta.spread string
meta.sursa string Sursa oficială din care vin datele, cu licenţa ei acolo unde e cerută.
meta.metoda string
meta.nota_vecini string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.nota_extrapolare string Precizare despre cum se citeşte răspunsul: o capcană, o convenţie sau o limită a sursei.
meta.curba string
meta.fara_date string data e null, iar aici stă motivul. Maturitatea e sub 6 luni sau peste 10 ani; răspunsul dă intervalul acoperit şi punctele publicate.
meta.fara_date_cod string Cuvântul scurt şi STABIL al motivului, pentru clienţii care comută pe el în cod: fara_date e proză şi se poate reformula, ăsta nu.

Exemple de răspuns

GEThttps://oneapi.ro/api/financiar/v1/titluri-stat/randament?maturitate=7Y&data=2024-06-14
{
    "data": {
        "luni": 84,
        "maturitate_ceruta": "7Y",
        "data": "2024-06-14",
        "data_ceruta": "2024-06-14",
        "exact_ziua": true,
        "zile_inapoi": 0,
        "unitate": "procent_pe_an",
        "interpolat": true,
        "metoda": "liniara",
        "bid": "6.71",
        "ask": "6.47",
        "mid": "6.59",
        "spread": "0.24",
        "intre": {
            "stanga": {
                "maturitate": "5Y",
                "denumire": "cinci ani",
                "luni": 60,
                "bid": "6.59",
                "ask": "6.35",
                "mid": "6.47",
                "spread": "0.24"
            },
            "dreapta": {
                "maturitate": "10Y",
                "denumire": "zece ani",
                "luni": 120,
                "bid": "6.89",
                "ask": "6.66",
                "mid": "6.78",
                "spread": "0.23"
            }
        }
    },
    "meta": {
        "sursa": "BNR — fixing titluri de stat (baza de date interactivă).",
        "metoda": "Interpolare LINIARĂ între punctele adiacente. Măsurat pe toată seria, curba are curbură reală: reconstruind puncte publicate din vecini mai îndepărtaţi, eroarea medie e 0,06–0,15 puncte. Între adiacente e mult mai mică, dar rămâne o aproximare.",
        "nota_vecini": "`intre` conţine ambele puncte vecine, întregi — cine vrea alt model de interpolare porneşte de acolo.",
        "nota_extrapolare": "Curba acoperă 6 luni – 10 ani. În afara ei nu se extrapolează.",
        "curba": "Toate punctele publicate ale zilei: /financiar/v1/titluri-stat/fixing."
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
404negasitNu există fixing aplicabil la data cerută.
422validareMaturitate malformată, sau dată malformată ori în viitor.
429cota_depasitaCota lunară a planului a fost depăşită (vezi Retry-After).

Toate erorile au aceeași formă. eroare.cod e stabil și e cel după care trebuie să ramifici în cod — nu după textul din mesaj, care se poate schimba.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "Maturitate malformată, sau dată malformată ori în viitor.",
        "detalii": {
            "maturitate": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}