API нового заказа

В примерах использована авторизация под администратором и выполнение функций с правами клиента. О способах авторизации вы можете узнать в статье взаимодействие через API.

Глоссарий

cart — новая корзина. Каждый клиент имеет одну корзину для каждого провайдера. Например, клиент относится к одному провайдеру, значит он имеет одну корзину и все позиции, которые он заказывает, попадают в эту корзину.

lineitem.id — позиция новой корзины.

order — заказ — одна или несколько позиций из корзины, для которых создаётся платёж.

Добавление позиции в корзину

API нового заказа похож на API старого заказа, поэтому значения дополнений и параметров передаются аналогично, дополнительные и отличающиеся параметры описаны ниже в таблице.

Для типов продукта SSL и Домен используйте функции вида {ITEMTYPE}.order.param. Чтобы добавить в корзину эти услуги через API с помощью быстрого заказа, используйте API старого заказа с параметрами clicked_button=quickbasket и force_use_new_cart=on.

Имя	Описание	Значение	Пример
func *	Функция заказа	v2.{ITEMTYPE}.order.param {ITEMTYPE} — внутреннее имя типа продукта	func=v2.soft.order.param func=v2.vds.order.param func=v2.dedic.order.param
order_period *	Период заказа	Принимает одно из следующих значений: 1 — месяц 3 — 3 месяца 6 — 6 месяцев 12 — год 24 — 2 года 36 — 3 года	order_period=1
pricelist *	Идентификатор тарифного плана	Целочисленное значение	pricelist=111
sok *	Подтверждение операции	ok	sok=ok
clicked_button *	Подтип операции	order	clicked_button=order
autoprolong	Включить автопродление Флаг	Принимает одно из следующих значений: on off	autoprolong=on
datacenter	Идентификатор дата-центра, в котором будет открываться услуга	Целочисленное значение	datacenter=2
force_use_new_cart	Включить использование новой корзины Флаг	Принимает одно из следующих значений: on off	force_use_new_cart=on
out	Формат ответа	Принимает одно из следующих значений: xml xjson devel text	out=xml
addon_{ADDON_PRICELIST_ID}	Значение дополнения	Значение зависит от настройки дополнения в тарифном плане Дополнения тарифного плана по API передаются через параметр addon_. Например, addon_5=10, где 5 — код дополнения, 10 — значение. Чтобы найти код дополнения, перейдите в Продукты → Тарифные планы → кнопка Конфиг. → поле Id	addon_12=126
skipbasket	Включить оплату услуги с лицевого счёта без помещения в корзину Флаг	Принимает одно из следующих значений: on off	skipbasket=on

* — обязательный параметр

Пример запроса добавления позиции в корзину:

curl -X POST -k https://domain.com/billmgr \
	-d 'authinfo=admin_login:admin_password' \
	-d 'su=client_login' \
	-d 'out=xml' \
	-d 'sok=ok' \
	-d 'force_use_new_cart=on' \
	-d 'func=v2.{ITEMTYPE}.order.param' \
	-d 'datacenter={DATACENTER_ID}' \
	-d 'pricelist={PRICELIST_ID}' \
	-d 'addon_{ADDON_PRICELIST_ID}={ADDON_VALUE}' \
	-d 'order_period={PERIOD}' \
	-d 'clicked_button=order'

Пример с указанием значений

Ответ будет содержать id позиции новой корзины lineitem.id.

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

<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
	...
	<lineitem.id>497</lineitem.id>
	...
</doc>

Операции с корзиной

Имя	Описание	Значение	Пример
func *	Функция корзины	cart	func=cart
clicked_button	Подтип операции	Принимает одно из следующих значений: activate — активация выбранных бесплатных позиций delete — удаление выбранных позиций apply_promocode — применение промокода ко всей корзине, независимо от выбранных позиций (нужен параметр promocode)	clicked_button=activate clicked_button=delete clicked_button=apply_promocode
selected	Позиции (lineitem) выбранные для совершения операции	Список целочисленных значений Разделитель ','	selected=105,106,107
sok	Подтверждение операции Необходимо указать в запросе, если присутствует параметр clicked_button	ok	sok=ok
promocode	Промокод Необходимо указать, если параметр clicked_button=apply_promocode	Промокод	promocode=IDDQD

* — обязательный параметр

Сводная информация по заказу

Функция: Cartorder

Возвращает сводную информацию по созданному заказу для отображения в интерфейсе:

curl -X POST -k https://domain.com/billmgr \
-d 'authinfo=admin_login:admin_password' \
-d 'su=client_login' \
-d 'func=cartorder' \
-d 'elid={billorder}'

где elid — идентификатор заказа (billorder)

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

<?xml version="1.0" encoding="UTF-8"?>
<doc lang="ru" func="cartorder" binary="/billmgr" host="https://ubu.lxc:1500" themename="dragon" features="25d83c4f3f3fa0d69d63c201cad676d2" notify="" theme="/manimg/dragon/">
	<list name="payment_info_list">
		<elem is_json_array="yes">
			<img img="m-account" width="20px" height="15px" sprite="yes" spritesvg="yes"/>
			<profile size="h3">notav@example.com, физ. лицо</profile>
		</elem>
		<elem is_json_array="yes">
			<img img="card" width="18px" height="16px" spritesvg="yes"/>
			<to_pay size="h3">К оплате 20.00 RUB</to_pay>
		</elem>
	</list>
	<list name="general_info">
		<elem is_json_array="yes">
			<position_count>1 позиция</position_count>
		</elem>
	</list>
	<list name="details">
		<elem is_json_array="yes">
			<item>oneAddon #4176</item>
			<count>1шт.</count>
			<price>
				<price>
					<currency>RUB</currency>
					<cost>20.00</cost>
				</price>
			</price>
			<configuration>
				<header name="configuration_name" color="main">Услуга</header>
				<header name="configuration_value" color="main">Значение</header>
				<header name="configuration_limit" color="main">Лимит</header>
				<elem is_json_array="yes">
					<configuration_name>oneAddon #4176</configuration_name>
					<configuration_value>Базовая стоимость</configuration_value>
					<configuration_price>
						<price>
							<currency>RUB</currency>
							<cost>10.00</cost>
						</price>
					</configuration_price>
				</elem>
				<elem is_json_array="yes">
					<configuration_name>числовой</configuration_name>
					<configuration_value>10 Шт.</configuration_value>
					<configuration_price>
						<price>
							<currency>RUB</currency>
							<cost>10.00</cost>
						</price>
					</configuration_price>
				</elem>
			</configuration>
			<extra_info>
				<elem is_json_array="yes">
					<autoprolong>
						<input name="autoprolong_4176" type="checkbox" msg_side="left" color_on="green" color_off="red" readonly="yes"/>
					</autoprolong>
				</elem>
			</extra_info>
		</elem>
	</list>
	<autoprolong_4176>off</autoprolong_4176>
	<list name="help_faq">
		<elem is_json_array="yes">
			<link internal="no" target="_blank" name="faq_link_0">https://docs.ispsystem.com/x/9JUHBQ</link>
		</elem>
		<elem is_json_array="yes">
			<link internal="no" target="_blank" name="faq_link_1">https://docs.ispsystem.com/x/ApYHBQ</link>
		</elem>
		<elem is_json_array="yes">
			<link internal="no" target="_blank" name="faq_link_2">https://docs.ispsystem.com/x/LJYHBQ</link>
		</elem>
	</list>
	<list name="help_support">
		<elem is_json_array="yes">
			<link name="help_support_link" internal="yes" newtab="yes">func=clientticket</link>
		</elem>
	</list>
	<elid>689</elid>
	<tparams>
		<elid>689</elid>
		<out>xml</out>
		<func>cartorder</func>
	</tparams>
	<saved_filters/>
</doc>

Примеры

После добавления позиции в корзину возможны разные варианты взаимодействия с клиентом. Ниже приведены следующие примеры:

отображение формы корзины, где клиент самостоятельно перейдёт к оформлению;
активация бесплатной позиции;
создание заказа и его оплата.

Отображение формы корзины

Для отображения формы корзины отправьте пользователя по ссылке вида:

https://domain.com/billmgr?startform=cart&selected={lineitem.id}

Перейдя по ссылке клиент окажется в корзине с выбранной позицией (lineitem.id) и её стоимостью и сможет перейти к оплате заказанной позиции либо продолжить покупки.

Используйте этот вариант взаимодействия, если:

для оплаты необходим плательщик, но клиент ещё не создавал его. При оформлении заказа клиент укажет все необходимые данные для плательщика через интерфейс биллинговой платформы;
необходимо подтверждение телефона или почты перед оплатой. При оформлении заказа клиенту будет предложено пройти верификацию.

Активация бесплатной позиции

Активировать бесплатную позицию можно двумя путями: указать skipbasket=on при заказе услуги либо воспользоваться запросом:

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

curl -X POST -k https://domain.com/billmgr \
	-d 'authinfo=admin_login:admin_password' \
	-d 'su=client_login' \
	-d 'out=xml' \
	-d 'sok=ok' \
	-d 'func=cart' \
	-d 'selected={lineitem.id}' \
	-d 'clicked_button=activate'

Если запрос завершился успешно, то позиции объединятся в заказ (billorder) и будут обработаны в ближайшее время.

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

<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
	...
	<billorder saveoutput="yes">555</billorder>
	...
</doc>

Создание и оплата заказа

Для получения ссылки на оплату необходимо создать и подтвердить заказ выбранных позиций (lineitem).

Имя	Описание	Значение	Пример
func *	Функция создания заказа для выбранных позиций	cartorder.create.confirm	func=cartorder.create.confirm
elid *	Позиции (lineitem), выбранные для заказа	Список целочисленных значений разделитель ','	elid=105,106,107
sok *	Подтверждение операции	ok	sok=ok
Способ оплаты * paymethod_id или storedmethod_id Обратите внимание! Параметры взаимоисключающие, укажите в запросе только один из них	paymethod_id — идентификатор метода оплаты. Для метода оплаты могут требоваться дополнительные параметры, например, для ЮKassa нужно указать payment_method Для определения таких параметров см. статью Взаимодействие через API storedmethod_id — идентификатор сохранённого способа оплаты клиента	Целочисленное значение Укажите paymethod_id=0, чтобы в качестве метода оплаты использовать лицевой счёт	paymethod_id=15 storedmethod_id=455
profile_id	Идентификатор плательщика Указывается, если плательщик требуется для выбранного метода оплаты	Целочисленное значение	profile_id=42
store_paymethod	Если параметр принимает значение "on" и метод оплаты поддерживает возможность сохранить выбранный метод оплаты, то для клиента метод этой оплаты будет сохранён Флаг	Принимает одно из следующих значений: on off	store_paymethod=on

* — обязательный параметр

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

curl -X POST -k https://domain.com/billmgr \
	-d 'authinfo=admin_login:admin_password' \
	-d 'su=client_login' \
	-d 'sok=ok' \
	-d 'func=cartorder.create.confirm' \
	-d 'elid=506' \
	-d 'paymethod_id=3' \ // ЮKassa
	-d 'profile_id=72' \
	-d 'payment_method=bank_card' // Оплата по карте

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

<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
	...
	<billorder saveoutput="yes">663</billorder>
	<payment_id saveoutput="yes">755</payment_id>
	<ok type="blank" on_blank_redirect_action="func=cartorder&elid=663">/mancgi/ycpayment?elid=755</ok>
	...
</doc>

Пояснения