Сделки¶
Получение списка доступных полей сделки¶
URI: /BumsTradeApiV01/Deal/listFields.api|xml
Входные параметры¶
Параметр | Тип | Описание |
---|---|---|
ProgramId | integer | ID схемы сделки |
Выходные данные¶
Поле | Тип | Описание |
---|---|---|
Fields | array<object (Name, Translation, Type)> | Массив объектов, где каждый объект является определением поля, содержащим его имя тип и перевод. |
Карточка сделки¶
URI: /BumsTradeApiV01/Deal/card.api|xml
Входные параметры¶
Параметр | Тип | Описание |
---|---|---|
Id | integer | ID сделки |
RequestedFields | array | Запрашиваемые поля ( меняет набор полей по умолчанию ) |
ExtraFields | array | Дополнительные поля ( дополняют набор полей по умолчанию ) |
Выходные данные¶
Параметр | Тип | Описание |
---|---|---|
Id | integer | ID сделки |
GUID | integer | GUID сделки |
Name | string | Имя (номер) сделки |
Description | string | Описание сделки |
TimeCreated | datetime | Время создания |
TimeUpdated | datetime | Время обновления |
IsDraft | bool | Является ли сделка черновиком |
IsPaid | bool | Является ли сделка оплаченой |
Contractor | object(Id,Name) | Клиент |
Contact | object(Id,Name) | Контактное лицо |
Payer | object(Id,Name) | Плательщик |
Owner | object(Id,Name) | Создатель (сотрудник) |
Positions | array(object(Id,Name,Count,DeclaredPrice,DiscountType,DiscountValue,Cost)) | Позиции сделки |
Auditors | array(object(Id,Name)) | Аудиторы (сотрудники) |
Manager | object(Id,Name) | Менеджер (сотрудник) |
FinalPrice | object(Value,CurrencyId,Rate) | К оплате |
Status | object(Id,Name) | Статус сделки |
ProgramId | integer | ID программы |
ProgramId | object(Id, Name) | Программа |
RelatedObjects | object(Id, Name, Type) | Связанные объекты |
PossibleTransitions | object(Id, Name, Comment, Disabled, Destination(Id, Name, Type, Color)) | Возможные переходы |
Пример ответа в JSON-формате¶
{
"status": {
"code": "ok",
"message": null
},
"data": {
"deal": {
"Id": "149",
"GUID": "",
"Name": "№1",
"Description": "Клиент хочет того и этого",
"Contractor": {
"Id": 1000001,
"Name": "ООО \"Наша Компания\""
},
"TimeCreated": "2016-11-11 15:37:16",
"TimeUpdated": "2016-11-11 17:27:29",
"Owner": {
"Id": 1000001,
"Name": "User Name"
},
"IsDraft": false,
"Positions": [{
"Id": "260",
"Name": "То",
"Count": "1",
"DeclaredPrice": {
"Value": 73,
"Currency": "руб.",
"CurrencyId": 1,
"CurrencyAbbreviation": "RUR",
"Rate": 1
},
"DiscountType": "2",
"DiscountValue": "0",
"Cost": {
"Value": 73,
"Currency": "руб.",
"CurrencyId": 1,
"CurrencyAbbreviation": "RUR",
"Rate": 1
},
"Offer": {
"Id": 366,
"Tax": {
"Id": 4,
"Name": "НДС"
},
"Unit": {
"Id": 1,
"Name": "шт."
},
"Name": "То"
}
}, {
"Id": "261",
"Name": "Это",
"Count": "1",
"DeclaredPrice": {
"Value": 42,
"Currency": "руб.",
"CurrencyId": 1,
"CurrencyAbbreviation": "RUR",
"Rate": 1
},
"DiscountType": "2",
"DiscountValue": "0",
"Cost": {
"Value": 42,
"Currency": "руб.",
"CurrencyId": 1,
"CurrencyAbbreviation": "RUR",
"Rate": 1
},
"Offer": {
"Id": 367,
"Tax": {
"Id": 4,
"Name": "НДС"
},
"Unit": {
"Id": 1,
"Name": "шт."
},
"Name": "Это"
}
}],
"IsPaid": false,
"Manager": {
"Id": 1000001,
"Name": "User Name"
},
"FinalPrice": {
"Value": 115,
"Currency": "руб.",
"CurrencyId": 1,
"CurrencyAbbreviation": "RUR",
"Rate": 1
},
"Program": {
"Id": 138,
"Name": "Продажа услуг Интернет-агентства"
},
"RelatedObjects": [{
"Id": 1000402,
"Name": "Сделать \"хорошо\"",
"Type": "task"
}, {
"Id": 150,
"Name": "№2",
"Type": "deal"
}],
"Status": {
"Id": 1322,
"Name": "Запрос"
},
"ProgramId": 138,
"PossibleTransitions": [{
"Id": "trans-2664",
"Name": "Коммерческое предложение",
"Comment": "",
"Disabled": false,
"Destination": {
"Id": 1323,
"Name": "Коммерческое предложение",
"Type": "active",
"Color": "#f3b470"
}
}, {
"Id": "trans-2663",
"Name": "Отложено",
"Comment": "",
"Disabled": false,
"Destination": {
"Id": 1326,
"Name": "Отложено",
"Type": "active",
"Color": "#ff4e00"
}
}, {
"Id": "trans-2665",
"Name": "Отвал",
"Comment": "",
"Disabled": false,
"Destination": {
"Id": 1331,
"Name": "Отвал",
"Type": "negative",
"Color": "#ff8500"
}
}]
}
}
}
Пример ответа в XML-формате¶
<?xml version="1.0" encoding="utf-8"?>
<response>
<status>
<code>ok</code>
<message />
</status>
<data>
<deal>
<id>149</id>
<g_u_i_d />
<name>№1</name>
<description>Клиент хочет того и этого</description>
<contractor>
<id>1000001</id>
<name>ООО "Наша Компания"</name>
</contractor>
<time_created>2016-11-11 15:37:16</time_created>
<time_updated>2016-11-11 17:27:29</time_updated>
<owner>
<id>1000001</id>
<name>User Name</name>
</owner>
<is_draft>0</is_draft>
<positions>
<item>
<id>260</id>
<name>То</name>
<count>1</count>
<declared_price>
<value>73</value>
<currency>руб.</currency>
<currency_id>1</currency_id>
<currency_abbreviation>RUR</currency_abbreviation>
<rate>1</rate>
</declared_price>
<discount_type>2</discount_type>
<discount_value>0</discount_value>
<cost>
<value>73</value>
<currency>руб.</currency>
<currency_id>1</currency_id>
<currency_abbreviation>RUR</currency_abbreviation>
<rate>1</rate>
</cost>
<offer>
<id>366</id>
<tax>
<id>4</id>
<name>НДС</name>
</tax>
<unit>
<id>1</id>
<name>шт.</name>
</unit>
<name>То</name>
</offer>
</item>
<item>
<id>261</id>
<name>Это</name>
<count>1</count>
<declared_price>
<value>42</value>
<currency>руб.</currency>
<currency_id>1</currency_id>
<currency_abbreviation>RUR</currency_abbreviation>
<rate>1</rate>
</declared_price>
<discount_type>2</discount_type>
<discount_value>0</discount_value>
<cost>
<value>42</value>
<currency>руб.</currency>
<currency_id>1</currency_id>
<currency_abbreviation>RUR</currency_abbreviation>
<rate>1</rate>
</cost>
<offer>
<id>367</id>
<tax>
<id>4</id>
<name>НДС</name>
</tax>
<unit>
<id>1</id>
<name>шт.</name>
</unit>
<name>Это</name>
</offer>
</item>
</positions>
<is_paid>0</is_paid>
<manager>
<id>1000001</id>
<name>User Name</name>
</manager>
<final_price>
<value>115</value>
<currency>руб.</currency>
<currency_id>1</currency_id>
<currency_abbreviation>RUR</currency_abbreviation>
<rate>1</rate>
</final_price>
<program>
<id>138</id>
<name>Продажа услуг Интернет-агентства</name>
</program>
<related_objects>
<item>
<id>1000402</id>
<name>Сделать "хорошо"</name>
<type>task</type>
</item>
<item>
<id>150</id>
<name>№2</name>
<type>deal</type>
</item>
</related_objects>
<status>
<id>1322</id>
<name>Запрос</name>
</status>
<program_id>138</program_id>
<possible_transitions>
<item>
<id>trans-2664</id>
<name>Коммерческое предложение</name>
<comment />
<disabled>0</disabled>
<destination>
<id>1323</id>
<name>Коммерческое предложение</name>
<type>active</type>
<color>#f3b470</color>
</destination>
</item>
<item>
<id>trans-2663</id>
<name>Отложено</name>
<comment />
<disabled>0</disabled>
<destination>
<id>1326</id>
<name>Отложено</name>
<type>active</type>
<color>#ff4e00</color>
</destination>
</item>
<item>
<id>trans-2665</id>
<name>Отвал</name>
<comment />
<disabled>0</disabled>
<destination>
<id>1331</id>
<name>Отвал</name>
<type>negative</type>
<color>#ff8500</color>
</destination>
</item>
</possible_transitions>
</deal>
</data>
</response>
Список сделок¶
URI: /BumsTradeApiV01/Deal/list.api|xml
Входные параметры¶
Параметр | Тип | Описание |
---|---|---|
FilterId | integer | Идентификатор фильтра |
FilterFields | array | Массив параметров для фильтрации в формате поле => значение |
RequestedFields | array | Запрашиваемые поля ( меняет набор полей по умолчанию ) |
ExtraFields | array | Дополнительные поля ( дополняют набор полей по умолчанию ) |
Limit | integer | Сколько выбрать объектов (LIMIT) |
Offset | integer | Начиная с какого выбирать объекты (OFFSET) |
Выходные данные (набор полей по умолчанию)¶
Поле | Тип | Описание |
---|---|---|
Id | integer | ID сделки |
GUID | integer | GUID сделки |
Name | string | Название сделки |
Description | string | Описание |
Contractor | object (Id, Name) | Клиент |
TimeCreated | datetime | Дата создания |
TimeUpdated | datetime | Дата изменения |
Owner | object (Id, Name) | Владелец |
Positions | array | (( #dealpositions Позиции сделки)) |
IsPaid | bool | Признак оплаты |
Manager | object (Id, Name) | Менеджер |
FinalPrice | money | Сумма сделки |
Program | object (Id, Name) | Схема сделки |
Поля позиций сделки¶
Поле | Тип | Описание |
---|---|---|
Id | integer | ID позиции сделки |
Name | string | Наименование позиции |
Count | integer | Количество |
DeclaredPrice | float | Заявленная цена |
DiscountType | integer | Тип скидки: 1 - скидка задается в процентах, 2 - в абсолютной величине |
DiscountValue | float | Размер скидки |
Cost | float | Финальная цена |
Поля доступные для фильтрации (параметр FilterFields)¶
Поле | Тип | Описание |
---|---|---|
Name | string | Название сделки |
GUID | integer | GUID сделки |
Description | string | Описание |
Contractor | integer | ID клиента |
Contractor.ActivityType | integer | ID вида деятельности |
Contractor.Status | integer | ID статуса клиента |
Contractor.PersonType | string | Типа лица клиента: human - физическое лицо, company - компания |
Contractor.Birthday | integer | День рождения или основания компании |
Contractor.Responsibles | integer | ID ответственного |
Contractor.Partners | integer | ID партнера |
Contractor.Competitors | integer | ID конкурента |
Contractor.Type | integer | ID типа клиента |
Contractor.Payers | integer | ID плательщика клиента |
Contractor.TimeCreated | datetime | Дата создания клиента |
Contractor.TimeUpdated | datetime | Дата изменения клиента |
Contractor.AdvertisingWay | integer | ID канала привлечения |
Contractor. | Дополнительное поле клиента, созданное пользователем. Cписок полей можно получить с помощью отдельного запроса | |
TimeCreated | datetime | Дата создания |
TimeUpdated | datetime | Дата изменения |
IsPaid | bool | Признак оплаты |
Shipping | bool | Признак отгрузки |
PayForm | integer | ID формы оплаты |
Paid | float | Значение оплаченной сумма |
Payer | integer | ID плательщика |
Manager | integer | ID менеджера |
Price | float | Итоговая сумма сделки |
Program | integer | ID схемы сделки |
Status | integer | ID статуса сделки |
Список схем сделок¶
URI: /BumsTradeApiV01/Program/list.api|xml
Входные параметры¶
Параметр | Тип | Описание |
---|---|---|
Limit | integer | Сколько выбрать объектов (LIMIT) |
Offset | integer | Начиная с какого порядкового номера выбирать объекты (OFFSET) |
Выходные данные¶
Поле | Тип | Описание |
---|---|---|
Id | integer | ID схемы |
Name | string | Название схемы |
Description | string | Описание |
NumerationMask | string | Схема нумерации |
Active | bool | Является ли схема активной |
InitialStatus | object(Id, Name) | Начальный статус |
Statuses | array of object(Id, Name, Color) | Допустимые статусы |
Редактирование/Создание сделки¶
URI: /BumsTradeApiV01/Deal/save.api|xml
Входные параметры¶
Имя поля | Тип | Описание | Примечание |
---|---|---|---|
Id | integer | ID сделки | Если не указан то будет создана новая сделка |
ProgramId | integer | ID программы (схемы) | Обязательное поле при создании сделки. При редактировании игнорируется. |
StatusId | integer | ID статуса сделки | Если не указан при создании сделки, то подбирается автоматически. Если указан при изменении сделки, то статус сделки будет изменён в зависимости от выставленного параметра StrictLogic. |
StrictLogic | boolean | Строгая логика перехода из статуса в статус. По умолчанию: true. | Если включена строгая логика, то для перехода в необходимый статус из текущего должен существовать переход, пользователь должен иметь на него права, отработают все триггеры. Если логика не включена, то статус просто изменится и всё. |
Model[Manager] | integer | Идентификатор пользователя, являющегося менеджером сделки | |
Model[Contractor] | integer | Идентификатор клиента | |
Model[Contact] | integer | Идентификатор контактного лица | |
Model[Auditors] | string | Идентификаторы пользователей являющихся аудиторами по сделке | Id перечисляются через запятую (Пример: „1000005,1013202“) |
Model[Description] | string | Описание сделки | Принимается во внимание только в случае отсутствия у сделки позиций |
Model[Paid][…] | mixed | Заплачено (сумма должна быть передана в текущей базовой валюте системы) | Актуально только при выставленном счете |
Model[Paid][Value] | float | Стоимость | |
Model[Paid][Rate] | float | Курс валюты | |
Model[Paid][Currency] | integer | ID валюты | |
Model[Cost][…] | mixed | Предварительная стоимость (сумма должна быть передана в текущей базовой валюте системы) | Актуально только если в сделке нет товаров |
Model[Cost][Value] | float | Стоимость | |
Model[Cost][Rate] | float | Курс валюты | |
Model[Cost][Currency] | integer | ID валюты | |
Model[Имя_поля][Add] | array | Массив приложенных файлов, должен передаваться POST-запросом | [Имя_поля] с типом «Файл» |
Model[Имя_поля][Add][0…n][Content] | string | Данные(контент файла), закодированные с использованием MIME base64 | |
Model[Имя_поля][Add][0…n][Name] | string | Имя файла | |
Model[Имя_поля][Delete][0…n] | string | Имя файла, который необходимо удалить** | |
Model[Имя_поля] | mixed | Дополнительное поле, созданное пользователем | см. Получение списка доступных полей сделки |
Positions | array | Массив позиций сделок | Если параметр передан при редактировании, то все позиции сделки будут заменены |
Для дополнительного поля с типом пользователь по умолчанию используется Id сотрудника. Для того, чтобы указать клиента, необходимо установить значение contractor:{Id клиента}
. Также можно установить user:{Id пользователя}
Поля позиций сделок (входные параметры)¶
Имя поля | Тип | Описание | Примечание |
---|---|---|---|
Name | string | Наименование позиции | Параметр не используется, если указан OfferId |
OfferId | integer | ID товара | |
Count | integer | Количество товаров в позиции, по умолчанию 1 | |
Price | object | Стоимость позиции | |
Price[Currency] | integer | ID валюты | Если не задано, будет выбрана валюта по умолчанию |
Price[Rate] | float | Курс валюты | Если не задан, будет взят текущий курс валюты в системе |
Price[Value] | float | Значение | |
DiscountType | integer | Тип скидки | Допустимые значения:
|
DiscountValue | object | Значение скидки | |
DiscountValue[Curr ency] | integer | ID валюты скидки (актуально для DiscountType = 2) | Если не задано, будет выбрана валюта по умолчанию |
DiscountValue[Rate] | float | Курс валюты скидки (актуально для DiscountType = 2) | Если не задан, будет взят текущий курс валюты в системе |
DiscountValue[Valu e] | float | Значение скидки |
Выходные данные (поля сделки)¶
Имя поля | Тип | Описание | Примечание |
---|---|---|---|
Id | integer | ID сделки |
Интеграция с интернет-магазинами¶
URI: /BumsTradeApiV01/Deal/createFromOnlineStore.api|xml
Данная команда служит для импорта заказов из интернет-магазинов, поддерживающих выгрузку данных в формате CommerceML 2.
Запрос рекомендуется отправлять методом POST, так как возможен существенный объем CommerceML-выгрузки.
Принятые ограничения¶
- Принимается формат CommerceML 2.05
- Обрабатываются только кириллические названия элементов
- Обрабатываются данные, касающиеся свойств заказа (элемент Документ), контрагента (элемент Контрагент) и товарных позиций (элемент Товар).
- Информация о сделке (заказе) должна храниться в элементе Документ с атрибутом ХозОперация равным «Заказ товара»
- Элементы Документ и Контрагент должны содержать атрибут Ид, в котором содержится GUID соответствующей сделки или контрагента
- Сделка может содержать не более одного контрагента
- Игнорируется элемент ЗначенияРеквизитов
На число одновременно переданных сделок и товаров ограничение не накладывается.
При создании сделки и контрагента проверяется, нет ли таких GUID’ов в базе. При создании товара и единицы измерения проверяются название и (в случае с товаром) цена.
Пример CommerceML-документа¶
Простой документ, содержащий сведения об одной сделке, к которой привязан один контрагент и три товарные позиции.
<?xml version="1.0" encoding="windows-1251"?>
<КоммерческаяИнформация ВерсияСхемы="2.05"
ДатаФормирования="2011-05-26T15:21:14"
ФорматДаты="ДФ=yyyy-MM-dd; ДЛФ=DT"
ФорматВремени="ДФ=ЧЧ:мм:сс; ДЛФ=T"
РазделительДатаВремя="T"
ФорматСуммы="ЧЦ=18; ЧДЦ=2; ЧРД=."
ФорматКоличества="ЧЦ=18; ЧДЦ=2; ЧРД=.">
<Документ>
<Ид>839F810C-8795-11E0-AD8D-88AB4824019B</Ид>
<Номер>5</Номер>
<Дата>2011-05-26</Дата>
<ХозОперация>Заказ товара</ХозОперация>
<Роль>Продавец</Роль>
<Валюта>руб</Валюта>
<Курс>1</Курс>
<Сумма>22100.00</Сумма>
<Контрагенты>
<Контрагент>
<Ид>4DE6F5F8-878C-11E0-9D3B-6EA04824019B</Ид>
<Наименование>ООО "Успех"</Наименование>
<ОфициальноеНаименование></ОфициальноеНаименование>
<ЮридическийАдрес>
<Представление></Представление>
</ЮридическийАдрес>
<Роль>Покупатель</Роль>
</Контрагент>
</Контрагенты>
<Время>14:16:19</Время>
<Комментарий></Комментарий>
<Товары>
<Товар>
<Ид>55</Ид>
<ИдКаталога></ИдКаталога>
<Наименование>Каркас кровати</Наименование>
<БазоваяЕдиница Код="796" НаименованиеПолное="Штука"
МеждународноеСокращение="PCE">шт
</БазоваяЕдиница>
<ЦенаЗаЕдиницу>10000.00</ЦенаЗаЕдиницу>
<Количество>1.00</Количество>
<Сумма>10000</Сумма>
<ЗначенияРеквизитов>
<ЗначениеРеквизита>
<Наименование>ВидНоменклатуры</Наименование>
<Значение>Товар</Значение>
</ЗначениеРеквизита>
<ЗначениеРеквизита>
<Наименование>ТипНоменклатуры</Наименование>
<Значение>Товар</Значение>
</ЗначениеРеквизита>
</ЗначенияРеквизитов>
</Товар>
<Товар>
<Ид>56</Ид>
<ИдКаталога></ИдКаталога>
<Наименование>Мальм 3</Наименование>
<БазоваяЕдиница Код="796" НаименованиеПолное="Штука"
МеждународноеСокращение="PCE">шт
</БазоваяЕдиница>
<Скидки>
<Скидка>
<Наименование>Скидка на товар</Наименование>
<Сумма>900.00</Сумма>
<УчтеноВСумме>true</УчтеноВСумме>
</Скидка>
</Скидки>
<ЦенаЗаЕдиницу>5100.00</ЦенаЗаЕдиницу>
<Количество>1.00</Количество>
<Сумма>5100</Сумма>
<ЗначенияРеквизитов>
<ЗначениеРеквизита>
<Наименование>ВидНоменклатуры</Наименование>
<Значение>Товар</Значение>
</ЗначениеРеквизита>
<ЗначениеРеквизита>
<Наименование>ТипНоменклатуры</Наименование>
<Значение>Товар</Значение>
</ЗначениеРеквизита>
</ЗначенияРеквизитов>
</Товар>
<Товар>
<Ид>477</Ид>
<ИдКаталога></ИдКаталога>
<Наименование>Стол и 4 стула</Наименование>
<БазоваяЕдиница Код="796" НаименованиеПолное="Штука"
МеждународноеСокращение="PCE">шт
</БазоваяЕдиница>
<ЦенаЗаЕдиницу>7000.00</ЦенаЗаЕдиницу>
<Количество>1.00</Количество>
<Сумма>7000</Сумма>
<ЗначенияРеквизитов>
<ЗначениеРеквизита>
<Наименование>ВидНоменклатуры</Наименование>
<Значение>Товар</Значение>
</ЗначениеРеквизита>
<ЗначениеРеквизита>
<Наименование>ТипНоменклатуры</Наименование>
<Значение>Товар</Значение>
</ЗначениеРеквизита>
</ЗначенияРеквизитов>
</Товар>
</Товары>
</Документ>
</КоммерческаяИнформация>
Входные параметры¶
Поле | Тип | Описание |
---|---|---|
CommerceInfo | string | Данные в формате CommerceML 2. Обязательный параметр |
В случае успеха возвращаются идентификаторы сделок, созданных в модуле Продажи. При возникновении ошибок будет выведено сообщение обо всех сделках, при попытке создания которых возникла ошибка.
Если сделка с таким GUID создавалась ранее, она будет проигнорирована целиком, в ответ придет идентификатор ранее созданной сделки.
Пример ответа в JSON-формате¶
{
"status":
{
"code":"ok",
"message":null
},
"params": [],
"data":
{
"Deals":
[
{
"id":1009
},
{
"id":1010
}
]
}
}
Пример ответа в XML-формате¶
<?xml version="1.0" encoding="utf-8"?>
<response>
<status>
<code>ok</code>
<message></message>
</status>
<params> </params>
<data>
<deals>
<item>
<id>1009</id>
</item>
<item>
<id>1010</id>
</item>
</deals>
</data>
</response>
</response>
Привязка сделки или задачи к сделке¶
URI: /BumsTradeApiV01/Deal/saveRelation.api|xml
Входные параметры¶
Параметр | Тип | Описание |
---|---|---|
Id | integer | ID сделки |
RelatedObjectId | integer | ID связываемого объекта |
RelatedObjectType | string | Тип связываемого объекта: deal, task или project |
Выходные данные¶
Аналогичны запросу на карточку сделки.
Отвязка сделки или задачи от сделки¶
URI: /BumsTradeApiV01/Deal/removeRelation.api|xml
Входные параметры¶
Параметр | Тип | Описание |
---|---|---|
Id | integer | ID сделки |
RelatedObjectId | integer | ID отвязываемого объекта |
RelatedObjectType | string | Тип отвязываемого объекта: deal, task или project |
Выходные данные¶
Аналогичны запросу на карточку сделки.
Запуск сценария¶
URI: /BumsTradeApiV01/Deal/runTrigger.api
Входные параметры¶
Параметр | Тип | Описание |
---|---|---|
DealId | integer | ID сделки |
TriggerId | integer | ID сценария |
Выходные данные¶
В случае успешного запуска возвращается Id сделки. Если запуск невозможен из-за несоблюдения условий, в ответе будет содержаться сообщение: «Trigger conditions does not match deal state».