Сделки (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 Типа сделки
Возможные сочетания параметров:
- did > 0 - выводит воронку для конкретной сделки
- did = NULL, direction > 0, type = NULL - выводит все воронки для указанного Направления
- did = NULL, direction = NULL, type > 0 - выводит все воронки для указанного Типа сделки
- 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 - для включения банковских реквизитов
- uids – вывод связанных идентификаторов внешних систем (yes / no – по умолчанию) [ см. Заявки ]
- 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)
- uids – вывод связанных идентификаторов внешних систем (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 - идентификатор клиента-плательщика
- author - идентификатор автора сделки
- datum_plan – плановая дата закрытия сделки
- mcid – идентификатор своей компании (можно получить в отдельном запросе). Если не указан, то будет указано id крайней использованной компании в сделках
- user – login пользователя в SalesMan CRM назначаемого Ответственным за клиента
- pid_list - список id контактов, через запятую
- step - числовое значение этапа (10, 20..) ИЛИ category –идентификатор этапа
- direction - направление (не обязательно)
- tip - тип сделки (не обязательно)
- прочие поля fields – информация для добавления
- speka - массив данных для добавления продуктов, для каждого добавляемого продукта содержит следующие данные:
- spid - id позиции спецификации
- tip - тип позиции (0 - товар, 1 - услуга, 2 - материал)
- artikul - артикул позиции прайса (уникальный идентификатор товара/услуги)
- title - наименование позиции
- kol - количество
- dop - доп.поле, по умолчанию = 1
- price - розничная цена (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
- price_in - закупочная цена (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
- edizm - единица измерения (не обязателный параметр, при совпадении актикула или названия с позицией в прайсе берется из прайса)
- nds - НДС, в %
Примечание
- параметр datum_plan может быть указан в запросе. Если он отсутствует, то будет принято текущая дата + 2 недели
- параметр payer может быть указан в запросе. Если он отсутствует, то будет принято payer = clid
- параметр mcid может отсутствовать в запросе. Если не указано, то принимается значение по умолчанию из справочника
- при пустом поле user Ответственным будет назначен текущий пользователь (из запроса)
- следующие параметры передаются в явном, текстовом виде:
- direction – направление деятельности. Если не указано, то принимается значение по умолчанию из справочника
- tip – тип сделки. Если не указано, то принимается значение по умолчанию из справочника
- step – числовое значение текущего этапа (например: 20), можно передавать category - id этапа
В случае отсутствия переданных значений в справочниках не будут созданы новые записи
Пример формирования запроса в 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",
//тип позиции
"tip" => "0",
"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",
//тип позиции
"tip" => "0",
"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.info” Новое
Запрос позволяет получить информацию по Счету по его идентификатору - id.
Параметры запроса:
- id – уникальный идентификатор записи
Пример запроса:
$params = [
"login" => "vladislav@isaler.ru",
"apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
// указываем метод
"action" => 'info',
"id" => 959
]
$urlparams = http_build_query($params);
Ответ:
Ответ содержит следующие специфичные данные:
- crid - Идентификатор Счета
- invoice - Номер Счета
- datum - Дата Счета
- datum_credit - Плановая дата оплаты Счета
- invoice_date - Фактическая дата оплаты Счета
- contractnum - Номер договора
- summa - Сумма Счета
- nds - Сумма Налога
- clid - ID клиента
- did - ID сделки
- tip - Тип Счета
- rs - ID расчетного счета
- iduser - ID ответственного по счету
- do - Статус оплаты ("on" = оплачено)
- suffix -
- template - шаблон Счета
- id - ID шаблона
- title - название шаблона
- file - файл шаблона
- typeid - ID типа документа
{
"data":{
"crid":"958",
"invoice":"207",
"datum":"2019-03-19 14:53:00",
"datum_credit":"2019-03-24",
"invoice_date":"2019-03-19",
"contractnum":"",
"summa":"261390.00",
"nds":"0.00",
"clid":"1596",
"did":"736",
"tip":"Счет-договор",
"rs":"20",
"iduser":"1",
"do":"on",
"suffix":"",
"template":{
"id":"33",
"title":"Базовый шаблон",
"file":"invoice.tpl",
"typeid":"94"
}
}
}
Возможные ответы в случае ошибок:
400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
404 – Документ не найден
405 – Отсутствуют параметры - id Счета
Запрос “invoice.add”
Запрос позволяет добавить к сделке новый счет
Параметры запроса:
- uid – уникальный идентификатор сделки во внешней системе
- did – уникальный идентификатор сделки в CRM
- user – логин Ответственного
- date – дата счета
- date.plan – ожидаемая дата оплаты счета
- summa – сумма счета, если не указана - берем сумму Сделки
- invoice - номер счета, если пусто, то будем генерировать очередной из системы
- contract - номер договора, если пусто, то смотрим Договор, прикрепленный к сделке
- rs - идентификатор расчетного счета (список можно получить из справочника) - если пусто, то берем р/с компании, от которой ведется сделка с признаком "по-умолчанию"
- nds - размер НДС в абсолютных цифрах (не обязательно при наличии спецификации)
- tip - тип счета - Предварительная оплата, Окончательная оплата, По спецификации, По договору, Счет-договор
- template - файл шаблона (см. запрос "invoice.templates") или
- templateID - ID шаблона (см. запрос "invoice.templates")
Если нужно зафиксировать уже оплаченный счет, то включаем следующие параметры:
- 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" => '',
// шаблон Счета: имя файла или ID шаблона
"template" => "invoice.tpl",
"templateID" => "94",
];
$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 - тип счета - Предварительная оплата, Окончательная оплата, По спецификации, По договору, Счет-договор
- template - файл шаблона (см. запрос "templates") или
- templateID - ID шаблона (см. запрос "templates")
$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" => '',
// шаблон Счета: имя файла или ID шаблона
"template" => "invoice.tpl",
"templateID" => "94",
];
$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 или Номеру не найден
Запрос “invoice.templates” Новое
Запрос позволяет получить список шаблонов Счетов.
Пример запроса:
$params = [
"login" => "vladislav@isaler.ru",
"apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
"action" => "templates"
]
$urlparams = http_build_query($params);
Ответ:
- id - идентификатор шаблона
- title - название шаблона
- file - файл шаблона
- typeid - идентификатор типа документа ( templateTypeID )
{
"result":"Success",
"data":[
{"id":"33","title":"Базовый шаблон","file":"invoice.tpl","typeid":"94"},
{"id":"49","title":"Квитанция на оплату","file":"INV5c90829308d93_invoice.tpl","typeid":"94"},
{"id":"48","title":"Тестовый","file":"INV5c907bb21cf42_invoice.tpl","typeid":"94"},
{"id":"50","title":"Шаблон расширенный","file":"INV5c90944c14fab_invoice.tpl","typeid":"94"}
]
}
Возможные ответы в случае ошибок:
400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
404 – Шаблоны не найдены