Сделки (deal)

Метод “deal”

Метод позволяет управлять записями Сделок – добавлять, обновлять, удалять.

URL для вызова - http(s)://crm_url/developer/v2/deal?параметр=значение

Запрос “fields”

Запрос позволяет получить список доступных полей, хранящих информацию о сделке в формате – «Имя поля» - «Расшифровка назначения» для формирования дальнейших запросов.

В список включены поля, активированные в Панели управления / Формы сделок. Не активные поля игнорируются при обработке.

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "fields"
]

$urlparams = http_build_query($params);

Ответ:


{
    "data":{
        "did":"Уникальный идентификатор записи в CRM",
        "uid":"Уникальный идентификатор записи в вашей ИС",
        "datum":"Дата создания. YYYY-MM-DD",
        "datum_izm":"Дата последнего изменения. YYYY-MM-DD",
        "mcid":"ID своей компании",
        "iduser":"Ответственный",
        "datum_plan":"Дата план.",
        "step":"Этап",
        "dog_num":"Договор",
        "tip":"Тип сделки",
        "direction":"Направление",
        "adres":"Адрес",
        "content":"Описание",
        "payer":"Плательщик",
        "des":"Примечание",
        "kol":"Сумма план.",
        "marg":"Прибыль",
        "datum_start":"Период действия. Начало",
        "datum_end":"Период действия. Конец",
        "datum_close":"Дата закрытия. YYYY-MM-DD",
        "status_close":"Результат закрытия сделки",
        "kol_fact":"Фактическая сумма продажи"
    }
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод

Запрос “steplist”

Запрос позволяет получить список этапов в формате – «Этап» - «Расшифровка назначения» для формирования дальнейших запросов.

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "steplist"
]

$urlparams = http_build_query($params);

Ответ:

Ответ содержит массив этапов с расшифровкой значений


{
    "data":[
        {"idcategory":"10","title":"0","content":"Проявлен\/Выявлен интерес"},
        {"idcategory":"2","title":"20","content":"Подтвержден интерес"},
        {"idcategory":"11","title":"40","content":"Отправлено КП"},
        {"idcategory":"5","title":"60","content":"Обсуждение деталей - продукты, услуги, оплата"},
        {"idcategory":"6","title":"80","content":"Согласован договор, Выставлен счет"},
        {"idcategory":"7","title":"90","content":"Получена предоплата, Выполнение договора"},
        {"idcategory":"8","title":"100","content":"Закрытие сделки, Подписание документов"}
    ]
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод

Запрос “direction”

Запрос позволяет получить список Направлений в формате – «Направление» - «Расшифровка назначения» для формирования дальнейших запросов.

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "direction"
]

$urlparams = http_build_query($params);

Ответ:

Ответ содержит массив Направлений с расшифровкой значений. Параметр "isDefault = yes" указывает на то, что это направление устанавливается по-умолчанию, если другое не указано


{
    "data":[
        {"id":"1","title":"Консалтинг","isDefault":""},
        {"id":"2","title":"Оборудование","isDefault":"yes"},
        {"id":"3","title":"Проектные работы","isDefault":""}
    ]
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод

Запрос “type”

Запрос позволяет получить список типов сделок для формирования дальнейших запросов.

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "type"
]

$urlparams = http_build_query($params);

Ответ:

Ответ содержит массив типов сделок


{
    "data":[
        {"tid":"7","title":"Ежемесячный","isDefault":""},
        {"tid":"65","title":"Продажа быстрая","isDefault":"yes"},
        {"tid":"1","title":"Продажа простая","isDefault":""},
        {"tid":"2","title":"Продажа с разработкой","isDefault":""},
        {"tid":"4","title":"Продажа услуг","isDefault":""},
        {"tid":"38","title":"Сервисная","isDefault":""},
        {"tid":"6","title":"Тендер","isDefault":""},
        {"tid":"3","title":"Услуги","isDefault":""}
    ]
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод

Запрос “statusclose”

Запрос позволяет получить список статусов закрытых сделок.

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "statusclose"
]

$urlparams = http_build_query($params);

Ответ:

Ответ содержит массив статусов закрытия сделки, которые используются в запросе close


{
    "data":[
        {"sid":"6","title":"Отказ от участия"},
        {"sid":"5","title":"Отменена Заказчиком"},
        {"sid":"1","title":"Победа полная"},
        {"sid":"2","title":"Победа, договорились с конкурентами"},
        {"sid":"3","title":"Проигрыш по цене"},
        {"sid":"4","title":"Проигрыш, договорились с конкурентами"}
    ]
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод

Запрос “funnel”

Запрос позволяет получить подробную информацию о воронках.

Параметры запроса:

  • did – уникальный идентификатор записи Сделки для вывода воронки для конкретной сделки
  • direction – название или id Направления
  • type – название или id Типа сделки

Возможные сочетания параметров:

  1. did > 0 - выводит воронку для конкретной сделки
  2. did = NULL, direction > 0, type = NULL - выводит все воронки для указанного Направления
  3. did = NULL, direction = NULL, type > 0 - выводит все воронки для указанного Типа сделки
  4. did = NULL, direction > 0, type > 0 - выводит данные воронки для указанного сочетания Направление + Типа сделки

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


$params = [
    "login" => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "funnel"
]

$urlparams = http_build_query($params);

Ответ:

Ответ содержит массив воронок, в зависимости от запроса


{
    "data":{
        //этапы воронки: id этапа => продолжительность (дн.)
        "steps"{"10":"2","2":"2","11":"2","5":"2","6":"2","7":"2","8":"2"},
        //этап воронки по-умолчанию
        "default":"10",
        //полная продолжительность воронки
        "length":14,
        //название воронки
        "funnel":"Оборудование\/Продажа с разработкой",
        //текущий этап
        "current":{"id":"5","title":"60","content":"Обсуждение деталей - продукты, услуги, оплата"},
        //следующий этап
        "next":{"id":6,"title":"80","content":"Согласован договор, Выставлен счет"},
        //предыдущий этап
        "prev":{"id":11,"title":"40","content":"Отправлено КП"}
    }
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод

Запрос “list”

Запрос позволяет получить список сделок, доступных текущему сотруднику, в т.ч. с применением фильтров.

Параметры запроса (не обязательные):

  • offset – страница вывода, с учетом того, что установлен лимит в 200 записей на страницу (по умолчанию offset = 0)
  • order – поле, по которому будет производится сортировка списка (по умолчанию order = datum)
  • first – направление сортировки (new – сначала новые, old – сначала старые). (по умолчанию first = new)

Фильтры (не обязательные):

  • uid – ограничение по uid сделки (идентификатор из внешней системы)
  • user – ограничение по пользователю (указывается логин пользователя)
  • dateStart – начальная дата создания записи (формат - YYYY-MM-DD)
  • dateEnd – конечная дата создания записи (не обязательно, формат - YYYY-MM-DD)
    • только dateStart – вывод записей с датой создания больше указанной даты
    • только dateEnd – вывод записей с датой создания меньше указанной даты
  • word – слово поиска по полям title, des, adres
  • steps – фильтр по этапам с перечислением названий этапов через запятую (Например – 10,20,40)
  • active - yes - активная сделка (по умолчанию) или no - закрытая
  • fields – указание списка полей, выводимых запросом
  • invoice - если равен "no", то ответ не будет содержать счетов (yes - по умолчанию)
  • bankinfo - для включения банковских реквизитов
  • filter - массив, содержащий дополнительные фильтры:
    • clid - идентификатор клиента-заказчика
    • payer - идентификатор клиента-плательщика
    • direction - направление деятельности в текстовом виде (напроимер, основное)
    • tip - тип сделки в текстовом виде
    • input1...input10 - доп.поле

Пример формирования запроса в PHP:


$params = [
    "login" => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"    => 'list',
    // страница, с учетом вывода 200 записей на страницу
    "offset"    => 0,
    // поле для упорядочивания записей
    "order"     => 'date_create',
    // направление сортировки; new - по-умолчанию, old - сначала более старые
    "first"     => '',
    // ограничение по login пользователя, пользователь должен быть в подчинении у текущего
    "user"      => '',
    // даты создания
    "dateStart" => '2014-01-01',
    "dateEnd"   => '2018-06-01',
    // строка поиска по полям title, des, phone, mail_url, site_url
    "word"      => '',
    // string, фильтр по UID сделки
    "uid"       => '',
    // string, фильтр по этапам с перечислением названий этапов через запятую (Например – 10,20,40)
    "steps"     => '10,20,40',
    // string, фильтр по активности. yes - активная сделка (по умолчанию) или no - закрытая
    "active" => 'yes',
    // string, вывод счетов. если равен "no", то ответ не будет содержать счетов (yes - по умолчанию)
    "invoice"   => '',
    // для вывода только заданных полей из конкретной записи == list, info
    //"fields"    => 'did,title,clid,kol,marga',
    // для включения банковских реквизитов
    //"bankinfo"  => 'yes',
    // фильтры (см. запрос "fields")
    "filter"    => [
        // string, фильтр по идентификатору клиента-заказчика
        "clid"      => '',
        // string, фильтр по идентификатору клиента-плательщика
        "payer"     => '',
        // string, фильтр по направлению деятельности в текстовом виде или по ID (напроимер, основное)
        "direction" => '',
        // string, фильтр по типу сделки в текстовом виде
        "tip"       => '',
        // string, фильтр по доп.полю
        "input1"    => ''
    ]
];

$urlparams = http_build_query($params);

Ответ:

В поле “data” приходит список записей, в поле "count" - приходит общее количество записей в выборке

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод

Запрос “info”

Запрос позволяет получить информацию о сделке по её идентификатору - did.

Параметры запроса:

  • did – уникальный идентификатор записи или uid – идентификатор из внешней системы
  • fields – ограничение вывода информации по полям с разделением запятыми без пробелов
  • invoice - если равен "yes", то ответ будет содержать счетов (yes - по умолчанию, no)
  • speka - если равен "yes", то ответ будет содержать спецификации (yes - по умолчанию, no)
  • client - если равен "yes", то ответ будет содержать информацию о Заказчике (yes - по умолчанию, no)
  • payer - если равен "yes", то ответ будет содержать информацию о Плательщике (yes - по умолчанию, no)
  • person - если равен "yes", то ответ будет содержать информацию о связанных Контактах (yes - по умолчанию, no)

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


$params = [
    "login" => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"    => 'info',
    "did"       => 902,
    // string, вывод счетов. если равен "no", то ответ не будет содержать счетов (yes, по - умолчанию)
    "invoice"     => 'yes',
    // string, вывод спецификации. если равен "no", то ответ не будет содержать счетов (yes, по - умолчанию)
    "speka"     => 'yes',
    // string, если равен "yes", то ответ будет содержать информацию о Заказчике (yes, no - по умолчанию)
    "client"     => 'yes',
    // string, если равен "yes", то ответ будет содержать информацию о Плательщике (yes, no - по умолчанию)
    "payer"     => 'yes',
];

$urlparams = http_build_query($params);

Ответ:


{
    "data":{
        "did":"902",
        "uid":"",
        "datum":"2017-08-09",
        "datum_izm":"2017-12-19",
        "clid":"1781",
        "clientTitle":"Сейлзмен Рус",
        "title":"СД4250: Сейлзмен Рус",
        "mcid":"2",
        "iduser":"1",
        "user":"vladislav@isaler.ru",
        "userUID":"DIR100",
        "datum_plan":"2018-06-30",
        "step":"100",
        "stepID":"8",
        "stepTitle":"Закрытие сделки, Подписание документов",
        "contractID":"212",
        "contractTitle":"Договор",
        "contractNumber":"39-1015\/2015",
        "contractDate":"2015-10-19",
        "tipID":"1",
        "tip":"Продажа простая",
        "directionID":"2",
        "direction":"Оборудование",
        "adres":"",
        "content":"",
        "payer":{
            "clid":"1781",
            "title":"Сейлзмен Рус",
            "des":"",
            "idcategory":"38",
            "category":"Информационные технологии",
            "phone":"7 (342) 254-55-77, 8 (912) 884-45-55",
            "fax":"",
            "site_url":"www.salesman.su",
            "mail_url":"info@salesman.su",
            "address":"Россия, Пермь, улица Максима Горького, 83",
            "iduser":"1",
            "pid":"2475",
            "fav":"yes",
            "trash":"no",
            "head_clid":"0",
            "head":null,
            "scheme":"Решение принимает совет учредителей",
            "tip_cmr":"2 - Потенциальный клиент",
            "territory":"1",
            "territoryname":"Пермь",
            "creator":"Андреев Владислав",
            "editor":"Андреев Владислав",
            "date_create":"30.01.15, 00:39",
            "date_edit":"10.07.18, 13:44",
            "recv":{
                "clid":"1781",
                "castUrName":"Сейлзмен Рус",
                "castName":"Сейлзмен Рус",
                "castInn":"5904338272",
                "castKpp":"590401001",
                "castBank":"СИБИРСКИЙ ФИЛИАЛ АО КБ \"МОДУЛЬБАНК\", НОВОСИБИРСК",
                "castBankKs":"30101810350040000864",
                "castBankRs":"40702810621810000563",
                "castBankBik":"045004864",
                "castOkpo":"",
                "castOgrn":"1165958091530",
                "castDirName":"Андреева Владислава Германовича",
                "castDirSignature":"Андреев В.Г.",
                "castDirStatus":"Генерального директора",
                "castDirStatusSig":"Генеральный директор",
                "castDirOsnovanie":"Устава",
                "castUrAddr":"614007, г. Пермь, ул. Максима Горького, д. 83, оф.402",
                "castFacAddr":"Россия, Пермь, улица Максима Горького, 83",
                "castType":"client"
            },
            "clientpath":" Relap",
            "type":"client",
            "clientpath2":"176",
            "uid":"1001",
            "relation":"2 - Потенциальный клиент",
            "priceLevel":"price_2",
            "clientUID":"1001",
            "input1":"3 - постоянные закупки",
            "input3":"Свердловский",
            "input4":"Вариант 1, Вариант 5",
            "input2":"1999-05-20",
            "input5":"Вариант 2",
            "input6":"Вариант 2",
            "input7":"40-50",
            "input8":"Раз",
            "input9":""
        },
        "kol":"79045.00",
        "marga":"9300.00",
        "input1":"Россия, Пермь",
        "input2":"Значение 2",
        "input3":"2017-12-19",
        "input4":"Значение 5",
        "input5":"",
        "input6":"Свердловский",
        "input7":"2017-08-09 14:30",
        "input8":"",
        "datum_start":"0000-00-00",
        "datum_end":"0000-00-00",
        "close":"no",
        "datum_close":null,
        "status_close":false,
        "des_fact":null,
        "kol_fact":"0.00",
        "person":[
            {"pid":"2475","title":"Андреев Владислав Германович","post":"Коммерческий директор","phone":"7 (342) 206-72-02, 7 (342) 254-55-77","mob":"7 (922) 328-94-66, 7 (912) 884-41-39","email":"vladislav1andreev@ya.ru, yoolla.demo@mail.ru, boss@bigsales-crm.ru, vladislav1andreev@yandex.ru, vladislav1andreev@yandex.ru"}
        ],
        "speka":[
            {"prid":"2353","artikul":"7414","title":"BizFAX E100 факс-сервер, 1 FXO, 1 FXS, 1 RJ45","kol":"5","dop":"1","price":"15809.00","price_in":"13949.00","nds":"0.00","comments":""}
        ],
        // список выставленных счетов (см. также "Добавление счета")
        "invoice"[
            {
                //идентификатор записи счета (если номер не уникален или не указан)
                "id":"860",
                //номер счета
                "invoice":"125",
                //дата счета в формате ГГГГ-ММ-ДД
                "date":"2017-08-09",
                //сумма счета
                "summa":"49045.00",
                //НДС по счету
                "nds":"0.00",
                //признак оплаченного счета (оплачен = on)
                "do":"on",
                //дата оплаты в формате ГГГГ-ММ-ДД
                "date_do":"2017-10-06",
                //номер договора (если есть)
                "contract":"39-1015\/2015",
                //идентификатор расчетного счета в CRM
                "rs":"1",
                //тип счета (например, Счет-договор)
                "tip":"Счет-договор"
            },
            {
                "id":"866",
                "invoice":"125",
                "date":"2017-10-06",
                "summa":"30000.00",
                "nds":"0.00",
                "do":"on",
                "date_do":"2017-10-06",
                "contract":"",
                "rs":"1",
                "tip":"Счет-договор"
            }
        ]
    }
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Сделка с указанным did не найдена в пределах аккаунта указанного пользователя
404 – Не найдено
405 – Отсутствуют параметры - did сделки

Запрос “add”

Запрос позволяет добавить новую сделку в базу CRM. При этом ответственным устанавливается сотрудник, логин которого использовался в запросе или указанный отдельно в параметре user

Параметры запроса:

  • uid – уникальный идентификатор во внешней ИС
  • title – название сделки (обязательное поле)
  • clid –идентификатор клиента, к которому будет привязана сделка (обязательное поле)
  • payer - идентификатор клиента-плательщика
  • datum_plan – плановая дата закрытия сделки
  • mcid – идентификатор своей компании (можно получить в отдельном запросе). Если не указан, то будет указано id крайней использованной компании в сделках
  • user – login пользователя в SalesMan CRM назначаемого Ответственным за клиента
  • pid_list - список id контактов, через запятую
  • прочие поля fields – информация для добавления
  • speka - массив данных для добавления продуктов, для каждого добавляемого продукта содержит следующие данные:
    • artikul - артикул позиции прайса (уникальный идентификатор товара/услуги)
    • title - наименование позиции
    • kol - количество
    • dop - доп.поле, по умолчанию = 1
    • price - розничная цена (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
    • price_in - закупочная цена (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
    • edizm - единица измерения (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
    • nds - НДС, в %

Примечание

  • параметр datum_plan может быть указан в запросе. Если он отсутствует, то будет принято текущая дата + 2 недели
  • параметр payer может быть указан в запросе. Если он отсутствует, то будет принято payer = clid
  • параметр mcid может отсутствовать в запросе. Если не указано, то принимается значение по умолчанию из справочника
  • при пустом поле user Ответственным будет назначен текущий пользователь (из запроса)
  • следующие параметры передаются в явном, текстовом виде:
    • direction – направление деятельности. Если не указано, то принимается значение по умолчанию из справочника
    • tip – тип сделки. Если не указано, то принимается значение по умолчанию из справочника
    • step – числовое значение текущего этапа (например: 20)

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

Пример формирования запроса в PHP:


$params = [
    "login" => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'add',
    //название
    "title"      => 'Тестовая сделка',
    //UID
    "uid"        => 'dfgfdfg89ert',
    //заказчик
    "clid"       => 1781,
    //плательщик, если отличается от clid
    "payer"      => 1781,
    //направление
    "direction"  => 'Оборудование',
    //тип сделки
    "tip"        => 'Продажа услуг',
    //id компании
    "mcid"       => 2,
    //этап сделки. если пусто, то будет взято значение по-умолчанию
    "step"       => '20',
    //плановая дата
    "datum_plan" => '2018-08-01',
    //сумма сделки, если нет спецификации
    "kol"        => '100000.00',
    //маржа сделки, если нет спецификации
    "marga"      => '20000.00',
    "user"       => 'marand@omadaru.ru',
    "content"    => 'Давно выяснено, что при оценке дизайна и композиции читаемый текст мешает сосредоточиться. Lorem Ipsum используют потому, что тот обеспечивает более или менее стандартное заполнение шаблона, а также реальное распределение букв и пробелов в абзацах, которое не получается при простой дубликации "Здесь ваш текст.. Здесь ваш текст.. Здесь ваш текст.."',
    //позиции спецификации
    "speka"      => [
        [
            "artikul"  => "7414",
            "title"    => "BizFAX E100 факс-сервер, 1 FXO, 1 FXS, 1 RJ45",
            "kol"      => "5",
            //доп.множитель, если не используется = 1
            "dop"      => "1",
            //не обязательно, если корректно указан artikul или title
            "price"    => "18831,15",
            //не обязательно, если корректно указан artikul или title
            "price_in" => "13 949,00",
            //не обязательно, если корректно указан artikul или title
            "edizm"    => "шт.",
            //НДС в % если есть
            "nds"      => "18"
        ],
        [
            "artikul"  => "7722",
            "title"    => "SIP-T12P SIP-телефон, 2 линии, PoE",
            "kol"      => "10",
            "dop"      => "1",
            "price"    => "3821,85",
            "price_in" => "2 831,00",
            "edizm"    => "шт.",
            "nds"      => "18"
        ]
    ]
];

$urlparams = http_build_query($params);

Ответ:

В поле “data” приходит id записи


{
    "result":"Успешно",
    "data":921,
    "text":["Добавлены позиции в спецификацию. Ошибок 0"]
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
405 – Отсутствуют параметры - clid и payer клиента
406 – Отсутствуют параметры - Название сделки
407 - Клиент или Плательщик не найден

Запрос “update”

Запрос позволяет обновить данные сделки по её did или uid. При этом нет необходимости передавать все данные – можно передать только изменившиеся данные.

Параметры запроса:

  • did – уникальный идентификатор клиента (обязательное поле) или uid – уникальный идентификатор во внешней ИС
  • fields - прочие поля, информация для обновления
  • pid_list - список id контактов, через запятую
  • speka - массив данных для добавления продуктов, для каждого добавляемого продукта содержит следующие данные:
    • artikul - артикул позиции прайса (уникальный идентификатор товара/услуги)
    • title - наименование позиции
    • kol - количество
    • dop - доп.поле, по умолчанию = 1
    • price - розничная цена (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
    • price_in - закупочная цена (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
    • edizm - единица измерения (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
    • nds - НДС, в %

Важно

  • Если в запросе есть массив speka (есть спецификация), то предыдущая спецификация будет удалена и добавлена новая
  • При наличии спецификации сумма сделки (бюджет) и маржа будут рассчитаны на основе спецификации
  • Запрос не применим для изменения статуса сделки (смена этапа, закрытие) - для этого используйте отдельные запросы change.step, change.close

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



$params = [
    "login" => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'update',
    "did"        => '921',
    "uid"        => 'FGR34556900',
    //название
    "title"      => 'Тестовая сделка',
    //заказчик
    //"clid"       => 1781,
    //плательщик, если отличается от clid
    //"payer"      => 1781,
    //направление
    //"direction"  => 'Оборудование',
    //тип сделки
    //"tip"        => 'Продажа услуг',
    //id компании
    //"mcid"       => 2,
    //плановая дата
    "datum_plan" => '2018-08-11',
    //сумма сделки, если нет спецификации
    "kol"        => '100000.00',
    //маржа сделки, если нет спецификации
    "marga"      => '20000.00',
    "pid_list"   => '2475,2513',
    "content"    => 'Давно выяснено, что при оценке дизайна и композиции читаемый текст мешает сосредоточиться. Lorem Ipsum используют потому, что тот обеспечивает более или менее стандартное заполнение шаблона, а также реальное распределение букв и пробелов в абзацах, которое не получается при простой дубликации "Здесь ваш текст.. Здесь ваш текст.. Здесь ваш текст.."',
    //позиции спецификации, если надо заменить
    "speka"      => [
        [
            "artikul"  => "7414",
            "title"    => "BizFAX E100 факс-сервер, 1 FXO, 1 FXS, 1 RJ45",
            "kol"      => "5",
            //доп.множитель, если не используется = 1
            "dop"      => "1",
            //не обязательно, если корректно указан artikul или title
            "price"    => "19831,15",
            //не обязательно, если корректно указан artikul или title
            "price_in" => "13949,00",
            //не обязательно, если корректно указан artikul или title
            "edizm"    => "шт.",
            //НДС в % если есть
            "nds"      => "18"
        ],
        [
            "artikul"  => "7722",
            "title"    => "SIP-T12P SIP-телефон, 2 линии, PoE",
            "kol"      => "5",
            "dop"      => "1",
            "price"    => "4821,85",
            "price_in" => "2831,00",
            "edizm"    => "шт.",
            "nds"      => "18"
        ]
    ]
];

$urlparams = http_build_query($params);

Ответ:

В поле “data” приходит id записи

{"result":"Успешно","data":764}

Если данные совпадают с имеющимися в базе запрос не будет обработан, но ошибки не вернет:

{"result":"Данные корректны, но идентичны имеющимся","data":764}

Результат обработки спецификации будет добавлен к предыдущему ответу.

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Сделка с указанным did не найдена в пределах аккаунта указанного пользователя
405 – Отсутствуют параметры - did сделки

Запрос “change.step”

Запрос позволяет изменить этап сделки по её did с указанием комментария изменения.

Параметры запроса:

  • did – уникальный идентификатор клиента (обязательное поле) или uid – уникальный идентификатор во внешней ИС
  • step – числовое значение нового этапа (обязательное поле)
  • description – комментарий к изменению этапа

Дополнительно:

  • Если в системе активирован модуль «Контрольные точки» и текущий этап связан с какой-либо контрольной точкой, то она будет отмечена выполненной. Ответ о выполнении вернется в поле “message”. Также сообщение будет записано в Историю активности.

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



$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"      => 'change.step',
    "did"         => 921,
    "step"        => '40',
    "description" => 'Согласовали спецификацию. Готовим договор.'
];

$urlparams = http_build_query($params);

Ответ:

  • В поле “data” приходит id записи
  • В поле “message” приходит дополнительное сообщение

{"result":"Этап сделки изменен на 40%. Предыдущий этап 20%","data":921}

Если данные совпадают с имеющимися в базе запрос не будет обработан, но ошибки не вернет:

{"result":"Данные корректны, но идентичны имеющимся","data":764}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Сделка с указанным did не найдена в пределах аккаунта указанного пользователя
405 – Отсутствуют параметры - Новый этап
406 – Отсутствуют параметры - did сделки

Запрос “change.close”

Запрос позволяет закрыть сделку по её did или uid.

Параметры запроса:

  • did – уникальный идентификатор сделки (обязательное поле) или uid – уникальный идентификатор во внешней ИС
  • status_close – статус закрытия сделки (обязательное поле)
  • kol_fact – сумма сделки при закрытии (если не указано, то = сумме по сделке)
  • marga – маржа сделки при закрытии (если не указано, то = марже по сделке)
  • des_fact – комментарий при закрытии

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



$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"      => 'change.close',
    "did"         => 921,
    "step"        => '40',
    "description" => 'Комментарий'
];

$urlparams = http_build_query($params);

Ответ:

В поле “data” приходит id записи

{"result":"Успешно","data":921}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Сделка с указанным did не найдена в пределах аккаунта указанного пользователя
405 – Отсутствуют или не корректны параметры - Статус закрытия сделки
406 – Отсутствуют параметры - did сделки
407 – Сделка уже закрыта

Запрос “change.user”

Запрос позволяет передать сделку по её did или uid.

Параметры запроса:

  • did – уникальный идентификатор сделки (обязательное поле) или uid – уникальный идентификатор во внешней ИС
  • user – логин нового Ответственного
  • client.send – если равен "yes", то будет передан Клиент (yes - по умолчанию, no)
  • person.send – если равен "yes", то будут переданы Контакты (yes - по умолчанию, no)

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



$params12 = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"       => 'change.user',
    "did"          => 912,
    "user"         => 'marand@omadaru.ru',
    "client.send"  => 'yes',
    "person.send"  => 'yes'
];

$urlparams = http_build_query($params);

Ответ:

В поле “data” приходит id записи

{"result":"Успешно","data":912}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Сделка с указанным did не найдена в пределах аккаунта указанного пользователя
406 – Отсутствуют параметры - did сделки

Запрос “delete”

Запрос позволяет удалить сделку по её did. Метод работает только в случае, если у сделки нет выставленных счетов.

Параметры запроса:

  • did – уникальный идентификатор сделки (обязательное поле) или uid – уникальный идентификатор во внешней ИС

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



$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"       => 'delete',
    "did"          => 912
];

$urlparams = http_build_query($params);

Ответ:

В поле “data” приходит id записи

{"result":"Успешно","data":912}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Сделка с указанным did не найдена в пределах аккаунта указанного пользователя
406 – Отсутствуют параметры - did сделки
407 – Удаление сделки не возможно - есть Оплаченные/Неоплаченые счета

Запрос “invoice.add”

Запрос позволяет добавить к сделке новый счет

Параметры запроса:

  • uid – уникальный идентификатор сделки во внешней системе
  • did – уникальный идентификатор сделки в CRM
  • user – логин Ответственного
  • date – дата счета
  • date.plan – ожидаемая дата оплаты счета
  • summa – сумма счета, если не указана - берем сумму Сделки
  • invoice - номер счета, если пусто, то будем генерировать очередной из системы
  • contract - номер договора, если пусто, то смотрим Договор, прикрепленный к сделке
  • rs - идентификатор расчетного счета (список можно получить из справочника) - если пусто, то берем р/с компании, от которой ведется сделка с признаком "по-умолчанию"
  • nds - размер НДС в абсолютных цифрах (не обязательно при наличии спецификации)
  • tip - тип счета - Предварительная оплата, Окончательная оплата, По спецификации, По договору, Счет-договор

Если нужно зафиксировать уже оплаченный счет, то включаем следующие параметры:

  • do - признак оплаченного счета = yes
  • date.do - дата оплаты, если пусто - текущая дата

Важно

  • Допускается указание либо did, либо uid сделки
  • Перед выставлением счета (если счет не к договору и не является предоплатным/постоплатным) необходимо добавить спецификацию - позиции с помощью запроса update
  • в случае do = yes счет просто отмечается оплаченным без каких-либо манипуляций с суммами на счете

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



$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"       => 'invoice.add',
    "did"          => 921,
    "uid"          => '',
    //Ответственный, которому надо назначить счет
    "user"         => 'marand@omadaru.ru',
    //номер счета, если "auto", то будем генерировать очередной из системы
    "invoice" => 'auto',
    //дата счета, если пусто - текущая дата
    "date"    => '',
    //ожидаемая дата оплаты счета, если не указано, то устанавливается как +5 дней от текущей даты
    "date.plan"    => '',
    //сумма счета, если не указано, то берем сумму из сделки или спецификации (если есть)
    "summa" => '',
    //номер договора, если пусто, то смотрим Договор, прикрепленный к сделке
    "contract" => '',
    //идентификатор расчетного счета (список можно получить из справочника) - если пусто, то берем первый по списку с признаком "по-умолчанию" для компании, от которой ведется сделка
    "rs" => '',
    //размер НДС в абсолютных цифрах, если пусто, то будет расчитан автоматически
    "nds" => '',
    //тип счета - Предварительная оплата, Окончательная оплата, По спецификации, По договору, Счет-договор
    "tip" => 'Счет-договор',
    //признак оплаченного счета - yes
    //"do" => '',
    //дата оплаты
    //"date.do" => '',
];

$urlparams = http_build_query($params);

Ответ:

В поле “result“ приходит ответ обработчика, в поле “data” приходит:

  • id - идентификатор записи счета в CRM
  • invoice - номер счета

{
    "result":"Успешно;Счет добавлен в платежи",
    "data":{"id":913,"invoice":"168"}
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Сделка с указанным did не найдена в пределах аккаунта указанного пользователя
406 – Уже выставлены все возможные счета

Запрос “invoice.do”

Запрос позволяет отметить выставленный счет оплаченным (с внесением суммы на указанный расчетный счет модуля Бюжет)

Параметры запроса:

  • did - идентификатор сделки
  • invoice - номер счета
  • id - идентификатор записи счета (если номер не уникален или не указан)
  • date.do - дата оплаты, если пусто - текущая дата
  • summa - сумма оплаты, если пусто, то принимается полная сумма счета; может быть меньше суммы счета - в таком случае будет создан счет на недостающую сумму

Наличие параметра "invoice" ИЛИ "id" обязательно для поиска счета в базе. Получить список счетов с "id" и "invoice" можно с помощью метода info

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



$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"       => 'invoice.do',
    "did"          => 921,
    //id счета
    "id"           => 913,
    //номер счета, не обязательно если указан id счета
    "invoice"      => '168',
    //дата оплаты, если пусто, то принимается текущая дата
    "date.do" => '',
    //сумма оплаты, если пусто, то принимается полная сумма счета
    "summa"   => '',
];

$urlparams = http_build_query($params);

Ответ:

В поле “result“ приходит ответ обработчика, в поле “data” приходит расширенный отчет обработки.

Примечание

  • Если внесена частичная оплата, то в ответе будет присутствовать параметр newdata - id дополнительного счета (с тем же номером)

{
    "result":"Успешно;Счет добавлен в платежи",
    "data":{"id":913,"invoice":"168"}
}

{
    "result":"Успешно",
    "data":"Внесена оплата по графику 100 000,00 р. Поступившая оплата отличается от планируемой. Добавлен дополнительный платеж 22 347,75 р. На р\/с Модульбанк внесена оплата в размере 100 000,00 р.",
    "newdata":917
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Счет по ID или Номеру не найден

Запрос “invoice.express” Новое

Является запросом, аналогичным invoice.add. Позволяет внести оплату. В случае неполной оплаты будет создана дополнительная запись в графике платежей на недостающую сумму.

Параметры запроса:

  • uid – уникальный идентификатор сделки во внешней системе
  • did – уникальный идентификатор сделки в CRM
  • user – логин Ответственного
  • date – дата счета
  • date.plan – ожидаемая дата оплаты счета
  • summa – сумма счета, если не указана - берем сумму Сделки
  • invoice - номер счета, если пусто, то будем генерировать очередной из системы
  • contract - номер договора, если пусто, то смотрим Договор, прикрепленный к сделке
  • rs - идентификатор расчетного счета (список можно получить из справочника) - если пусто, то берем р/с компании, от которой ведется сделка с признаком "по-умолчанию"
  • nds - размер НДС в абсолютных цифрах (не обязательно при наличии спецификации)
  • tip - тип счета - Предварительная оплата, Окончательная оплата, По спецификации, По договору, Счет-договор


$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"       => 'addinvoice',
    "did"          => 921,
    "uid"          => '',
    //Ответственный, которому надо назначить счет
    "user"         => 'marand@omadaru.ru',
    //номер счета, если "auto", то будем генерировать очередной из системы
    "invoice" => 'auto',
    //дата счета, если пусто - текущая дата
    "date"    => '',
    //ожидаемая дата оплаты счета, если не указано, то устанавливается как +5 дней от текущей даты
    "date.plan"    => '',
    //сумма счета, если не указано, то берем сумму из сделки или спецификации (если есть)
    "summa" => '',
    //номер договора, если пусто, то смотрим Договор, прикрепленный к сделке
    "contract" => '',
    //идентификатор расчетного счета (список можно получить из справочника) - если пусто, то берем первый по списку с признаком "по-умолчанию" для компании, от которой ведется сделка
    "rs" => '',
    //размер НДС в абсолютных цифрах, если пусто, то будет расчитан автоматически
    "nds" => '',
    //тип счета - Предварительная оплата, Окончательная оплата, По спецификации, По договору, Счет-договор
    "tip" => 'Счет-договор',
    //дата оплаты
    //"date.do" => '',
];

$urlparams = http_build_query($params);

Ответ:

В поле “result“ приходит ответ обработчика, в поле “data” приходит расширенный отчет обработки


{
    "result":"Успешно;Внесена оплата 122 347,75 р. На р\/с Модульбанк внесена оплата в размере 122347.75 р. Счет добавлен в платежи",
    "data":{"id":925,"invoice":"175"}
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Счет по номеру не найден
406 – Уже выставлены все возможные счета

Запрос “invoice.mail” Новое

Позволяет отправить существующий счет в виде PDF контактам по сделке

Параметры запроса:

  • id – уникальный идентификатор счета
  • invoice - номер счета
  • user – логин Ответственного
  • theme - тема сообщения, если не указано, то будет установлено "Счет на оплату"
  • content - тело сообщения, если не указано, то будет использован шаблон по-умолчанию

Примечание

  • Сначала будет произведен поиск Контактов, прикрепленным к Сделке
  • Если Контакты в сделке не найдены, то будет произведен поиск Основного контакта Клиента
  • Если Контакты не найдены, то отправка будет произведена на Email, указанный в карточке Плательщика по сделке

Шаблон сообщения:



Приветствую, {{person}}

Отправляю Вам Счет на оплату.

Спасибо за внимание.
С уважением,
{{mName}}
Тел.: {{mPhone}}
Email.: {{mMail}}
==============================
{{mCompany}}

Применимые тэги:

  • {{person}} - заменяет ИМЯ контакта
  • {{mName}} - Имя сотрудника
  • {{mPhone}} - Телефон сотрудника
  • {{mMail}} - Email сотрудника
  • {{mCompany}} - Название компании (короткое) из справочника "Мои компании", за которой закреплен р/сч. по счету

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



$params = [
    "login"   => "vladislav@isaler.ru",
    "apikey"  => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"  => 'invoice.mail',
    //id счета
    //"id"    => 898,
    //номер счета
    "invoice" => "158",
    //тема сообщения
    "theme"   => "Счет на оплату",
    //содержание сообщения
    "content" => ""
];

$urlparams = http_build_query($params);

Ответ:

В поле “result“ приходит ответ обработчика, в поле “data” приходит расширенный отчет обработки


{
    "result":"Успешно",
    "data":{"id":902,"invoice":"158"}
}

В случае ошибки:


{
    "result":"Error",
    "error":{"code":"407","text":"Не указан ни один получатель"},
    "data":902,"invoice":"158",
    "text":"Выполнено с ошибками. Ошибка: Пожалуйста, введите хотя бы один адрес e-mail получателя."
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Счет по номеру не найден
407 – Не указан ни один получатель

Запрос “invoice.html” Новое

Запрос позволяет получить содержимое счета в виде HTML

Параметры запроса:

  • invoice - номер счета
  • id - идентификатор записи счета (если номер не уникален или не указан)
  • nosignat - если равен "yes", то в ответе не будет изображения печати

Наличие параметра "invoice" ИЛИ "id" обязательно для поиска счета в базе. Получить список счетов с "id" и "invoice" можно с помощью метода info

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



$params = [
    "login"      => "vladislav@isaler.ru",
    "apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'invoice.html',
    //id счета
    "id"         => 925,
    //исключение печати из вывода
    //"nosignat" => "yes",
    //номер счета
    "invoice"    => "158",
];

$urlparams = http_build_query($params);

Ответ:

  • в поле “html“ приходит ответ HTML,
  • в поле “id” приходит id счета,
  • в поле "invoice" приходит номер счета

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Счет по ID или Номеру не найден

Запрос “invoice.pdf” Новое

Запрос позволяет получить ссылку на счет в виде PDF

Параметры запроса:

  • invoice - номер счета
  • id - идентификатор записи счета (если номер не уникален или не указан)
  • nosignat - если равен "yes", то в ответе не будет изображения печати

Наличие параметра "invoice" ИЛИ "id" обязательно для поиска счета в базе. Получить список счетов с "id" и "invoice" можно с помощью метода info

Примечание

  • если файл не существует, то он будет сгенерирован (требуется больше времени на обработку). Поэтому в cURL запросе следует установить повышенное время ожидания ответа (подбирается опытным путем, но >=20)

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



$params = [
    "login"      => "vladislav@isaler.ru",
    "apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'invoice.html',
    //id счета
    "id"         => 925,
    //исключение печати из вывода
    //"nosignat" => "yes",
    //номер счета
    "invoice"    => "158",
];

$urlparams = http_build_query($params);

Ответ:

  • в поле “url“ приходит URL pdf-файла (слэши экранированы),
  • в поле “id” приходит id счета,
  • в поле "invoice" приходит номер счета

{
    "url":"http://sm2018.crm/files/invoice_925.pdf",
    "id":925,
    "invoice":175
}

Возможные ответы в случае ошибок:

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
403 – Счет по ID или Номеру не найден