Контакты (person)

Метод “person”

Метод позволяет управлять записями Контактов – добавлять, обновлять, удалять. Метод аналогичен методу “client”, но в нем отсутствуют специфичные сущности "Контакт" параметры.

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

Запрос “fields”

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

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

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


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

$urlparams = http_build_query($params);

Ответ:


{
 "data":{
   "pid":"Уникальный идентификатор записи контакта",
   "date_create":"Дата создания. Timestamp",
   "date_edit":"Дата последнего изменения. Timestamp",
   "clid":"Клиент",
   "ptitle":"Должность",
   "person":"Ф.И.О.",
   "tel":"Тел.",
   "fax":"Факс",
   "mob":"Моб.",
   "mail":"Почта",
   "rol":"Роль",
   "social":"Прочее",
   "iduser":"Ответственный",
   "loyalty":"Лояльность",
   "input1":"Дата рождения",
   "clientpath":"Источник клиента",
   "blog":"Блог",
   "mysite":"Сайт",
   "twitter":"Twitter",
   "icq":"ICQ",
   "skype":"Skype",
   "google":"Google",
   "yandex":"Я.ru",
   "mykrug":"Мой круг"
   }  
}

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

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

Запрос “list”

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

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

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

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

user – ограничение по пользователю (указывается логин пользователя)
dateStart – начальная дата создания записи (формат - YYYY-MM-DD)
dateEnd – конечная дата создания записи (не обязательно, формат - YYYY-MM-DD)
- только dateStart – вывод записей с датой создания больше указанной даты
- только dateEnd – вывод записей с датой создания меньше указанной даты
word – слово поиска по полям person, ptitle, tel, mail
fields – ограничение вывода информации по записям с разделением запятыми без пробелов. Например, при указании fields= person,tel в ответе будут получены только ФИО контакта и его телефон
socinfo – включает вывод социальных контактов (Блог, Сайт, Twitter, ICQ, Skype, Google, Я.ru, Мой круг)

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

filter - массив, содержащий дополнительные фильтры:
- clid - идентификатор клиента (целое число)
- clientpath - источник клиента в текстовом виде
- input1...input10 - доп.поле

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"    => 'list',
    // страница, с учетом вывода 200 записей на страницу
    "offset"    => 0,
    // поле для упорядочивания записей
    "order"     => 'date_create',
    // направление сортировки; new - по-умолчанию, old - сначала более старые
    "first"     => '',
    // ограничение по login пользователя, пользователь должен быть в подчинении у текущего
    "user"      => '',
    // даты создания
    "dateStart" => '2016-01-01',
    "dateEnd"   => '2018-06-01',
    // строка поиска по полям title, des, phone, mail_url, site_url
    "word"      => '',
    // фильтры
    "filter"    => [
        // string, фильтр по типу отношений (список доступен в методе guides в запросе relations)
        "loyalty"  => 'Лояльный',
        // string|integer, фильтр по должности
        "ptitle" => 'Директор',
        // string, фильтр по источнику
        "clientpath" => '',
        // string, фильтр по доп.полю
        "input1"     => ''
    ],
    // для вывода только заданных полей из конкретной записи == list, info
    //"fields"    => 'clid,person,tel,mob,mail',
    // для включения социальных контактов
    //"socinfo"  => 'yes'
];

$urlparams = http_build_query($params);

Ответ:

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

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

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

Запрос “info”

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

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

pid – уникальный идентификатор записи клиента
fields – ограничение вывода информации по полям с разделением запятыми без пробелов. Например, при указании fields=title,phone в ответе будут получено только название клиента и его телефон
socinfo – включает вывод социальных контактов (Блог, Сайт, Twitter, ICQ, Skype, Google, Я.ru, Мой круг)

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"  => 'info',
    // id контакта
    "pid"     => '2475',
    // для вывода только заданных полей из конкретной записи == list, info
    "fields"  => 'clid,person,ptitle,tel,mob,mail',
    // для включения банковских реквизитов
    "socinfo" => 'yes'
];

$urlparams = http_build_query($params);

Ответ:


{
    "data":{
        "clid":"1781",
        "client":"Сейлзмен Рус",
        "person":"Андреев Владислав Германович",
        "ptitle":"Коммерческий директор",
        "tel":"7 (342) 206-72-02",
        "mob":"7 (922) 328-94-66",
        "mail":"v@salesman.pro",
        "socials":{
            "blog":"333",
            "mysite":"333",
            "twitter":"333",
            "icq":"333",
            "skype":"andreev.v.g",
            "google":"333",
            "yandex":"333",
            "mykrug":"333"
        }
    }
}

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

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

Запрос “add”

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

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

person – название клиента (обязательное поле)
user – login пользователя в SalesMan CRM назначаемого Ответственным за клиента
mperson - yes|no - установить контакт основным
прочие поля fields – информация для добавления
socials – массив полей для социальных контактов
- blog => Блог
- mysite => Сайт
- twitter => Twitter
- icq => ICQ
- skype => Skype
- google => Google
- yandex => Я.ru
- mykrug => Мой круг

Примечание

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

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

mperson - для установки контакта Основным (если привязывается к Клиенту) (mperson=yes)

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

loyalty – лояльность

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

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

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


$params = [
    "login"      => "vladislav@isaler.ru",
    "apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'add',
    "clid"       => 1781,
    "person"     => 'Апиров Апист Иванович',
    "ptitle"     => 'Технический директор',
    "tel"        => '+7(342)250-50-50, +7(342)290-50-51',
    "mob"        => '+7(922)250-50-50',
    "mail"       => 'a.i.apirov@mailio.ru',
    "clientpath" => 'Voxlink',
    "loyalty"    => '0 - Не лояльный',
    "socials"    => [
        "blog"    => 'http://api.blog.rus',
        "mysite"  => 'http://apiapi.rus',
        "twitter" => 'apiapi',
        "icq"     => '123456789',
        "skype"   => 'apiapi',
        "google"  => 'apiapi',
        "yandex"  => 'apiapi',
        "mykrug"  => 'apiapi'
    ],
    // установить основным контактом
    "mperson"    => "yes"
];

$urlparams = http_build_query($params);

Ответ:

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

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

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

Запрос “add.list”

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

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

user – login пользователя назначаемого Ответственным за клиентов. Он может быть указан для конкретной добавляемой записи
остальные параметры аналогичны запросу "add"

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

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


$params = [
    "login"      => "vladislav@isaler.ru",
    "apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'addlist',
    "persons" => [
        [
            "clid"       => 6212,
            "person"     => 'Тест 900000',
            "ptitle"     => 'Технический директор',
            "tel"        => '+7(342)250-50-50, +7(342)290-50-51',
            "mob"        => '+7(922)250-50-54',
            "mail"       => 'test90000@mailio.ru',
            "clientpath" => 'Voxlink',
            "loyalty"    => '1 - Пока не понятно',
            "socials"    => [
                "blog"    => 'http://api.blog2.rus',
                "mysite"  => 'http://apiapi2.rus',
                "twitter" => 'apiapi',
                "icq"     => '12345678900',
                "skype"   => 'apiapi2',
                "google"  => 'apiapi2',
                "yandex"  => 'apiapi2',
                "mykrug"  => 'apiapi2'
            ]
        ],
        [
            "clid"       => 6213,
            "mperson"    => "yes",
            "person"     => 'Тест 100000',
            "ptitle"     => 'Генеральный директор',
            "tel"        => '+7(342)290-90-90, +7(342)290-90-91',
            "mob"        => '+7(922)290-90-94',
            "mail"       => 'test100000@mailio.ru',
            "clientpath" => 'Вконтакте',
            "loyalty"    => '2 - Нейтральный',
            "user"       => "marand@omadaru.ru",
            "socials"    => [
                "blog"    => 'http://api.blog2.rus',
                "mysite"  => 'http://apiapi2.rus',
                "twitter" => 'apiapi4',
                "icq"     => '25345678900',
                "skype"   => 'apiapi4',
                "google"  => 'apiapi4',
                "yandex"  => 'apiapi4',
                "mykrug"  => 'apiapi4'
            ]
        ]
    ]
];

$urlparams = http_build_query($params);

Ответ:

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


[
    {"result":"Успешно","data":2509},
    {"result":"Успешно","data":2510}
]

Важно

Проверка на дубли не производится - см. [модуль "Дубли"](https://salesman.pro/docs/137 "Модуль "Дубли"")

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

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

Запрос “update”

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

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

pid – уникальный идентификатор контакта (обязательное поле)
прочие поля fields – информация для обновления
socials – информация для обновления

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


$params = [
    "login"      => "vladislav@isaler.ru",
    "apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'update',
    "pid"        => 2750,
    "person"     => 'Апиров Апист Иванович',
    //"ptitle"     => 'Технический директор',
    //"tel"        => '+7(342)250-50-50, +7(342)290-50-51',
    "mob"        => '+7(922)250-50-54',
    //"mail"       => 'a.i.apirov@mailio.ru',
    "clientpath" => 'Voxlink',
    "loyalty"    => '1 - Пока не понятно',
    "socials"    => [
        "blog"    => 'http://api.blog2.rus',
        "mysite"  => 'http://apiapi2.rus',
        "twitter" => 'apiapi',
        "icq"     => '12345678900',
        "skype"   => 'apiapi2',
        "google"  => 'apiapi2',
        "yandex"  => 'apiapi2',
        "mykrug"  => 'apiapi2'
    ]
];

$urlparams = http_build_query($params);

Ответ:

{"result":"Успешно","data":"2509","social":"Соц.контакты обновлены"}

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

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

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

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

Запрос “delete”

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

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

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

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "delete",
    "pid"    => 2509
];

$urlparams = http_build_query($params);

Ответ:

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

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

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