Facebook Google Plus Youtube

Сделки (contract)

Метод “contract”

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

Запрос “fields”

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

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=fields

Ответ:

{
 "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”

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=steplist

Ответ:

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

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

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

Запрос “direction”

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=direction

Ответ:

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

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

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

Запрос “contracttipe”

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=contracttipe

Ответ:

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

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

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

Запрос “statusclose”

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=statusclose

Ответ:

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

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

  • 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 - по умолчанию)

Дополнительные фильтры:

  • filter - массив, содержащий дополнительные фильтры:
    • clid - идентификатор клиента-заказчика
    • payer - идентификатор клиента-плательщика
    • direction - направление деятельности в текстовом виде (напроимер, основное)
    • tip - тип сделки в текстовом виде
    • input1...input10 - доп.поле

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

$params['login'] = "vladislav@isaler.ru";
$params['apikey'] = 'aMgiCQyj8bCToNc47BZZYrRICoWSIl';
$params['action'] = 'list';
$params['filter']['tip'] = 'Услуги';
$params['filter']['direction'] = 'Отделка';
$params['filter']['input1'] = 'Текст';

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=list&offset=0&order=datum&first=&user=&dateStart=2015-01-01&dateEnd=&word=&fields=did,clid,title,kol,marga

Ответ:

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

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

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

Запрос “info”

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

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

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=info&did=744

Ответ:

{
 "data":{
   "did":"744",
   "datum":"2015-01-31",
   "datum_izm":null,
   "clid":"1781",
   "clientname":"Юлла, ООО",
   "title":"Продажа для Юлла, ООО",
   "mcid":"3",
   "iduser":"vladislav@isaler.ru",
   "datum_plan":"2015-06-30",
   "step":"90",
   "dog_num":"192",
   "tip":"Продажа услуг",
   "direction":"Проектные работы",
   "adres":"г. Пермь, ул. Коммунистическая, 41",
   "content":"",
   "payer":"1781",
   "payername":"Юлла, ООО",
   "kol":"27741.00",
   "marga":"7622.00",
   "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"
 }
}

Ответ также будет содержать 2 блока, если в параметрах нет отказа от их вывода:

  • "speka" - спецификация
    • "artikul" - артикул продукта
    • "title" -  название позиции
    • "kol" - количество
    • "dop" - доп.множитель, если не используется = 1
    • "price" - цена продажи
    • "price_in" - закупочная стоимость
    • "edizm" единица измерения
    • "nds" - НДС в % если есть
  • "invoice" - список выставленных счетов (см. также "Добавление счета")
    • "id" - идентификатор записи счета (если номер не уникален или не указан)
    • "invoice" - номер счета
    • "date" - дата счета в формате ГГГГ-ММ-ДД
    • "summa" - сумма счета
    • "nds" - НДС по счету
    • "do" - признак оплаченного счета (оплачен = on)
    • "date_do" - дата оплаты в формате ГГГГ-ММ-ДД
    • "contract" - номер договора (если есть)
    • "rs" - идентификатор расчетного счета в CRM
    • "tip" - тип счета (например, Счет-договор)

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

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

Запрос “add”

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

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

  • uid – уникальный идентификатор во внешней ИС
  • title – название сделки (обязательное поле)
  • clid –идентификатор клиента, к которому будет привязана сделка (обязательное поле)
  • payer - идентификатор клиента-плательщика
  • datum_plan – плановая дата закрытия сделки
  • mcid – идентификатор своей компании (можно получить в отдельном запросе)
  • user – login пользователя в SalesMan CRM назначаемого Ответственным за клиента
  • прочие поля 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";
$params['apikey'] = 'aMgiCQyj8bCToNc47BZZYrRICoWSIl';
$params['action'] = 'add';
$params['mcid'] = '2'; //id компании в справочнике "Мои компании"
$params['user'] = '';
$params['clid'] = '1781';
$params['datum_plan'] = '2015-05-30';
$params['payer'] = '';//м.б. пустым, если равен clid
$params['title'] = 'Пробная сделка API №1';
$params['content'] = 'Текст описания.';
$params['step'] = '20';
$params['kol'] = '100000.00';
$params['marga'] = '30000.00';
$params['tip'] = 'Продажа услуг';
$params['direction'] = 'Оборудование';
$urlparams = http_build_query($params);

Ответ:

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

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

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

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

Запрос “update”

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

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

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

Важно:

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=update&did=1820&step=40&kol=120000.00&marga=40000.00&datum_plan=2015-06-10

Ответ:

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

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

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

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

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

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

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

Запрос “changestep”

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

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

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

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

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=changestep&did=764&step=40&reason=

Ответ:

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

{"result":"Успешно","data":1820,"message":" Поставлена отметка о выполнении Контрольной точки - Согласование спецификаци"}

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

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

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

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

Запрос “close”

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

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

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

Примечание:

  • kol_fact и marga не обязательные, при отсутствии будут равны сумме и марже сделки

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=close&did=764&status_close=

Ответ:

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

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

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

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

Запрос “delete”

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

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

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

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

http(s)://crm_url/developer/v1/contract?login=vladislav@isaler.ru&apikey=aMgiCQyj8bCToNc47BZZYrRICoWSIl&action=delete&did=764

Ответ:

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

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

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

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

Запрос “addinvoice”

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

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

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

Важно:

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

Ответ:

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

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

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

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

Запрос “addpaiment”

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

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

  • invoice - номер счета
  • id - идентификатор записи счета (если номер не уникален или не указан)
  • date_do - дата оплаты, если пусто - текущая дата

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

Ответ:

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

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

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

Запрос “addpaimentpart” Новое

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

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

  • invoice - номер счета (обязательный параметр)
  • id - идентификатор записи счета (если номер не уникален или не указан)
  • date_do - дата оплаты, если пусто - текущая дата
  • summa - сумма оплаты, должна быть больше нуля и меньше/равно сумме счета

Ответ:

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

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

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

 

Что-то не понятно? Задай вопрос: