Сделки

Получение списка доступных полей сделки

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 Тип скидки

Допустимые значения:

  • 1 - скидка в процентах
  • 2 - скидка в абсолютном значении
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-выгрузки.

Принятые ограничения

  1. Принимается формат CommerceML 2.05
  2. Обрабатываются только кириллические названия элементов
  3. Обрабатываются данные, касающиеся свойств заказа (элемент Документ), контрагента (элемент Контрагент) и товарных позиций (элемент Товар).
  4. Информация о сделке (заказе) должна храниться в элементе Документ с атрибутом ХозОперация равным «Заказ товара»
  5. Элементы Документ и Контрагент должны содержать атрибут Ид, в котором содержится GUID соответствующей сделки или контрагента
  6. Сделка может содержать не более одного контрагента
  7. Игнорируется элемент ЗначенияРеквизитов

На число одновременно переданных сделок и товаров ограничение не накладывается.

При создании сделки и контрагента проверяется, нет ли таких 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/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».