Клиенты (client)

Метод “client”

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

URL для вызова:

http(s)://{{baseurl}}/developer/v3/client/запрос?параметр=значение

Запрос “fields”

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

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

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

GET http://localhost/developer/v3/client/fields
Content-Type: application/json
apikey: t1xdeOwWSIqgDol70CkRdK3WD4N4cm
login: vladislav@isaler.ru

Ответ:

{
    "data":{
        "clid":"Уникальный идентификатор записи клиента в CRM",
        "uid":"Уникальный идентификатор записи клиента в вашей ИС",
        "type":"Тип записи - client,person,concurent,contractor,partner",
        "date_create":"Дата создания. Timestamp",
        "date_edit":"Дата последнего изменения. Timestamp",
        "title":"Название",
        "iduser":"Ответственный",
        "idcategory":"Отрасль",
        "head_clid":"Головн. орг-ия",
        "pid":"Осн. контакт",
        "address":"Адрес",
        "phone":"Телефон",
        "fax":"Факс",
        "site_url":"Сайт",
        "mail_url":"Почта",
        "territory":"Территория",
        "des":"Описание",
        "scheme":"Принятие решений",
        "tip_cmr":"Тип отношений",
        "recv":"Реквизиты",
        "clientpath":"Источник клиента"
    }
}

Запрос “list”

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

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

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

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

string user – ограничение по пользователю (указывается логин пользователя)
int iduser – ограничение по пользователю (указывается ID пользователя)
date dateStart – начальная дата создания записи (формат - YYYY-MM-DD)
date dateEnd – конечная дата создания записи (не обязательно, формат - YYYY-MM-DD)
- только dateStart – вывод записей с датой создания больше указанной даты
- только dateEnd – вывод записей с датой создания меньше указанной даты
string word – слово поиска по полям title, des, phone, mail_url, site_url
string fields – ограничение вывода информации по записям с разделением запятыми без пробелов.
- Например, при указании fields=title,phone в ответе будут получены только названия клиента и его телефон
bool bankinfo – вывод банковских реквизитов клиента (true / false – по умолчанию)
bool uids – вывод связанных идентификаторов внешних систем (true / false – по умолчанию) [ см. Заявки ]

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

array filter - массив, содержащий дополнительные фильтры:
- string|int relation - тип отношений в текстовом виде (например, "Постоянный клиент")
- string|int idcategory - отрасль в текстовом или явном (в виде ID) виде
- string|int territory - территория в текстовом или явном (в виде ID) виде
- string|int clientpath - источник клиента в текстовом или явном (в виде ID) виде
- bool trash - признак нахождения в корзине (true / false)
- string type - тип клиента в текстовом виде (client, person, partner, contractor, concurent)
- string input1...input10 - доп.поле

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

GET http://localhost/developer/v3/client/list
Content-Type: application/json
apikey: t1xdeOwWSIqgDol70CkRdK3WD4N4cm
login: vladislav@isaler.ru

{
    "order": "date_change",
    "dateChangeStart": "2022-01-01",
    "dateChangeEnd": "2023-01-31",
    "fields": "clid,title,type,iduser,date_chage,date_create",
    "uids": true,
    "filter": {
        "type": "client",
        "territory": "Москва",
        "idcategory": "Промышленность",
        "trash": false
    }
}

Ответ:

data - список записей
params - доп.данные
- page - текущая страница
- pageall - общее кол-во страниц
count - общее количество записей в выборке

Запрос “info”

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

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

int clid – уникальный идентификатор записи клиента ИЛИ
string uid – уникальный идентификатор записи клиента во внешней системе ИЛИ
string inn – поиск по ИНН
bool bankinfo – вывод банковских реквизитов клиента (true / false – по умолчанию)
bool uids – вывод связанных идентификаторов внешних систем (true / false – по умолчанию) [ см. Заявки ]
bool contacts – вывод всех связанных контактов (true / false – по умолчанию)

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

GET http://sm2021.crm/developer/v3/client/info
Content-Type: application/json
apikey: t1xdeOwWSIqgDol70CkRdK3WD4N4cm
login: vladislav@isaler.ru

{
    "clid": 1781,
    "contacts": true,
    "bankinfo": true,
    "uids": true
}

Пример ответа:

{
    "data":{
        "clid":"1781",
        "title":"Сейлзмен Рус",
        "phone":"7(342)254-55-77, 8(912)884-45-55",
        "mail_url":"info@salesman.su",
        "bankinfo":{
            "castUrName":"Сейлзмен Рус",
            "castInn":"5904338272",
            "castKpp":"590401001",
            "castBank":"СИБИРСКИЙ ФИЛИАЛ АО КБ \"МОДУЛЬБАНК\", НОВОСИБИРСК",
            "castBankKs":"30101810350040000864",
            "castBankRs":"40702810621810000563",
            "castBankBik":"045004864",
            "castOkpo":"",
            "castOgrn":"1165958091530",
            "castDirName":"Андреева Владислава Германовича",
            "castDirSignature":"Андреев В.Г.",
            "castDirStatus":"Генерального директора",
            "castDirStatusSig":"Генеральный директор",
            "castDirOsnovanie":"Устава",
            "castUrAddr":"614007, г. Пермь, ул. Максима Горького, д. 83, оф.402"
        }
    }
}

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

403 – Клиент с указанным clid не найден в пределах аккаунта указанного пользователя
404 – Не найдено
405 – Отсутствуют параметры - clid клиента

Значения реквизитов клиента:

castUrName - Юридическое название
castInn - ИНН
castKpp - КПП
castBank - Банк
castBankKs - Кор.счет
castBankRs - Расч.счет
castBankBik - БИК банка
castOkpo - ОКПО
castOgrn - ОГРН
castDirName - ФИО руководителя, в род.падеже (в лице кого) - Иванова Ивана Ивановича
castDirSignature - ФИО руководителя, Иванов И.И.
castDirStatus - Должность руководителя, в род.падеже, Директора
castDirStatusSig - Должность руководителя, например: Директор
castDirOsnovanie - Основание Руководителя, в род. падеже - Устава, Доверенности №ХХХ
castUrAddr - Юр.адрес

Запрос “add”

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

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

string title – название клиента (обязательное поле)
string uid – id записи во внешней системе (например в 1С)
string type – тип записи: client (юр.лицо) – по умолчанию, person (физ.лицо), concurent, contractor, parnter
string user – login пользователя в SalesMan CRM назначаемого Ответственным за клиента
string|array phone - номера телефонов (разделенные ",", если отправляется в виде строки)
date date_create - дата добавления (опционально, в формате YYYY-MM-DD H:i:s)
прочие поля fields – информация для добавления
array recv – массив реквизитов (см.выше), не обязательное поле

Примечание

параметр date_create может быть указан в запросе. Если он отсутствует, то будет принят timestamp

при пустом поле user Ответственным будет назначен текущий пользователь (из запроса)

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

string idcategory – отрасль

string tip_cmr – тип отношений

string territory** – территория

string clientpath – источник клиента

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

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

POST http://sm2020.crm/developer/v3/client/add
Content-Type: application/json
apikey: t1xdeOwWSIqgDol70CkRdK3WD4N4cm
login: vladislav@isaler.ru

{
  "type": "client",
  "uid": "123400092",
  "title": "Пробный клиент 2024.1",
  "phone": ["+7(342)550-10-30", "+7(342)550-10-31"],
  "mail_url": "testplus20241@isaler.ru",
  "site_url": "testplus20241.ru",
  "territory": "Пермь",
  "clientpath": "100crm",
  "tip_cmr": "Потенциальный клиент",
  "idcategory": "Информационные технологии",
  "recv": {
    "castUrName": "ООО \"Пробный клиент 2024.1\"",
    "castInn": "590456789008",
    "castKpp": "590404218",
    "castBank": "Филиал ОАО «УРАЛСИБ» в г. Уфа",
    "castBankKs": "30101810600000000778",
    "castBankRs": "40702810301220001998",
    "castBankBik": "048073770",
    "castOgrn": "1145958040268"
  }
}

Ответ:

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

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

В случае ошибки 406 в поле data придет clid найденной существующей записи клиента

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

405 – Отсутствуют параметры
406 – Найден существующий клиент

Запрос “add.list”

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

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

параметры аналогичны запросу "add"
user – login пользователя в SalesMan CRM назначаемого Ответственным за клиента (не обязательный параметр, в случае отсутствия Ответственным назначается пользователь из параметра "login")

Запрос аналогичен запросу add, но параметры для каждой добавляемой записи передаются в массиве client

POST http://sm2020.crm/developer/v3/client/add.list
Content-Type: application/json
apikey: t1xdeOwWSIqgDol70CkRdK3WD4N4cm
login: vladislav@isaler.ru

{
    "client": [
        {
            "uid": "1234",
            "user": "marand@omadaru.ru",
            "type": "client",
            "title": "Пробный клиент t1000",
            "phone": "+7(343)260-10-10",
            "mail_url": "info@test100001.ru",
            "site_url": "test10001.ru",
            "territory": "Пермь",
            "clientpath": "Сайт",
            "tip_cmr": "Потенциальный клиент",
            "idcategory": "Торговля",
            "date_create": "2015-05-30 23:05:30",
            "recv": {
                "castUrName": "ООО \"Пробный клиент 01\"",
                "castInn": "590456789006",
                "castKpp": "590404210",
                "castBank": "Филиал ОАО \u00abУРАЛСИБ\u00bb в г. Уфа",
                "castBankKs": "30101810600000000770",
                "castBankRs": "40702810301220001991",
                "castBankBik": "048073770",
                "castOgrn": "1145958040260"
            }
        },
        {
            "uid": "1235",
            "user": "marand@omadaru.ru",
            "type": "client",
            "title": "Пробный клиент t2000",
            "phone": "+7(343)260-10-11",
            "mail_url": "info@test200001.ru",
            "site_url": "test200002.ru",
            "territory": "Пермь",
            "clientpath": "Сайт",
            "tip_cmr": "Потенциальный клиент",
            "idcategory": "Промышленность",
            "date_create": "2015-05-30 23:05:30",
            "recv": {
                "castUrName": "ООО \"Пробный клиент 02\"",
                "castInn": "590456789006",
                "castKpp": "590404210",
                "castBank": "Филиал ОАО \u00abУРАЛСИБ\u00bb в г. Уфа",
                "castBankKs": "30101810600000000770",
                "castBankRs": "40702810301220001991",
                "castBankBik": "048073770",
                "castOgrn": "1145958040260"
            }
        }
    ]
}

Ответ:

Ответ приходит для каждой добавляемой записи отдельно и содержит id добавленной записи.

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

405 – Отсутствуют параметры
406 – Найден существующий клиент

Запрос “update”

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

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

integer clid – уникальный идентификатор клиента (обязательное поле) ИЛИ
string uid – уникальный идентификатор клиента во внешней системе
прочие поля fields – информация для обновления
array recv – массив реквизитов (см.выше), не обязательное поле

Примечание

При передаче пустого поля - данные поля будут очищены в карточке Клиента

Реквизиты обрабатываются независимо от обновления основной информации в случае, если они указаны

Можно передавать только те реквизиты, которые надо обновить

Результат выносится в отдельный ответ "recv"

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

POST http://sm2020.crm/developer/v3/client/update
Content-Type: application/json
apikey: t1xdeOwWSIqgDol70CkRdK3WD4N4cm
login: vladislav@isaler.ru

{
    "clid": 6274,
    "uid": "123400192",
    "title": "Пробный клиент 2024.10",
    "phone": [
        "+7(342)550-10-30",
        "+7(342)550-10-31"
    ],
    "mail_url": "testplus20241@testplus20241.ru",
    "site_url": "testplus20241.ru",
    "tip_cmr": "2 - Потенциальный клиент",
    "recv": {
        "castKpp": "5904042180"
    }
}

Ответ:

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

{
    "data": 6274,
    "hid": 25319,
    "result": "Успешно; Реквизиты обновлены"
}

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

{
    "data": 6274,
    "result": "Данные корректны, но идентичны имеющимся.; Реквизиты обновлены"
}

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

403 – Клиент с указанным clid не найден в пределах аккаунта указанного пользователя
405 – Отсутствуют параметры - clid клиента

Запрос “delete”

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

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

integer clid – уникальный идентификатор клиента (обязательное поле)

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

GET http://sm2020.crm/developer/v3/client/delete
Content-Type: application/json
apikey: t1xdeOwWSIqgDol70CkRdK3WD4N4cm
login: vladislav@isaler.ru

{
    "clid": 6274
}

Ответ:

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

{
    "message": "Успешно: Клиент удален.<br>Также удалено 5 записи истории активностей. Снята привязка к Клиенту у 0 Контактов. Удалено 0 записей напоминаний. Удалено 0 файлов.",
    "result": "Клиент удален",
    "data": 6274
}

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

403 – Клиент с указанным clid не найден в пределах аккаунта указанного пользователя
405 – Отсутствуют параметры - clid клиента
406 – Удаление клиента не возможно - есть сделки