# Справочник API

Справочник собран из OpenAPI того же коммита, что и сайт. Файл целиком: [openapi.json](https://developers.staging.donatty.com/openapi.json). В нём `servers` указывает на боевой API, а кнопка «Попробовать запрос» отправляет запросы на https://api.staging.donatty.com.

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

Для публичного ключа сервер проверяет адрес сайта (Origin). Из справочника запрос уходит с адреса `https://developers.staging.donatty.com`: чтобы ключ сработал, добавьте его в адреса ключа или проверяйте ключ со своего сайта, как описано в [быстром старте для сайта](https://developers.staging.donatty.com/quickstart/website.md).



## Текстовая версия справочника

### GET /v1/streamer

**Профиль стримера.** Публичный профиль стримера, выпустившего ключ.

**Доступ:** секретный ключ (`personalToken`), право `profile:read`; публичный ключ (`publishableKey`), право `profile:read`

**Ответы:**

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

**Пример ответа 200:**

```json
{
  "id": "str_5b0c2f4e-8d61-4f43-9a7e-2f1d3c6b9a10",
  "slug": "teststreamer",
  "displayName": "Test Streamer",
  "avatarUrl": "https://storage.donatty.com/avatars/teststreamer.png",
  "donatePageUrl": "https://donatty.com/teststreamer"
}
```

### GET /v1/donations

**Донаты.** Все донаты стримера от новых к старым: Донатти и Donation Alerts (если подключён), включая отклонённые модерацией и ожидающие её решения, с полным текстом и текущим статусом модерации. Без контактов донатеров, платёжных данных и комиссий. Только секретные ключи.

**Доступ:** секретный ключ (`personalToken`), право `donations:read`

**Параметры:**

| Имя | Где | Тип | Описание |
|---|---|---|---|
| `limit` | в адресе | `integer`, 1–100, по умолчанию `20` |  |
| `cursor` | в адресе | `string` | `nextCursor` предыдущей страницы. |
| `since` | в адресе | `string:date-time` | Только донаты, созданные в этот момент или позже (RFC 3339). |
| `source` | в адресе | список `string`, значения: `DONATTY`, `DONATION_ALERTS` | Источники через запятую. |
| `moderation` | в адресе | список `string`, значения: `PENDING`, `PASSED`, `BLOCKED`, `NONE` | Статусы модерации через запятую, например `PASSED,NONE`. |

**Ответы:**

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

**Пример ответа 200:**

```json
{
  "items": [
    {
      "id": "don_0f6e2a4c-91b3-4d7a-8c5e-3b2a1f0e9d84",
      "createdAt": "2026-11-09T10:15:30.123456Z",
      "source": "DONATTY",
      "donorName": "Alex",
      "message": "Thanks for the stream!",
      "amount": {
        "value": "500.00",
        "currency": "RUB"
      },
      "goal": {
        "id": "goal_7e3a9c10-4b2d-4f8e-a1c6-0d9b8e7f6a52",
        "title": "New microphone"
      },
      "moderation": {
        "status": "PENDING",
        "deadline": "2026-11-09T10:16:30Z"
      },
      "media": {
        "title": "Song of the day",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "provider": "YOUTUBE",
        "durationSeconds": 212,
        "moderation": {
          "status": "PENDING",
          "deadline": "2026-11-09T10:16:30Z"
        }
      }
    },
    {
      "id": "don_3c9d7b21-5e84-4a6f-b0d2-8e1f4a7c6b35",
      "createdAt": "2026-11-09T10:02:11Z",
      "source": "DONATTY",
      "donorName": "Anonymous",
      "message": "This text was rejected by moderation but is returned in full.",
      "amount": {
        "value": "150.50",
        "currency": "RUB"
      },
      "goal": null,
      "moderation": {
        "status": "BLOCKED",
        "deadline": null
      },
      "media": null
    },
    {
      "id": "don_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "createdAt": "2026-11-09T09:58:00Z",
      "source": "DONATION_ALERTS",
      "donorName": "Maria",
      "message": "Hi from Donation Alerts",
      "amount": {
        "value": "5.00",
        "currency": "USD"
      },
      "goal": null,
      "moderation": {
        "status": "NONE",
        "deadline": null
      },
      "media": null
    }
  ],
  "nextCursor": "MTc5NDIxODI4MDAwMDAwMC45YTFiMmMzZC00ZTVmLTRhNmItOGM3ZC0wZTFmMmEzYjRjNWQ"
}
```

### GET /v1/goals

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

**Доступ:** секретный ключ (`personalToken`), право `goals:read`; публичный ключ (`publishableKey`), право `goals:read`

**Параметры:**

| Имя | Где | Тип | Описание |
|---|---|---|---|
| `status` | в адресе | `string`, значения: `ACTIVE`, `CLOSED` |  |
| `limit` | в адресе | `integer`, 1–100, по умолчанию `20` |  |
| `cursor` | в адресе | `string` | `nextCursor` предыдущей страницы. |

**Ответы:**

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

**Пример ответа 200:**

```json
{
  "items": [
    {
      "id": "goal_7e3a9c10-4b2d-4f8e-a1c6-0d9b8e7f6a52",
      "title": "New microphone",
      "target": {
        "value": "15000.00",
        "currency": "RUB"
      },
      "raised": {
        "value": "6420.50",
        "currency": "RUB"
      },
      "status": "ACTIVE",
      "endsAt": "2026-12-31T21:00:00Z",
      "createdAt": "2026-10-01T12:00:00Z"
    }
  ],
  "nextCursor": "MTc5MDg1NjAwMDAwMDAwMC43ZTNhOWMxMC00YjJkLTRmOGUtYTFjNi0wZDliOGU3ZjZhNTI"
}
```

### GET /v1/stats/top

**Топ донатеров.** Топ донатеров за календарный период `[from, to)` в зоне `timeZone`: все подключённые источники в рублях, донатеры с одним именем объединены по источникам, сортировка по сумме по убыванию.

**Доступ:** секретный ключ (`personalToken`), право `stats:read`; публичный ключ (`publishableKey`), право `stats:read`

**Параметры:**

| Имя | Где | Тип | Описание |
|---|---|---|---|
| `period` | в адресе | `string`, значения: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME`, по умолчанию `ALL_TIME` |  |
| `limit` | в адресе | `integer`, 1–100, по умолчанию `10` |  |
| `timeZone` | в адресе | `string`, по умолчанию `Europe/Moscow` | Часовой пояс календарного периода (IANA). |

**Ответы:**

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

**Пример ответа 200:**

```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"
      }
    }
  ]
}
```

### GET /v1/stats/total

**Сумма донатов.** Сумма донатов за календарный период `[from, to)` в зоне `timeZone`: все подключённые источники в рублях.

**Доступ:** секретный ключ (`personalToken`), право `stats:read`; публичный ключ (`publishableKey`), право `stats:read`

**Параметры:**

| Имя | Где | Тип | Описание |
|---|---|---|---|
| `period` | в адресе | `string`, значения: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME`, по умолчанию `ALL_TIME` |  |
| `timeZone` | в адресе | `string`, по умолчанию `Europe/Moscow` | Часовой пояс календарного периода (IANA). |

**Ответы:**

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

**Пример ответа 200:**

```json
{
  "period": "DAY",
  "from": "2026-11-09T17:00:00Z",
  "to": "2026-11-10T17:00:00Z",
  "total": {
    "value": "18250.25",
    "currency": "RUB"
  }
}
```

### Схемы

#### Money

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

#### Moderation

| Поле | Тип | Описание |
|---|---|---|
| `status` | `string`, значения: `PENDING`, `PASSED`, `BLOCKED`, `NONE` | `PENDING` — модерация идёт; `PASSED` — одобрен (в том числе «Повторить на стриме»); `BLOCKED` — отклонён; `NONE` — модерации не было (выключена, никого нет онлайн, Donation Alerts). |
| `deadline` | `string,null:date-time` | Только для `PENDING`: когда сработает решение по умолчанию. |

#### Streamer

| Поле | Тип | Описание |
|---|---|---|
| `id` | `string` |  |
| `slug` | `string` |  |
| `displayName` | `string` |  |
| `avatarUrl` | `string,null:uri` |  |
| `donatePageUrl` | `string:uri` |  |

#### Donation

| Поле | Тип | Описание |
|---|---|---|
| `id` | `string` |  |
| `createdAt` | `string:date-time` |  |
| `source` | `string`, значения: `DONATTY`, `DONATION_ALERTS` |  |
| `donorName` | `string` |  |
| `message` | `string` |  |
| `amount` | `Money` |  |
| `goal` | `object` (или null) |  |
| `moderation` | `Moderation` |  |
| `media` | `object` (или null) |  |

#### DonationPage

| Поле | Тип | Описание |
|---|---|---|
| `items` | список `Donation` |  |
| `nextCursor` | `string,null` | Передайте как `cursor`, чтобы получить следующую страницу; `null` — страница последняя. |

#### Goal

| Поле | Тип | Описание |
|---|---|---|
| `id` | `string` |  |
| `title` | `string` |  |
| `target` | `Money` |  |
| `raised` | `Money` |  |
| `status` | `string`, значения: `ACTIVE`, `CLOSED` |  |
| `endsAt` | `string,null:date-time` |  |
| `createdAt` | `string:date-time` |  |

#### GoalPage

| Поле | Тип | Описание |
|---|---|---|
| `items` | список `Goal` |  |
| `nextCursor` | `string,null` | Передайте как `cursor`, чтобы получить следующую страницу; `null` — страница последняя. |

#### Top

| Поле | Тип | Описание |
|---|---|---|
| `period` | `string`, значения: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME` |  |
| `from` | `string:date-time` |  |
| `to` | `string:date-time` | Не включается: начало следующего периода; для ALL_TIME — момент ответа. |
| `items` | список `object` |  |

#### Total

| Поле | Тип | Описание |
|---|---|---|
| `period` | `string`, значения: `DAY`, `WEEK`, `MONTH`, `YEAR`, `ALL_TIME` |  |
| `from` | `string:date-time` |  |
| `to` | `string:date-time` | Не включается. |
| `total` | `Money` |  |

#### Problem

| Поле | Тип | Описание |
|---|---|---|
| `type` | `string:uri` | https://developers.donatty.com/errors/<code> |
| `title` | `string` |  |
| `status` | `integer` |  |
| `detail` | `string` |  |
| `code` | `string`, значения: `missing_token`, `invalid_token`, `token_expired`, `token_in_query`, `wrong_token_type`, `insufficient_scope`, `origin_not_allowed`, `invalid_parameter`, `not_found`, `rate_limited`, `internal_error`, `service_unavailable` |  |
| `policy` (необязательный) | `string`, значения: `app-user`, `app`, `user`, `publishable-ip` | Только для `rate_limited`: исчерпанный уровень. |