# Внешние API и референсы

| Что | Ссылка | Заметки |
|---|---|---|
| ZenMoney API | https://github.com/zenmoney/ZenPlugins/wiki/ZenMoney-API | только `/v8/diff/` и `/v8/suggest/`; токен 24 ч + refresh |
| T-Invest API | https://developer.tbank.ru/invest/api | gRPC; лимиты Operations/Instruments 200/мин, MarketData 600/мин |
| T-Invest Python SDK | индекс `https://opensource.tbank.ru/api/v4/projects/238/packages/pypi/simple` | пакет `t-tech-investments` |
| MOEX ISS | https://iss.moex.com/iss/reference/ | без ключа; history, dividends, bondization, индексы |
| ЦБ РФ курсы | https://www.cbr.ru/scripts/XML_dynamic.asp | cp1251, делить на `Nominal` |
| pyxirr | https://github.com/Anexen/pyxirr | XIRR/TWR |
| investbook | https://github.com/spacious-team/investbook | референс форматов отчётов Сбер/ВТБ (Java) |
| invest_toolkit | https://github.com/i-savelev/invest_toolkit | парсеры Сбер/ВТБ на Python |
| Соседние проекты | `../fin-dashboard`, `../t_tech-gyro` | ZenMoney diff-цикл, CBR fx, T-Invest адаптер + CA-сертификаты |

## Что выяснилось при реализации фазы 1 (источники)

### ZenMoney `/v8/diff/`
- Тело запроса: `{"currentClientTimestamp": <unix now>, "serverTimestamp": <курсор|0>,
  "forceFetch": [типы]}`; `forceFetch` отправляем только при курсоре 0. Ответ — те же
  массивы сущностей (только изменённые), `deletion: [{id, object, stamp, user}]` и новый
  `serverTimestamp`.
- Типы сущностей: `instrument, company, user, account, tag, merchant, budget, reminder,
  reminderMarker, transaction`. `company`, `user`, `budget`, `reminder*` храним только в
  raw — в core они пока не нужны.
- `account.type = ccard` маппится в `AccountKind.zm_card` (в enum нет `zm_ccard`),
  остальные типы — буквально `zm_<type>`.
- Токен живёт 86400 с. Ротация: `POST https://api.zenmoney.ru/oauth2/token/`,
  form-encoded `grant_type=refresh_token&refresh_token=…&client_id=…&client_secret=…`,
  ответ `{access_token, refresh_token, expires_in, token_type}`. Пара лежит в
  `source_credential(source='zenmoney')`, засеивается из `ZENMONEY_REFRESH_TOKEN`.
- Статический токен (zerro.app/token) при 401 нечем обновить — источник падает с
  явным требованием обновить `ZENMONEY_TOKEN`.

### Прокси на хосте `ada-x1`
- `ALL_PROXY=socks5h://…`, поэтому `httpx.AsyncClient(trust_env=True)` требует extra
  `httpx[socks]` (пакет `socksio`) — он добавлен в зависимости, иначе клиент падает на
  конструировании ещё до запроса.
- api.zenmoney.ru доступен через прокси (`trust_env=True`, по умолчанию).
  cbr.ru через этот прокси роняет TLS → CBR-клиент строится с `trust_env=False`.

### ЦБ РФ
- `XML_daily.asp?date_req=DD/MM/YYYY` нужен только ради карты `CharCode -> ID`
  (`USD -> R01235`, `JPY -> R01820`); на 17.09.2026 отдаёт 54 валюты.
- `XML_dynamic.asp?date_req1=…&date_req2=…&VAL_NM_RQ=<ID>` — `<Record Date="dd.mm.yyyy">`
  с `<Nominal>` и `<Value>` (запятая как разделитель). Кодировка windows-1251.
  В `raw_cbr_rate` кладём `value` и `nominal` как напечатано; деление на номинал —
  в `pricing/fx.py`.
- Крипта и металлы (XAU, BTC …) ЦБ не котирует — уходят в `warnings`, не в ошибку.