Контакты (person)

Метод “person”

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

URL для вызова:

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

Запрос “fields”

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

Запрос “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 - доп.поле

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

GET http://{{baseurl}}/developer/v3/person/list
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "order": "date_edit",
    "dateStart": "2021-01-01",
    "dateEnd": "2023-01-31",
    "fields": "clid,person,ptitle,tel,mob,mail",
    "socinfo": true,
    "filter": {
        "clientpath": 177
    }
}

Ответ:

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

Запрос “info”

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

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

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

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

GET http://{{baseurl}}/developer/v3/person/info
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "pid": 2797,
    "fields": "pid,clid,person,ptitle,tel,mob,mail"
}

Ответ:

{
    "data": {
        "pid": 2797,
        "clid": 6255,
        "client": "Ляпис Трубецкой",
        "person": "Георгий Трубецкой",
        "ptitle": "Коммерческий директор",
        "tel": "7 (945) 700-70-70",
        "mob": null,
        "mail": "george.truba@gmail.com"
    }
}

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

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 – источник клиента

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

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

POST http://sm2020.crm/developer/v3/person/add
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "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": "salesman.pro",
    "loyalty": "0 - Не лояльный"
}

Ответ:

{
    "result": "Контакт добавлен",
    "data": 2804,
    "error": ""
}

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

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

Запрос “add.list”

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

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

POST http://{{baseurl}}/developer/v3/person/add.list
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "persons": [
        {
            "clid": 6276,
            "person": "Тест 911",
            "ptitle": "Технический директор",
            "tel": "+7(342)250-50-98, +7(342)290-50-99",
            "mob": "+7(922)250-50-99",
            "mail": "test911@mailio.ru",
            "clientpath": "salesman.pro",
            "loyalty": "1 - Пока не понятно"
        },
        {
            "clid": 6276,
            "person": "Тест 912",
            "ptitle": "Генеральный директор",
            "tel": "+7(342)250-20-98, +7(342)290-20-99",
            "mob": "+7(922)250-20-99",
            "mail": "test912@mailio.ru",
            "clientpath": "salesman.pro",
            "loyalty": "1 - Пока не понятно"
        }
    ]
}

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

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

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

Ответ:

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

[
  {
    "result": "Контакт добавлен",
    "data": 2805,
    "error": ""
  },
  {
    "result": "Контакт добавлен",
    "data": 2806,
    "error": ""
  }
]

Важно

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

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

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

Запрос “update”

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

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

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

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

POST http://{{baseurl}}/developer/v3/person/update
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "pid": 2804,
    "ptitle": "Технический инженер",
    "mob": "+7(922)250-59-59",
    "mail": "a.i.apirovv@mailio.ru",
    "loyalty": "1 - Пока не понятно"
}

Ответ:

{
    "result": "Данные контакта обновлены",
    "data": 2804,
    "error": ""
}

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

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

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

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

Запрос “delete”

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

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

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

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

POST http://{{baseurl}}/developer/v3/person/delete
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "pid": 2804
}

Ответ:

{
    "message": "Успешно: Контакт удален. Также удалено 4 записи истории активностей. Удалено 0 записей напоминаний. Удалено 0 файлов",
    "result": "Клиент удален",
    "data": 2804
}

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

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