# Топ донатеров

**`GET /v1/stats/top`** · Секретный или публичный ключ · право `stats:read`

Донатеры с самой большой суммой донатов за сегодня, эту неделю, месяц, год или за всё время. Считаем донаты из всех подключённых источников и переводим в рубли. Донатеров с одним именем из разных источников считаем одним.

## Параметры

| Имя | Где | Тип | Описание |
|---|---|---|---|
| `period` | в адресе | строка, значения: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME`, по умолчанию `ALL_TIME` | `DAY` — сегодня с 00:00, `WEEK` — эта неделя с понедельника, `MONTH` — этот месяц, `YEAR` — этот год, `ALL_TIME` — всё время. Границы — по часовому поясу `timeZone`. По умолчанию `ALL_TIME`. |
| `limit` | в адресе | целое число, 1–100, по умолчанию `10` | Сколько донатеров вернуть: от 1 до 100, по умолчанию 10. |
| `timeZone` | в адресе | строка, по умолчанию `Europe/Moscow` | Часовой пояс, по которому считаются границы периода, например `Asia/Novosibirsk`. По умолчанию `Europe/Moscow`. |

## Ответы

- `200` — Успешно
- `400` — Параметр не подходит или ключ передан в адресе запроса: [`invalid_parameter`](https://developers.donatty.com/errors/invalid_parameter.md), [`token_in_query`](https://developers.donatty.com/errors/token_in_query.md)
- `401` — Ключа нет, он не найден, удалён или истёк: [`missing_token`](https://developers.donatty.com/errors/missing_token.md), [`invalid_token`](https://developers.donatty.com/errors/invalid_token.md), [`token_expired`](https://developers.donatty.com/errors/token_expired.md)
- `403` — Ключ не того вида, у него нет права `stats:read`, или публичный ключ пришёл с адреса, которого нет в его списке: [`wrong_token_type`](https://developers.donatty.com/errors/wrong_token_type.md), [`insufficient_scope`](https://developers.donatty.com/errors/insufficient_scope.md), [`origin_not_allowed`](https://developers.donatty.com/errors/origin_not_allowed.md)
- `429` — Исчерпан лимит запросов: [`rate_limited`](https://developers.donatty.com/errors/rate_limited.md)
- `500` — Запрос не удался на нашей стороне: [`internal_error`](https://developers.donatty.com/errors/internal_error.md)
- `503` — API временно недоступен: [`service_unavailable`](https://developers.donatty.com/errors/service_unavailable.md)

## Пример ответа

```json
{
  "period": "WEEK",
  "from": "2026-11-08T21:00:00Z",
  "to": "2026-11-15T21:00:00Z",
  "items": [
    {
      "rank": 1,
      "name": "Alex",
      "total": {
        "value": "12500.00",
        "currency": "RUB"
      }
    },
    {
      "rank": 2,
      "name": "Maria",
      "total": {
        "value": "4300.75",
        "currency": "RUB"
      }
    },
    {
      "rank": 3,
      "name": "Ivan",
      "total": {
        "value": "1000.00",
        "currency": "RUB"
      }
    }
  ]
}
```

## Схемы

### Top

| Поле | Тип | Описание |
|---|---|---|
| `period` | строка, значения: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME` | Период из запроса. |
| `from` | строка (дата и время) | Начало периода. Для `ALL_TIME` — `1970-01-01T00:00:00Z`. |
| `to` | строка (дата и время) | Начало следующего периода: сам этот момент в период не входит. Для `ALL_TIME` — момент ответа. |
| `items` | список объектов |  |

### Money

| Поле | Тип | Описание |
|---|---|---|
| `value` | строка | Десятичная сумма с двумя знаками после запятой. |
| `currency` | строка | Код ISO 4217. |
