8. Справочник методов API

8. Справочник методов API

Базовый адрес: `https://api.shiftpay.cc/api/v1`. Все ответы — JSON. Ошибки — `application/problem+json` (см. [раздел 13](#13-ошибки-и-справочник-кодов)). Поддерживаются только `GET` и `POST`; тело `POST` до 64 КиБ.

| Метод | Путь | Право | Назначение | | --- | --- | --- | --- | | GET | `/` | — | Служебная информация: сервис, тип аутентификации, включён ли live. Подпись не нужна. | | GET | `/health` | — | Проверка готовности (`{"status":"ok"}`). Подпись не нужна. | | GET | `/payment-methods` | `payments:read` | Способы оплаты магазина. | | POST | `/payments` | `payments:write` | Создать платёж. | | GET | `/payments` | `payments:read` | Список платежей. | | GET | `/payments/{id}` | `payments:read` | Платёж. | | POST | `/payments/{id}/cancel` | `payments:write` | Отменить платёж. | | GET | `/payments/{id}/events` | `payments:read` + `webhooks:read` | События платежа и доставка вебхуков. | | GET | `/webhook-events/{id}` | `webhooks:read` | Событие по ID. | | GET | `/balance` | `balance:read` | Баланс по валютам. | | POST | `/refunds` | `refunds:write` | Создать заявку на возврат. | | GET | `/refunds` | `refunds:read` | Список возвратов. | | GET | `/refunds/{id}` | `refunds:read` | Возврат. | | GET | `/withdrawals/terms` | `withdrawals:read` | Условия вывода. | | POST | `/withdrawals/quote` | `withdrawals:read` | Расчёт вывода (без резерва). | | POST | `/withdrawals` | `withdrawals:write` | Создать заявку на вывод. | | GET | `/withdrawals` | `withdrawals:read` | Список заявок. | | GET | `/withdrawals/{id}` | `withdrawals:read` | Заявка и согласования. |

Метод `/conversions` в публичном API пока не поддерживается и возвращает `501`.

8.1. Способы оплаты

`GET /payment-methods` → `{"data":[{"id":"sbp"},{"id":"card"}, …]}`. Готовность провайдера дополнительно проверяется при открытии оплаты.

8.2. Платежи

**Список** — `GET /payments?limit=20&cursor=…&status=paid`

• `limit` — 1–100, по умолчанию 20.

• `cursor` — значение `next_cursor` из предыдущего ответа.

• `status` — один из статусов платежа.

• Ответ: `{"data":[…], "has_more": true|false, "next_cursor": "…"|null}`. Сортировка от новых к старым. Неизвестные или повторяющиеся параметры → `400 invalid_request`.

**Платёж** — `GET /payments/{id}`. Чужие платежи недоступны (`404 not_found`).

**Отмена** — `POST /payments/{id}/cancel` с пустым телом `{}` и `Idempotency-Key`. Если статус не `awaiting_method`/`pending` → `409 invalid_state`. Создаётся событие `payment.cancelled`.

**События платежа** — `GET /payments/{id}/events?limit=…&cursor=…` (нужны оба права: `payments:read` и `webhooks:read`). Для каждого события: `id`, `type`, `source`, `correlation_id`, `created_at`, `payload` (может быть опущен, если очень большой, тогда `payload_omitted: true`) и блок `delivery`: `status` (`delivered`, `queued`, `paused`, `not_enqueued` и др.), `attempt_count`, `next_attempt_at`, `delivered_at`.

**Событие по ID** — `GET /webhook-events/{id}` → `id`, `type`, `payload`, `created_at`.

8.3. Баланс

`GET /balance` →

Значение полей описано в [разделе 10](#10-деньги-баланс-холд-резерв-комиссия). Ответ содержит строку по каждой поддерживаемой валюте (RUB, USD, EUR, USDT, BTC, TON), даже если остаток нулевой.

8.4. Возвраты

**Создать** — `POST /refunds` (право `refunds:write`, `Idempotency-Key`), тело:

| Поле | Описание | | --- | --- | | `payment_id` | ID оплаченного платежа (`sp_test_…`/`sp_live_…`). Обязательно. | | `reason` | Обязательно, один из: `duplicate`, `returned_goods`, `suspected_fraud`, `cancelled_order`, `customer_request`, `service_not_provided`, `wrong_amount`, `quality_claim`, `other`. | | `details` | Комментарий до 512 символов, без управляющих символов. | | `amount` | Необязательно. Сейчас поддерживается **только полный возврат**; другая сумма даёт `400 refund_full_only`. |

Ответ `201` содержит: `id` (`rf_test_…`/`rf_live_…`), `payment_id`, `status`, `amount`, `original_amount`, `currency`, `fee`, `fee_bps`, `merchant_debit`, `reserved_amount`, `reason`, `details`, `review_reason`, `created_at`, `updated_at`, `execution_enabled`.

Важно:

• Заявка **резервирует** сумму возврата и комиссию на балансе магазина. **Деньги покупателю она сама не отправляет.** Заявку рассматривает администратор; после решения платёж получает статус `refunded`.

• Комиссия возврата удерживается с магазина и не добавляется покупателю.

• Статусы возврата: `pending`, `approved`, `rejected`. Отклонённая заявка возвращает резерв в доступные средства.

• `execution_enabled: false` означает, что автоматическое исполнение возврата платформой не подключено.

**Список** — `GET /refunds?limit=50&cursor=…&status=pending` (лимит 1–100, по умолчанию 50). Ответ: `data`, `has_more`, `next_cursor`. **Возврат** — `GET /refunds/{id}`.

Частые коды: `refund_payment_not_found` (404), `refund_payment_state` (409, платёж не в подходящем состоянии), `refund_insufficient_balance` (409), `refund_requires_review` (409), `refund_forbidden` (403), `refund_live_disabled` (403).

8.5. Выводы (API)

Публичный API выводов — серверный, работает по той же подписи. Его очередь предназначена для **тестовой среды**: он не обещает отправку реальных денег. Боевые выводы оформляются в кабинете ([раздел 11](#11-платежи-возвраты-выводы-конвертации-в-кабинете)).

• `GET /withdrawals/terms` — настроенные условия вывода (`data`: список способов с комиссией, минимумом, максимумом, порогом двойного одобрения, версией условий `revision` и т. п.).

• `POST /withdrawals/quote` — тело `currency`, `network`, `amount`. Возвращает расчёт (комиссию и итог списания), **не резервирует средства**, ключ идемпотентности не нужен.

• `POST /withdrawals` — создание. Обязательные поля: `currency`, `network`, `amount`, `address`, `terms_revision` (версия условий, полученная из `terms`/`quote`), заголовок `Idempotency-Key`. Необязательные: `note` (до 512 символов), `quote_confirmation`. Заявка **резервирует сумму и комиссию**.

• `GET /withdrawals?limit=…&after=…&status=…` — список. Здесь курсор называется **`after`** (не `cursor`); `limit` 1–100, по умолчанию 50.

• `GET /withdrawals/{id}` — заявка (идентификатор вида `wd_test_…`) и согласования.

Статусы заявки на вывод: `pending` → `partially_approved` (при двойном одобрении) → `approved`, либо `rejected`. **`approved` не означает, что выплата выполнена.** При отклонении резерв освобождается отдельной проводкой.

Типичные коды: `withdrawal_version_conflict` (условия изменились, перечитайте `terms`), `withdrawal_amount_limit`, `withdrawal_insufficient_balance`, `withdrawal_requires_review`, `withdrawal_rate_limited`, `withdrawal_invalid_state`.

8.6. Пагинация, идемпотентность, лимиты

| Тема | Правило | | --- | --- | | Курсоры | Передавайте `next_cursor` как `cursor` (у выводов — как `after`). Курсор непрозрачный: не разбирайте и не собирайте его. | | Лимит запросов | 180 аутентифицированных запросов в минуту на ключ. При превышении `429` и `Retry-After`. | | Размер тела | До 64 КиБ. | | Content-Type | `application/json` для `POST`, иначе `415`. | | Трассировка | В каждом ответе есть `X-Correlation-Id`. Сохраняйте его для обращения в поддержку. | | Идемпотентность | Обязательна для изменяющих `POST`: создание платежа, отмена, возврат, вывод. |

---