# Донаты

**`GET /v1/donations`** · Секретный ключ · право `donations:read`

Ваши донаты от новых к старым: из Донатти и из Donation Alerts, если он подключён. Без фильтра приходят все донаты с полным текстом, включая отклонённые модерацией и ожидающие её решения. Для показа на стриме добавьте `moderation=PASSED,NONE`. Контактов донатеров, ордера и комиссии сервиса в ответе нет; из платёжных данных есть только `feeCompensation` (доплата донатера за комиссию) и `paymentMethod` (`CARD`, `SBP` или `null`).

## Параметры

| Имя | Где | Тип | Описание |
|---|---|---|---|
| `limit` | в адресе | целое число, 1–100, по умолчанию `20` | Сколько записей вернуть на странице: от 1 до 100, по умолчанию 20. |
| `cursor` | в адресе | строка | `nextCursor` из предыдущего ответа: вернёт следующую страницу. |
| `since` | в адресе | строка (дата и время) | Только донаты, созданные в этот момент или позже, например `2026-11-09T10:00:00Z`. |
| `source` | в адресе | список строк, значения: `DONATTY`, `DONATION_ALERTS` | Из каких источников вернуть донаты, через запятую. Без параметра — из всех. |
| `moderation` | в адресе | список строк, значения: `PENDING`, `PASSED`, `BLOCKED`, `NONE` | Донаты с какими статусами модерации вернуть, через запятую. Для показа на стриме — `PASSED,NONE`. Без параметра приходят все, включая отклонённые. |

## Ответы

- `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` — Ключ не того вида или у него нет права `donations:read`. У публичного ключа этого права не бывает: [`wrong_token_type`](https://developers.donatty.com/errors/wrong_token_type.md), [`insufficient_scope`](https://developers.donatty.com/errors/insufficient_scope.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
{
  "items": [
    {
      "id": "don_5d2e8f31-6a47-4c19-9b0e-7f3a2d1c8e46",
      "createdAt": "2026-11-09T10:21:47Z",
      "source": "DONATTY",
      "donorName": "Алексей",
      "message": "Спасибо за стрим!",
      "amount": {
        "value": "500.00",
        "currency": "RUB"
      },
      "feeCompensation": {
        "value": "27.00",
        "currency": "RUB"
      },
      "paymentMethod": "CARD",
      "goal": null,
      "moderation": {
        "status": "PASSED",
        "deadline": null
      },
      "media": null
    },
    {
      "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"
      },
      "feeCompensation": null,
      "paymentMethod": "SBP",
      "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"
      },
      "feeCompensation": null,
      "paymentMethod": "CARD",
      "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"
      },
      "feeCompensation": null,
      "paymentMethod": null,
      "goal": null,
      "moderation": {
        "status": "NONE",
        "deadline": null
      },
      "media": null
    }
  ],
  "nextCursor": "MTc5NDIxODI4MDAwMDAwMC45YTFiMmMzZC00ZTVmLTRhNmItOGM3ZC0wZTFmMmEzYjRjNWQ"
}
```

## Схемы

### DonationPage

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

### Donation

| Поле | Тип | Описание |
|---|---|---|
| `id` | строка | Идентификатор доната, `don_…`. |
| `createdAt` | строка (дата и время) | Когда донат создан; у доната Донатти — когда подтверждена оплата. |
| `source` | строка, значения: `DONATTY`, `DONATION_ALERTS` | Откуда донат: `DONATTY` или `DONATION_ALERTS`. |
| `donorName` | строка | Имя, которое указал донатер. Если он его не указал, у доната Донатти — `Anonymous`. |
| `message` | строка | Сообщение донатера целиком; пустая строка, если он ничего не написал. Фильтры виджетов к нему не применяются. |
| `amount` | `Money` | Сумма доната в его валюте, без доплаты донатера за комиссию. |
| `feeCompensation` | `Money` или null | Доплата донатера за комиссию сервиса в валюте `amount`: с донатера списано `amount` плюс `feeCompensation`. `null`, если донатер не доплачивал, и всегда для `DONATION_ALERTS`. |
| `paymentMethod` | строка, значения: `CARD`, `SBP` или null | Как донатер заплатил: `SBP` (СБП) или `CARD` — все остальные способы, включая Apple Pay и Google Pay и старые донаты без записанного способа. `null` для `DONATION_ALERTS`. |
| `goal` | объект или null | Цель, в которую пошёл донат: `id` и `title`. `null`, если донат без цели. |
| `moderation` | `Moderation` | Модерация сообщения: статус и срок решения. |
| `media` | объект или null | Ролик к донату: `title`, `url`, `provider`, `durationSeconds` и своя `moderation`. `null`, если ролика нет. |

### Money

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

### Moderation

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