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

Форматы полей, страницы списков и то, как считаются цели, топ и сумма.

## Форматы

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

## Страницы

Донаты и цели приходят страницами: `{"items": [...], "nextCursor": "..."}`. Чтобы получить следующую страницу, передайте `nextCursor` в параметре `cursor`. `nextCursor: null` значит, что страница последняя. В `limit` — от 1 до 100 записей, по умолчанию 20.

Страницы идут от новых записей к старым, без пропусков и повторов. Новые донаты и новый статус модерации приходят только в новом запросе без `cursor`. У донатов есть параметр `since`: вернутся донаты, созданные в этот момент или позже.

Пустой `"items": []` со статусом 200 — успешный ответ: [почему так бывает](https://developers.donatty.com/faq.md#почему-пришёл-пустой-список).

Топ донатеров возвращает до `limit` записей одной страницей, без `nextCursor`; по умолчанию 10.

## Почему сумма цели не совпадает с виджетом

В `raised` входят сумма, с которой вы начали сбор (поле «Начать сбор с»), и все донаты Донатти в эту цель, включая отклонённые модерацией. Цели Donation Alerts и настройки виджета API не учитывает.

## Топ и сумма за период

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

| `period` | Что считается |
|---|---|
| `DAY` | сегодня с 00:00 |
| `WEEK` | эта неделя с понедельника |
| `MONTH` | этот месяц с 1-го числа |
| `YEAR` | этот год с 1 января |
| `ALL_TIME` | всё время; значение по умолчанию |

Границы считаются по часовому поясу из `timeZone`, по умолчанию `Europe/Moscow`. В ответе `from` — начало периода, `to` — начало следующего: донат, созданный ровно в `to`, в период не входит. Для `ALL_TIME` `to` — момент ответа.

Баланса и вывода денег в API нет.
