# Контакты (person)

## Метод “person”

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

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

<a id="fields"></a>
### Запрос “fields”

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

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

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

<pre><code class="php">
  $params = [
 	"login" => "vladislav@isaler.ru",
	"apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	"action" => "fields"
  ]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{
 "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":"Мой круг"
   }  
}
</code></pre>

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

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

<a id="list"></a>
### Запрос “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**:

<pre><code class="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);

</code></pre>


**Ответ:**

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

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

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

<a id="info"></a>
### Запрос “info”


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

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

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

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

<pre><code class="php">
$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);
</code></pre>

**Ответ:**

<pre><code class="json">
{
	"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"
		}
	}
}
</code></pre>

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

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

<a id="add"></a>
### Запрос “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:**

<pre><code class="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);

</code></pre>

**Ответ:**

<pre><code class="json">{"result":"Успешно","data":2502}</code></pre>

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

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

<a id="add.list"></a>
### Запрос “add.list”

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

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

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

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

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

<pre><code class="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);

</code></pre>

**Ответ:**

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

<pre><code class="json">
[
	{"result":"Успешно","data":2509},
	{"result":"Успешно","data":2510}
]
</code></pre>

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

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

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

<a id="update"></a>
### Запрос “update”


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

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

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

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

<pre><code class="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);

</code></pre>


**Ответ:**

<pre><code class="json">{"result":"Успешно","data":"2509","social":"Соц.контакты обновлены"}</code></pre>

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

<pre><code class="json">{"result":"Данные корректны, но идентичны имеющимся","data":2509}</code></pre>

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

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

<a id="delete"></a>
### Запрос “delete”

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

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

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

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">{"result":"Успешно","data":2509}</code></pre>

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

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