> ## Documentation Index
> Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Правила сплита

**Методы:** `/v1/split/rule` · `/rule/list` · `/rule/delete`

**Сплит‑платёж** — правило, по которому доля каждого входящего платежа автоматически уходит партнёру.
Пример: из каждых \$100 — 70 % остаётся вам, 20 % уходит на адрес A, 10 % на адрес B. Типовые сценарии:
партнёрские программы, реселлеры, доля площадки в маркетплейсе, разделение выручки между
соучредителями.

Правила действуют на **все** входящие платежи мерчанта — задавать их у каждого счёта не нужно.

**Базовый URL:** `https://api.oblodai.com` · **Аутентификация:** обязательна.

<Note>
  Примеры используют хелпер `call()` и переменные `$SECRET`/`$PUBLIC_ID` — их определение см. в
  [Как подписать запрос](/guides/signing-requests). Проще не писать подпись руками, а взять
  [SDK](/sdk/overview).
</Note>

<Note>
  **Расчёт по сплитам не мгновенный.** Он откладывается на окно удержания `refund_hold_hours` —
  см. [`POST /v1/split/config/get · /set`](/reference/split-config). Прочитайте, **почему**: это не задержка
  ради задержки, а защита от ситуации «деньги ушли партнёру, а покупатель попросил возврат».
</Note>

***

## Два вида получателя

Это **главное** решение при создании правила: от него зависит, сможете ли вы вернуть деньги
покупателю.

| Получатель                 | Как задаётся          | Как уходит доля                         | Что при возврате                                                                                                             |
| -------------------------- | --------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Мерчант внутри Oblodai** | `merchant_id`         | Движение по внутреннему учёту (ledger). | **Обратимо:** доля **отзывается обратно** (claw‑back), пропорционально сумме возврата — даже если окно удержания уже прошло. |
| **Внешний адрес**          | `address` + `network` | Реальная транзакция в блокчейне.        | **НЕОБРАТИМО:** транзакция ушла в сеть, вернуть её нельзя. Возврат покупателю вы покрываете из своих средств.                |

Задавайте **либо** `address` + `network`, **либо** `merchant_id` — не оба сразу.

**Внутренний сплит безопаснее.** Если покупатель попросит возврат, платформа сама заберёт долю у
партнёра. Внешний сплит уходит в блокчейн навсегда — от него вас защищает **только** окно удержания
[`refund_hold_hours`](/reference/split-config): пока оно не истекло, доля партнёру ещё не отправлена, и возврат
покупателю возможен целиком. Полный возврат внутри окна **отменяет** сплит, частичный —
**уменьшает** долю партнёра.

<Warning>
  **Не ставьте `refund_hold_hours: 0` при внешних сплитах.** Доли уйдут почти сразу, и вернуть их
  станет физически невозможно. → [`POST /v1/split/config/set`](/reference/split-config)
</Warning>

***

## POST /v1/split/rule — создать правило

### Параметры запроса

<ParamField body="percent" type="float64" required>
  Доля от каждого платежа: `10` = 10 %, `2.5` = 2.5 %. Больше 0 и не больше 100. Точность — до 0.01 %.
</ParamField>

<ParamField body="address" type="string">
  Внешний криптоадрес партнёра.
</ParamField>

<ParamField body="network" type="string">
  Сеть адреса. **Обязательна вместе с `address`.**
</ParamField>

<ParamField body="merchant_id" type="string">
  Идентификатор мерчанта‑партнёра внутри Oblodai.
</ParamField>

<ParamField body="note" type="string">
  Комментарий для себя (в списке правил).
</ParamField>

<Info>
  Ровно один вариант получателя: либо `address` + `network`, либо `merchant_id`.
</Info>

**Сумма всех правил не может превышать 100 %** — иначе `split.exceeds_100`. Себе сплит назначить
нельзя (`split.self_destination`).

### Пример запроса

<CodeGroup>
  ```bash cURL theme={null}
  BODY='{"address":"TXY...","network":"tron","percent":10,"note":"партнёр Алиса"}'
  TS=$(date +%s)
  SIG=$(printf '%s\n%s\n%s\n%s' "$TS" 'POST' '/v1/split/rule' "$BODY" \
    | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
  curl -s https://api.oblodai.com/v1/split/rule \
    -X POST -H 'Content-Type: application/json' \
    -H "X-Public-Id: $PUBLIC_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
    -d "$BODY"
  ```

  ```python Python theme={null}
  # 10 % на внешний адрес — необратимо.
  call("/v1/split/rule", {
      "address": "TXY...",
      "network": "tron",
      "percent": 10,
      "note": "партнёр Алиса",
  })

  # 20 % мерчанту внутри платформы — при возврате доля отзовётся обратно.
  call("/v1/split/rule", {
      "merchant_id": "b4c1f0e2-5a77-4d31-9f08-2c6e7a1b3d94",
      "percent": 20,
      "note": "площадка",
  })
  ```

  ```js Node.js theme={null}
  // 10 % на внешний адрес — необратимо.
  await call("/v1/split/rule", {
    address: "TXY...",
    network: "tron",
    percent: 10,
    note: "партнёр Алиса",
  });

  // 20 % мерчанту внутри платформы — при возврате доля отзовётся обратно.
  await call("/v1/split/rule", {
    merchant_id: "b4c1f0e2-5a77-4d31-9f08-2c6e7a1b3d94",
    percent: 20,
    note: "площадка",
  });
  ```
</CodeGroup>

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

```json theme={null}
{
  "state": 0,
  "result": {
    "rule_id": "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23",
    "percent": 10
  }
}
```

***

## POST /v1/split/rule/list — список правил

Параметров нет — пошлите `{}`.

<CodeGroup>
  ```python Python theme={null}
  call("/v1/split/rule/list", {})
  ```

  ```js Node.js theme={null}
  await call("/v1/split/rule/list", {});
  ```
</CodeGroup>

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

```json theme={null}
{
  "state": 0,
  "result": {
    "items": [
      {
        "rule_id": "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23",
        "percent": 10,
        "active": true,
        "note": "партнёр Алиса",
        "address": "TXY...",
        "network": "tron",
        "reversible": false
      },
      {
        "rule_id": "7b3d0f19-6c25-4e88-b0a4-1f9e2d5c8a07",
        "percent": 20,
        "active": true,
        "note": "площадка",
        "merchant_id": "b4c1f0e2-5a77-4d31-9f08-2c6e7a1b3d94",
        "reversible": true
      }
    ]
  }
}
```

<ResponseField name="rule_id" type="string">
  Идентификатор правила.
</ResponseField>

<ResponseField name="percent" type="float">
  Доля от каждого платежа, %.
</ResponseField>

<ResponseField name="active" type="bool">
  Действует ли правило.
</ResponseField>

<ResponseField name="note" type="string">
  Ваш комментарий.
</ResponseField>

<ResponseField name="address" type="string">
  Получатель — внешний адрес (только у внешних правил).
</ResponseField>

<ResponseField name="network" type="string">
  Сеть внешнего адреса (только у внешних правил).
</ResponseField>

<ResponseField name="merchant_id" type="string">
  Получатель — мерчант платформы (только у внутренних правил).
</ResponseField>

<ResponseField name="reversible" type="bool">
  `true` — доля отзывается при возврате платежа (внутренний сплит); `false` — уходит в блокчейн навсегда (внешний).
</ResponseField>

***

## POST /v1/split/rule/delete — удалить правило

### Параметры запроса

<ParamField body="rule_id" type="string" required>
  Идентификатор правила.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  call("/v1/split/rule/delete", {"rule_id": "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23"})
  ```

  ```js Node.js theme={null}
  await call("/v1/split/rule/delete", { rule_id: "e2a91c47-3f80-4b6d-a512-7c0d9e8f1a23" });
  ```
</CodeGroup>

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

```json theme={null}
{ "state": 0, "result": { "deleted": true } }
```

Удаление действует на **будущие** платежи. Доли, уже начисленные по прошлым платежам и ждущие
окончания окна удержания, всё равно уйдут партнёру.

***

## Коды ошибок

| Код                          | Значение                                                              |
| ---------------------------- | --------------------------------------------------------------------- |
| `400 request.bad_json`       | Тело не парсится.                                                     |
| `400 split.bad_destination`  | Не задан получатель, либо заданы **оба** (`address` и `merchant_id`). |
| `400 split.network_required` | Задан `address`, но не задана `network`.                              |
| `400 split.bad_percent`      | `percent` вне диапазона 0–100.                                        |
| `400 split.exceeds_100`      | Сумма долей всех правил превысила 100 %.                              |
| `400 split.bad_merchant`     | `merchant_id` не является корректным UUID.                            |
| `400 split.self_destination` | Получатель — вы сами.                                                 |
| `400 split.bad_id`           | `rule_id` не является корректным UUID.                                |
| `404 split.not_found`        | Правило не найдено.                                                   |
| `503 split.disabled`         | Сплит‑платежи недоступны на этом шлюзе.                               |
| `401 auth.*`                 | Ошибки аутентификации.                                                |

***

## Нюансы

* **Сплит — пятый путь ухода средств** с вашего баланса (наряду с [выплатой](/reference/payout-create),
  [возвратом](/reference/payment-refund), [автовыводом](/reference/auto-withdraw) и
  [переводом на личный кошелёк](/reference/transfer-to-personal)). Учитывайте его, когда сводите баланс.
* **База расчёта — то, что реально пришло, за вычетом возвратов.** Доля считается от суммы платежа на
  момент исполнения, а не от суммы счёта: возврат внутри окна удержания уменьшает или обнуляет долю.
* **Доля уходит в монете платежа.** Отдельной конвертации сплит не делает.
* **Внешние сплиты необратимы.** Если вам нужна возможность отката, используйте `merchant_id`
  (внутренний сплит) — либо держите достаточное окно
  [`refund_hold_hours`](/reference/split-config).

***

## Связанные страницы

<CardGroup cols={2}>
  <Card title="POST /v1/split/config/get · /set" href="/reference/split-config" icon="arrow-right" horizontal>
    окно удержания `refund_hold_hours` и **почему** оно нужно.
  </Card>

  <Card title="POST /v1/payment/refund" href="/reference/payment-refund" icon="arrow-right" horizontal>
    как возврат взаимодействует со сплитами.
  </Card>

  <Card title="POST /v1/balance" href="/reference/balance" icon="arrow-right" horizontal />

  <Card title="POST /v1/auto-withdraw/*" href="/reference/auto-withdraw" icon="arrow-right" horizontal />
</CardGroup>