# Работа с данными

## Пустой ответ

Список без записей приходит со статусом 200 и `"items": []`: донатов или целей пока нет. Это успешный ответ: ошибки приходят с другим статусом.

## Страницы

Списки отдаются как `{"items": [...], "nextCursor": "..."}`. Следующая страница —
`?cursor=<nextCursor>`; `nextCursor: null` — страниц больше нет. `limit` — от 1 до 100 (по умолчанию
20). Курсор даёт страницы без пропусков и повторов, даже если пока вы листаете, приходят новые донаты.

## Цели, топ и сумма

Публичный ключ работает только с разрешённого адреса сайта: в примерах ниже `Origin` указан вручную, из
браузера заголовок ставится сам.

```bash
curl -s "https://api.staging.donatty.com/v1/goals?status=ACTIVE&limit=1" -H "Authorization: Bearer $KEY" \
  -H 'Origin: https://mysite.example'
curl -s "https://api.staging.donatty.com/v1/stats/top?period=WEEK&limit=3" -H "Authorization: Bearer $KEY" \
  -H 'Origin: https://mysite.example'
curl -s "https://api.staging.donatty.com/v1/stats/total?period=DAY&timeZone=Asia/Novosibirsk" -H "Authorization: Bearer $KEY" \
  -H 'Origin: https://mysite.example'
```

- `raised` цели — собранное целью Донатти по всем донатам, включая отклонённые модерацией; цели Donation
  Alerts и настройки виджета не учитываются, поэтому прогресс на сцене может отличаться.
- Топ и сумма — все подключённые источники стримера в рублях. Период `DAY | WEEK | MONTH | YEAR |
  ALL_TIME` (по умолчанию `ALL_TIME`) — календарный в зоне `timeZone` (IANA, по умолчанию
  `Europe/Moscow`); граница `[from, to)`: `to` — начало следующего периода и в сумму не входит.

В `raised` входит и ручной старт цели — начальная сумма, которую стример задал вручную. Учитывайте её, когда сравниваете `raised` с суммой донатов.

Донаты, отклонённые модерацией, входят в сумму целей, топа и периода.

Статистика не баланс. Сумма за период — это поступившие донаты. Остаток к выводу и выплаты API не отдаёт.

## Форматы

- Деньги: `{"value": "500.00", "currency": "RUB"}` — десятичная строка и код ISO 4217.
- Время: RFC 3339 в UTC (`2026-11-09T10:15:30Z`, бывают доли секунды).
- Идентификаторы: `str_…`, `don_…`, `goal_…` — строки; внутренних числовых id нет.
- Неизвестные поля и значения перечислений пропускайте: в `v1` они могут добавляться без новой версии.