Группа методов  Bill  внешнего программного интерфейса менеджера сервиса предназначена для работы со счетами клиентам.

Сводка по методам

МетодОписание
root
listСписок счетов на оплату
infoИнформация о счете на оплату
createСоздать счет  на оплату
updateИзменить счет  на оплату
create_subscriptionСоздать подписки на тарифы сервиса на основании счета на оплату
file_token
uploadПолучить талон на загрузку файла, прикрепляемого к счету на оплату

bill/list

Метод возвращает список счетов на оплату

ПараметрТипОписаниеПример
Запрос
seller_id *Число (+12.0)Код продавца1000
customer_id *Число (+12.0)Код покупателя2000
start_date *Дата и время в строке формата ISOДата начала30.07.2020 0:00:00
end_date *Дата и время в строке формата ISOДата окончания30.07.2020 0:00:00
Ответ:  bill  (0..*)
idСтрока переменная (9)Номер счета000000002
createdДата и время в строке формата ISOДата оформления счета28.07.2020 0:00:00
modifiedДата и время в строке формата ISOДата последнего изменения счета30.07.2020 0:00:00
bill_id *Строка фиксированная (36)Идентификатор счетаe6e123dd-10ac-4e43-ab02-6a2b2b36140d
seller_idЧисло (+12.0)Код продавца1000
customer_idЧисло (+12.0)Код покупателя2000
renewal *БулевоПродлениеtrue
total_cost *Число (+31.2)Сумма счета4000
payment_link *Строка неограниченной длиныПлатежная ссылкаhttps://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371
paid *БулевоОплаченfalse
add_info *Строка неограниченной длиныДополнительная информация
comment *Строка неограниченной длиныКомментарий счетаКомментарий счета на оплату
Пример запроса  Развернуть
{
  "auth": {
    "account": 1010
  },
  "general": {
    "version": 13,
    "type": "usr",
    "method": "bill/list",
    "debug": true
  }
}
Пример ответа  Развернуть
{
  "bill": [
    {
      "id": "000000002",
      "created": "2020-07-28T00:00:00",
      "modified": "2020-07-30T00:00:00",
      "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
      "seller_id": 1000,
      "customer_id": 2000,
      "renewal": true,
      "total_cost": 4000,
      "payment_link": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371",
      "paid": false,
      "add_info": "",
      "comment": "Комментарий счета на оплату"
    }
  ],
  "general": {
    "response": 10200,
    "error": false,
    "message": "",
    "version": 13,
    "sm_version": "1.0.100.12",
    "sm_timezone": "Europe/Moscow"
  }
}

Вверх

bill/info

Метод возвращает информацию о счете на оплату

ПараметрТипОписаниеПример
Запрос
id *Строка переменная (9)Номер счета для поиска. Обязательно, если не указан идентификатор счета.000000002
bill_id *Строка фиксированная (36)Идентификатор счета для поиска. Обязательно, если не указан номер счета.e6e123dd-10ac-4e43-ab02-6a2b2b36140d
Ответ:  bill  (1)
idСтрока переменная (9)Номер счета000000002
createdДата и время в строке формата ISOДата оформления счета28.07.2020 0:00:00
modifiedДата и время в строке формата ISOДата последнего изменения счета30.07.2020 0:00:00
bill_idСтрока фиксированная (36)Идентификатор счетаe6e123dd-10ac-4e43-ab02-6a2b2b36140d
seller_idЧисло (+12.0)Код продавца1000
customer_idЧисло (+12.0)Код покупателя2000
renewal *БулевоПродлениеtrue
total_cost *Число (+31.2)Сумма счета4000
payment_link *Строка неограниченной длиныПлатежная ссылкаhttps://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371
paid *БулевоОплаченfalse
add_info *Строка неограниченной длиныДополнительная информация
comment *Строка неограниченной длиныКомментарий счетаКомментарий счета на оплату
tariffsСписок (0..*)Тарифы
  - tariff_idСтрока переменная (9)Код тарифа512
  - servant_tariff_id *Строка переменная (9)Код тарифа обслуживающей организации00007
  - period_idСтрока переменная (10)Код периода действия1MN
  - basis_id *Строка переменная (9)Код основания000000077
  - amountЧисло (+12.0)Количество (может быть больше 1 для подписок на расширения тарифов)1
  - cost *Число (+31.2)Сумма2000
servicesСписок (0..*)Услуги
  - serviceСтрока переменная (1024)УслугаКонсультации специалиста
  - cost *Число (+31.2)Сумма2000
filesСписок (0..*)Файлы
  - idСтрока фиксированная (36)Идентификатор файла710e7a50-25b5-45e1-ab8a-3a0d657816ae
  - nameСтрока неограниченной длиныОписание файлаСчет.pdf
fieldsСписок (0..*)Дополнительные реквизитыfalse
  - keyСтрока переменная (100)Имя реквизитаТребуется заполнение данных абонента
  - value *Число (любое), Строка неограниченной длины, Дата и время в строке формата ISO, БулевоЗначение реквизитаtrue
  - type *Строка неограниченной длиныТип реквизитаboolean
status *
Состояния счета на оплату
  - name *Строка переменная (17)

Имя состояния:

  • "created" - Создан
  • "wait_sending" - ОжиданиеОтправки
  • "wait_registration" - ОжиданиеОформления
  • "wait_payment" - ОжиданиеОплаты
  • "paid" - Оплачено
  • "billing_error" - ОшибкаВыставленияСчета
paid
  - error *БулевоПризнак ошибкиfalse
  - description *Строка неограниченной длиныОписание состояния
Пример запроса  Развернуть
{
  "id": "000000002",
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "auth": {
    "account": 1010
  },
  "general": {
    "version": 13,
    "type": "usr",
    "method": "bill/info",
    "debug": true
  }
}
Пример ответа  Развернуть
{
  "bill": {
    "id": "000000002",
    "created": "2020-07-28T00:00:00",
    "modified": "2020-07-30T00:00:00",
    "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
    "seller_id": 1000,
    "customer_id": 2000,
    "renewal": true,
    "total_cost": 4000,
    "payment_link": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371",
    "paid": false,
    "add_info": "",
    "comment": "Комментарий счета на оплату",
    "tariffs": [
      {
        "tariff_id": "512",
        "servant_tariff_id": "00007",
        "period_id": "1MN",
        "basis_id": "000000077",
        "amount": 1,
        "cost": 2000
      }
    ],
    "services": [
      {
        "service": "Консультации специалиста",
        "cost": 2000
      }
    ],
    "files": [
      {
        "id": "710e7a50-25b5-45e1-ab8a-3a0d657816ae",
        "name": "Счет.pdf"
      }
    ],
    "fields": [
      {
        "key": "Требуется заполнение данных абонента",
        "value": true,
        "type": "boolean"
      },
    "status": {
      "name": "paid",
      "error": false,
      "description": ""
      }
    ]
  },
  "general": {
    "response": 10200,
    "error": false,
    "message": "",
    "version": 13,
    "sm_version": "1.0.100.12",
    "sm_timezone": "Europe/Moscow"
  }
}

Вверх

bill/create

Метод создает новый счет на оплату

ПараметрТипОписаниеПример
Запрос
bill_id *Строка фиксированная (36)Идентификатор счетаe6e123dd-10ac-4e43-ab02-6a2b2b36140d
seller_idЧисло (+12.0)Код продавца1000
customer_idЧисло (+12.0)Код покупателя2000
renewal *БулевоПродлениеtrue
total_cost *Число (+31.2)Сумма счета4000
payment_link *Строка неограниченной длиныПлатежная ссылкаhttps://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371
paid *БулевоОплаченfalse
add_info *Строка неограниченной длиныДополнительная информация
comment *Строка неограниченной длиныКомментарий счетаКомментарий счета на оплату
tariffs *
Тарифы
  - tariff_idСтрока переменная (9)Код тарифа512
  - servant_tariff_id *Строка переменная (9)Код тарифа обслуживающей организации00007
  - period_idСтрока переменная (10)Код периода действия1MN
  - basis_id *Строка переменная (9)Код основания000000077
  - amountЧисло (+12.0)Количество (может быть больше 1 для подписок на расширения тарифов)1
  - cost *Число (+31.2)Сумма2000
services *
Услуги
  - serviceСтрока переменная (1024)УслугаКонсультации специалиста
  - cost *Число (+31.2)Сумма2000
files *
Файлы
  - idСтрока фиксированная (36)Идентификатор файла710e7a50-25b5-45e1-ab8a-3a0d657816ae
  - nameСтрока неограниченной длиныОписание файлаСчет.pdf
fields *
Дополнительные реквизитыfalse
  - keyСтрока переменная (100)Имя реквизитаТребуется заполнение данных абонента
  - value *Число (любое), Строка неограниченной длины, Дата и время в строке формата ISO, БулевоЗначение реквизитаtrue
  - type *Строка неограниченной длиныТип реквизитаboolean
Ответ
idСтрока переменная (9)Номер счета000000002
bill_idСтрока фиксированная (36)Идентификатор счетаe6e123dd-10ac-4e43-ab02-6a2b2b36140d
Пример запроса  Развернуть
{
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "seller_id": 1000,
  "customer_id": 2000,
  "renewal": true,
  "total_cost": 4000,
  "payment_link": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371",
  "paid": false,
  "add_info": "",
  "comment": "Комментарий счета на оплату",
  "tariffs": [
    {
      "tariff_id": "512",
      "servant_tariff_id": "00007",
      "period_id": "1MN",
      "basis_id": "000000077",
      "amount: 1,
      "cost": 2000
    }
  ],
  "services": [
    {
      "service": "Консультации специалиста",
      "cost": 2000
    }
  ],
  "files": [
    {
      "id": "710e7a50-25b5-45e1-ab8a-3a0d657816ae",
      "name": "Счет.pdf"
    }
  ],
  "fields": [
    {
      "key": "Требуется заполнение данных абонента",
      "value": true,
      "type": "boolean"
    }
  ],
  "auth": {
    "account": 1000
  },
  "general": {
    "version": 13,
    "type": "usr",
    "method": "bill/create",
    "debug": true
  }
}
Пример ответа  Развернуть
{
  "id": "000000002",
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "general": {
    "response": 10200,
    "error": false,
    "message": "",
    "version": 13,
    "sm_version": "1.0.100.12",
    "sm_timezone": "Europe/Moscow"
  }
}

Вверх

bill/update

Метод изменяет счет на оплату

ПараметрТипОписаниеПример
Запрос
id *Строка переменная (9)Номер счета для поиска. Обязательно, если не указан идентификатор счета.000000002
bill_id *Строка фиксированная (36)Идентификатор счета для поиска. Обязательно, если не указан номер счета.e6e123dd-10ac-4e43-ab02-6a2b2b36140d
seller_idЧисло (+12.0)Код продавца1000
customer_idЧисло (+12.0)Код покупателя2000
renewal *БулевоПродлениеtrue
total_cost *Число (+31.2)Сумма счета4000
payment_link *Строка неограниченной длиныПлатежная ссылкаhttps://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371
paid *БулевоОплаченfalse
add_info *Строка неограниченной длиныДополнительная информация
comment *Строка неограниченной длиныКомментарий счетаКомментарий счета на оплату
tariffs *
Тарифы
  - tariff_idСтрока переменная (9)Код тарифа512
  - servant_tariff_id *Строка переменная (9)Код тарифа обслуживающей организации00007
  - period_idСтрока переменная (10)Код периода действия1MN
  - basis_id *Строка переменная (9)Код основания000000077
  - amountЧисло (+12.0)Количество (может быть больше 1 для подписок на расширения тарифов)1
  - cost *Число (+31.2)Сумма2000
services *
Услуги
  - serviceСтрока переменная (1024)УслугаКонсультации специалиста
  - cost *Число (+31.2)Сумма2000
files *
Файлы
  - idСтрока фиксированная (36)Идентификатор файла710e7a50-25b5-45e1-ab8a-3a0d657816ae
  - nameСтрока неограниченной длиныОписание файлаСчет.pdf
fields *
Дополнительные реквизитыfalse
  - keyСтрока переменная (100)Имя реквизитаТребуется заполнение данных абонента
  - value *Число (любое), Строка неограниченной длины, Дата и время в строке формата ISO, БулевоЗначение реквизитаtrue
  - type *Строка неограниченной длиныТип реквизитаboolean
Ответ
idСтрока переменная (9)Номер счета000000002
bill_idСтрока фиксированная (36)Идентификатор счетаe6e123dd-10ac-4e43-ab02-6a2b2b36140d
Пример запроса  Развернуть
{
  "id": "000000002",
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "seller_id": 1000,
  "customer_id": 2000,
  "renewal": true,
  "total_cost": 4000,
  "payment_link": "https://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=26bcb3ac-000f-5000-8000-178abf269371",
  "paid": false,
  "add_info": "",
  "comment": "Комментарий счета на оплату",
  "tariffs": [
    {
      "tariff_id": "512",
      "servant_tariff_id": "00007",
      "period_id": "1MN",
      "basis_id": "000000077",
      "amount": 1,
      "cost": 2000
    }
  ],
  "services": [
    {
      "service": "Консультации специалиста",
      "cost": 2000
    }
  ],
  "files": [
    {
      "id": "710e7a50-25b5-45e1-ab8a-3a0d657816ae",
      "name": "Счет.pdf"
    }
  ],
  "fields": [
    {
      "key": "Требуется заполнение данных абонента",
      "value": true,
      "type": "boolean"
    }
  ],
  "auth": {
    "account": 1000
  },
  "general": {
    "version": 13,
    "type": "usr",
    "method": "bill/update",
    "debug": true
  }
}
Пример ответа  Развернуть
{
  "id": "000000002",
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "general": {
    "response": 10200,
    "error": false,
    "message": "",
    "version": 13,
    "sm_version": "1.0.100.12",
    "sm_timezone": "Europe/Moscow"
  }
}

Вверх

bill/create_subscription

Метод позволяет оформить подписки  на тарифы сервиса на основании счета на оплату

ПараметрТипОписаниеПример
Запрос
id *Строка переменная (9)Номер счета для поиска. Обязательно, если не указан идентификатор счета.000000002
bill_id *Строка фиксированная (36)Идентификатор счета для поиска. Обязательно, если не указан номер счета.e6e123dd-10ac-4e43-ab02-6a2b2b36140d
start *Дата и время в строке формата ISOНачало действия создаваемых подписок08.11.2022 0:00:00
Ответ:  subscription  (0..*)
idСтрока переменная (9)Номер созданной подписки000000002
Пример запроса  Развернуть
POST a/adm/hs/ext_api/execute/usr/bill/create_subscription
Content-Type: application/json; charset=utf-8

{
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "start": "2022-11-08T00:00:00",
  "auth": {
    "account": 1010
  }
}
Пример ответа  Развернуть
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "subscription": [
    {
      "id": "000000002"
    }
  ],
  "general": {
    "response": 10200,
    "error": false,
    "message": "",
    "version": 23,
    "sm_version": "1.1.20.11",
    "sm_timezone": "Europe/Moscow"
  }
}

В результате выполнения метода будут созданы подписки по данным счета на оплату

Порядок привязки к основному тарифу:

  • В подписке указан основной тариф – все расширения привязываются к этому тарифу
  • В подписке указано несколько основных тарифов:
    • Можно привязать только к одному из тарифов – привязка осуществляется к этому тарифу
    • Можно привязать к нескольким тарифам – привязывается к тому, который первый может содержать эти расширения в порядке тарифов в счете.

Возможные ошибки:

  • Для тарифов-расширений не указаны основные подписки, к которым можно привязать расширения и не указан основной тариф.
  • Стандартные ошибки проверок при оформлении подписок

Вверх

bill/file_token/upload

Метод для получения талона на загрузку файла, прикрепляемого к счету на оплату.

ПараметрТипОписаниеПример
Запрос
id *Строка переменная (9)Номер счета для поиска. Обязательно, если не указан идентификатор счета.000000002
bill_id *Строка фиксированная (36)Идентификатор счета для поиска. Обязательно, если не указан номер счета.e6e123dd-10ac-4e43-ab02-6a2b2b36140d
nameСтрока переменная (255)Имя файлаbill.pdf
sizeЧисло (+15.0)Размер файла (байт)52428800
Ответ
id *Строка переменная (9)Номер счета000000002
bill_id *Строка фиксированная (36)Идентификатор счетаe6e123dd-10ac-4e43-ab02-6a2b2b36140d
direction *Строка переменная (8)Направление передачи данныхupload
token *Строка переменная (64)Талон на загрузку файлаbacff7f85e0fec5a0aba0b7a2e705a7c09b352dc196b45cab40897aae42a59eb
url *Строка неограниченной длиныАдрес для загрузки (PUT)http://example.com/sm/hs/dt/upload/bacff7f85e0fec5a0aba0b7a2e705a7c09b352dc196b45cab40897aae42a59eb
Пример запроса  Развернуть
{
  "id": "000000002",
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "name": "bill.pdf",
  "size": 52428800,
  "general": {
    "version": 13,
    "type": "usr",
    "method": "bill/file_token/upload",
    "debug": true
  }
}
Пример ответа  Развернуть
{
  "id": "000000002",
  "bill_id": "e6e123dd-10ac-4e43-ab02-6a2b2b36140d",
  "direction": "upload",
  "token": "bacff7f85e0fec5a0aba0b7a2e705a7c09b352dc196b45cab40897aae42a59eb",
  "url": "http://example.com/sm/hs/dt/upload/bacff7f85e0fec5a0aba0b7a2e705a7c09b352dc196b45cab40897aae42a59eb",
  "general": {
    "response": 10200,
    "error": false,
    "message": "",
    "version": 13,
    "sm_version": "1.0.100.12",
    "sm_timezone": "Europe/Moscow"
  }
}

Важная особенность

При загрузке больших файлов (более 500 Мбайт) следует учитывать, что файл может быть доступен для использования лишь через некоторое время после его закачки и получения его идентификатора. Рекомендуется перед использованием файла проверить его фактическую регистрацию в данных менеджера сервиса.


Вверх