Перейти к содержимому
🔌 API
v2

Подписки

Подписки в API Radist.Online: как подключения привязываются к подписке, расчёт оставшегося срока по paid_until, реквизиты ИП и ООО для счетов.

Общее

Swagger: https://api.radist.online/v2/docs#/Subscriptions

Необходимые права доступа (scopes) для работы с API: subscriptions

Подписка — сущность, к которой прикреплены подключения. Подключение, которое не в подписке, или в неоплаченной подписке, не работает.

Реквизиты — реквизиты ИП или ООО. Используются для выставления счетов на оплату.

Срок подписки

Пример подписки

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "id": 1926,
  "connections": [
    29228,
    30111
  ],
  "subscription_type": "CONNECTION_TELEGRAM_BOT",
  "subscription_plan": "STANDARD",
  "current_size": 2,
  "max_size": 4,
  "test_until": "2022-11-27T07:17:28.784647Z",
  "paid_until": "2220-05-25T13:38:57.518834Z"
}

Оставшийся срок подписки = paid_until - {текущие дата и время}

Примеры

Изменить список подключений в подписке
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// После этой операции в подписке будет 2 подключения: 29228, 30111.

// В подписке может быть от 0 до `max_size` подключений.

PATCH /companies/{company_id}/subscriptions/{subscription_id}
{"connections":[29228, 30111], "preview": false}


Response
{
  "id": 1926,
  "connections": [
    29228,
    30111
  ],
  "subscription_type": "CONNECTION_TELEGRAM_BOT",
  "subscription_plan": "STANDARD",
  "current_size": 2,
  "max_size": 4,
  "test_until": "2022-11-27T07:17:28.784647Z",
  "paid_until": "2220-05-25T13:38:57.518834Z"
}
Добавить реквизиты
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

POST /companies/{company_id}/subscriptions/requisites/
{
  "tin": "1699982918",
  "kpp": "770101001",
  "name": "ООО \"Маша и Миша\""
}


Response
{
  "id": 2004,
  "tin": "1699982918",
  "kpp": "770101001",
  "name": "ООО \"Маша и Миша\"",
  "approval_status": "APPROVED"
}
Выставить счёт на оплату подписок и WABA-диалогов
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

// Меняем размер подписки 1926 с 2 до 4 подключений (в рамках уже
// оплаченного max_size), план подписки не меняется. Плюс 100 WABA-диалогов.

// Получим предпросмотр (preview=true, значение по умолчанию).
// Это не создаст счёт, но даст итоговую стоимость и состав счёта.
// Чтобы сформировать настоящий счёт, передайте preview=false.

// Для не-предпросмотра обязательно нужно передать consents.offer_accepted=true.

// new_subscription_plan - FREE, START, STANDARD (ADVANCED больше не доступен)

// payment_method - CARD_RU (карта РФ), CARD_OTHER (карта не РФ),
// BANK_TRANSFER (банковский перевод, обязательно передать company_requisite_id)

// card_provider - ROBOKASSA или KEEPZ: эквайер, который примет оплату.
// Обязателен при payment_method=CARD_OTHER и запрещён при остальных способах
// оплаты. KEEPZ доступен только компаниям, которые платят в рублях: счёт
// остаётся рублёвым, но с карты спишутся доллары по курсу ЦБ РФ.

POST /companies/{company_id}/subscriptions/invoices/
{
  "preview": true,
  "items": [
    {
      "type": "SUBSCRIPTION",
      "id": 1926,
      "new_subscription_plan": "STANDARD",
      "new_size": 4
    },
    {
      "type": "WABA_DIALOGS",
      "count": 100
    }
  ],
  "consents": {
    "offer_accepted": true
  },
  "payment_method": "CARD_RU",
  "period_months": 3,
  "promo_code": null // Указать, если есть
}


Response // Это предпросмотр (id=null, preview=true)
{
  "id": null,
  "preview": true,
  "status": "new",
  "lifetime": "2024-12-09T10:34:03.947066Z",
  "summary": {
    "payment_method": "CARD_RU",
    "card_provider": null,
    "charge_currency": null,
    "charge_amount": null,
    "conversion_rate": null,
    "conversion_rate_date": null,
    "period_months": 3,
    "items": [
      {
        "type": "SUBSCRIPTION",
        "subscription_id": 1926,
        "subscription_type": "CONNECTION_TELEGRAM_BOT",
        "old_size": 2,
        "new_size": 4,
        "old_subscription_plan": "STANDARD",
        "new_subscription_plan": "STANDARD",
        "old_paid_until": "2024-09-09T10:34:03.947066Z",
        "top_up_amount": {
          "amount": 4860,
          "discount": 486,
          "discounts": {
            "period_discount_percent": 10,
            "quantity_discount_percent": 0,
            "promo_discount_percent": 0,
            "partner_discount_percent": 0,
            "test_period_discount_percent": 0,
            "partner_balance_discount_flat": 0
          }
        },
        "upgrade_amount": {
          "amount": 0,
          "discount": 0,
          "discounts": {
            "period_discount_percent": 0,
            "quantity_discount_percent": 0,
            "promo_discount_percent": 0,
            "partner_discount_percent": 0,
            "test_period_discount_percent": 0,
            "partner_balance_discount_flat": 0
          }
        }
      },
      {
        "type": "WABA_DIALOGS",
        "count": 100,
        "price": 10.6915,
        "top_up_amount": {
          "amount": 1069.15,
          "discount": 0,
          "discounts": {
            "partner_balance_discount_flat": 0
          }
        }
      }
    ],
    "promo_code": null,
    "total_discount": 486,
    "partner_discount_percent": 0,
    "company_requisite": null
  },
  "amount": 5443.15,
  "currency": "RUB",
  "payment_url": null,
  "preview_url": "https://invoices.radist.online/private/invoices/06019947-8962-4129-8276-cd9c388e4ba1",
  "act_url": null,
  "receipt": {
    "items": [
      {
        "name": "Лицензия на ПО для ЭВМ \"Telegram Bot Radist.Online\" (Стандартный)",
        "quantity": 1,
        "price": 4374,
        "vat": "none",
        "tax_name": "Без НДС",
        "tax_value": null
      },
      {
        "name": "Лицензия на ПО для ЭВМ Radist.Online, диалоги для переписок",
        "quantity": 1,
        "price": 1069.15,
        "vat": "none",
        "tax_name": "Без НДС",
        "tax_value": null
      }
    ]
  },
  "created_at": "2024-12-02T10:34:03.945486Z"
}

Если у подписки меняется план (new_subscription_plan отличается от текущего), в счёте дополнительно появится ненулевой upgrade_amount, а в чеке — отдельная строка “Расширение”.

Выставить счёт с оплатой картой не РФ
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// Оплату картой не РФ (payment_method=CARD_OTHER) принимает один из двух
// эквайеров, и его обязательно нужно выбрать в card_provider:
//   ROBOKASSA - с карты списываются рубли, как и раньше;
//   KEEPZ     - счёт остаётся рублёвым, но с карты спишутся доллары
//               по курсу ЦБ РФ.
// При остальных способах оплаты card_provider передавать нельзя.

POST /companies/{company_id}/subscriptions/invoices/
{
  "preview": true,
  "items": [
    {
      "type": "WABA_DIALOGS",
      "count": 100
    }
  ],
  "consents": {
    "offer_accepted": true
  },
  "payment_method": "CARD_OTHER",
  "card_provider": "KEEPZ"
}


Response // предпросмотр; поля, не связанные со списанием, — как в примере выше
{
  "id": null,
  "preview": true,
  "status": "new",
  "summary": {
    "payment_method": "CARD_OTHER",
    "card_provider": "KEEPZ",
    "charge_currency": "USD",
    "charge_amount": 13.05,
    "conversion_rate": 81.9234,
    "conversion_rate_date": "2026-09-07",
    "period_months": 0,
    "items": [
      // состав счёта - как в примере выше
    ],
    "promo_code": null,
    "total_discount": 0,
    "partner_discount_percent": 0,
    "company_requisite": null
  },
  "amount": 1069.15,
  "currency": "RUB"
}

Поля списания приходят в summary и у предпросмотра, и у настоящего счёта:

  • card_provider — эквайер, который принял оплату: ROBOKASSA, KEEPZ или null. null — у оплат картой РФ, банковским переводом и с партнёрского баланса: эквайера там нет.
  • charge_currency — валюта, в которой деньги спишутся с карты (USD), или null.
  • charge_amount — сумма списания в charge_currency.
  • conversion_rate — курс ЦБ РФ, рублей за доллар.
  • conversion_rate_date — дата курса в формате YYYY-MM-DD.

Четыре последних поля равны null, когда эквайер списывает деньги в валюте самого счёта, — то есть у всех оплат, кроме Keepz. Счёт Keepz остаётся рублёвым: amount, currency и суммы в чеке не меняются, а charge_amount — это то, что плательщик увидит в выписке по карте. Курс меняется, поэтому сумма списания актуальна на момент того предпросмотра, из которого создан счёт.

Ошибки:

  1. Если при payment_method=CARD_OTHER не передать card_provider — или передать его при другом способе оплаты, — метод вернёт ошибку 1 (REQUEST_VALIDATION_ERROR) со статусом 422.
  2. card_provider=KEEPZ вернёт ошибку 18003 (INVOICE_PROVIDER_ERROR) со статусом 400, если компания платит не в рублях, если терминал Keepz ещё не подключён на нашей стороне или если не удалось получить курс ЦБ РФ.
Помогла ли статья?
Последнее обновление
ПартнёркаКомпания