Сделки

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

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 позиции сделки

Name

string

Наименование позиции

Count

integer

Количество

DeclaredPrice

float

Заявленная цена

DiscountType

integer

Тип скидки: 1 - скидка задается в процентах, 2 - в абсолютной величине

DiscountValue

float

Размер скидки

Cost

float

Финальная цена

Поля доступные для фильтрации (параметр FilterFields)

Список схем сделок

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 сотрудника. Для того, чтобы указать контакта, необходимо установить значение 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».