# Клиенты (client)

## Метод “client”

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

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

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

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

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

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

<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":{
        "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":"Источник клиента"
        }
    }
}
</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** – слово поиска по полям title, des, phone, mail_url, site_url
- **fields** – ограничение вывода информации по записям с разделением запятыми без пробелов. 
  - Например, при указании fields=title,phone в ответе будут получены только названия клиента и его телефон
- **bankinfo** – вывод банковских реквизитов клиента (yes / no – по умолчанию)
- **uids** – вывод связанных идентификаторов внешних систем (yes / no – по умолчанию)  [ см. [Заявки](https://salesman.pro/api2/lead#uids) ]

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

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

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

<pre><code class="php">
  $params = [
 	"login" => "vladislav@isaler.ru",
	"apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	"action" => "list",
	"filter" => [
		"type" => "client",
		"territory" => "Москва",
		"idcategory" => "Промышленность",
		"clientpath" => "Выставка",
		"trash" => "no",
		"input1" => "Текст",
	]
  ]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

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

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

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


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

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

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

- **clid** – уникальный идентификатор записи клиента
- ИЛИ **uid** – уникальный идентификатор записи клиента во внешней системе
- ИЛИ **inn** – поиск по ИНН
- **fields** – ограничение вывода информации по полям с разделением запятыми без пробелов. Например, при указании fields=title,phone в ответе будут получено только название клиента и его телефон
- **bankinfo** – вывод банковских реквизитов клиента (yes / no – по умолчанию)
- **uids** – вывод связанных идентификаторов внешних систем (yes / no – по умолчанию) [ см. [Заявки](https://salesman.pro/api2/lead#uids) ]
- **contacts** – вывод всех связанных контактов (yes / no – по умолчанию)

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

<pre><code class="php">
$params = [
	"login"    => "vladislav@isaler.ru",
	"apikey"   => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	"action"   => 'info',
	"clid"     => '1781',
	"fields"   => 'clid,title,phone,mail_url',
	"bankinfo" => 'yes'
];

$urlparams = http_build_query($params);

</code></pre>


**Ответ**:

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


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

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

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

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


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


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

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

- **title** – название клиента (обязательное поле)
- **uid** – id записи во внешней системе (например в 1С)
- **type** – тип записи: client (юр.лицо) – по умолчанию, person (физ.лицо), concurent, contractor, parnter
- **user** – login пользователя в SalesMan CRM назначаемого Ответственным за клиента
- прочие поля **fields** – информация для добавления
- **recv** – массив реквизитов (см.выше), не обязательное поле

> ### Примечание
> 
> параметр **date_create** может быть указан в запросе. Если он отсутствует, то будет принят timestamp при пустом поле user Ответственным будет назначен текущий пользователь (из запроса) следующие параметры передаются в явном, текстовом виде:
> 
> - **idcategory** – отрасль
> - **tip_cmr** – тип отношений
> - **territory** – территория
> - **clientpath** – источник клиента
> 
> В случае отсутствия переданных значений в справочниках будут созданы новые записи

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

<pre><code class="php">
$params = [
	"login"       => "vladislav@isaler.ru",
	"apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	"action"      => "add",
	"type"        => "client",
	"uid"         => "1234",
	"user"        => "user@mail.com",
	"title"       => "Пробный клиент API plus",
	"phone"       => "+7(342)260-10-10, +7(342)260-10-11",
	"mail_url"    => "test.api1@yoolla-api.ru",
	"site_url"    => "yoolla-api.ru",
	"territory"   => "Пермь",
	"clientpath"  => "Сайт SalesManAPI.ru",
	"tip_cmr"     => "Потенциальный клиент",
	"idcategory"  => "Не определена",
	"date_create" => "2015-05-30 23:05:30",//в часовом поясе аккаунта
	"recv"        => [
		"castUrName"  => "ООО \"Пробный клиент API plus\"",
		"castInn"     => "590456789006",
		"castKpp"     => "590404210",
		"castBank"    => "Филиал ОАО «УРАЛСИБ» в г. Уфа",
		"castBankKs"  => "30101810600000000770",
		"castBankRs"  => "40702810301220001991",
		"castBankBik" => "048073770",
		"castOgrn"    => "1145958040260",
	]
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ**:

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

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

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

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

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

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


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

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

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

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

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

<pre><code class="php">
$params = [
	"login" => "vladislav@isaler.ru",
	"apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	"action" => "add.list",
	"client" => [
		[
			"uid"         => "1234",
			"user"        => "user@mail.com",
			"type"        => "client",
			"title"       => "Пробный клиент 01",
			"phone"       => "+7(342)260-10-10",
			"mail_url"    => "info@test01.ru",
			"site_url"    => "test01.ru",
			"territory"   => "Пермь",
			"clientpath"  => "Сайт",
			"tip_cmr"     => "Потенциальный клиент",
			"idcategory"  => "Торговля",
			"date_create" => "2015-05-30 23:05:30",//в часовом поясе аккаунта
			"recv"        => [
				"castUrName"  => "ООО \"Пробный клиент 01\"",
				"castInn"     => "590456789006",
				"castKpp"     => "590404210",
				"castBank"    => "Филиал ОАО «УРАЛСИБ» в г. Уфа",
				"castBankKs"  => "30101810600000000770",
				"castBankRs"  => "40702810301220001991",
				"castBankBik" => "048073770",
				"castOgrn"    => "1145958040260",
			]
		],
		[
			"uid"         => "1234",
			"user"        => "user@mail.com",
			"type"        => "client",
			"title"       => "Пробный клиент 02",
			"phone"       => "+7(342)260-10-11",
			"mail_url"    => "info@test01.ru",
			"site_url"    => "test02.ru",
			"territory"   => "Пермь",
			"clientpath"  => "Сайт",
			"tip_cmr"     => "Потенциальный клиент",
			"idcategory"  => "Промышленность",
			"date_create" => "2015-05-30 23:05:30",//в часовом поясе аккаунта
			"recv"        => [
				"castUrName"  => "ООО \"Пробный клиент 02\"",
				"castInn"     => "590456789006",
				"castKpp"     => "590404210",
				"castBank"    => "Филиал ОАО «УРАЛСИБ» в г. Уфа",
				"castBankKs"  => "30101810600000000770",
				"castBankRs"  => "40702810301220001991",
				"castBankBik" => "048073770",
				"castOgrn"    => "1145958040260",
			]
		]
	]
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ**:

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

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

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

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


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

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

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

> ### Примечание
> 
> - При передаче пустого поля - данные поля будут очищены в карточке Клиента
> - Реквизиты обрабатываются независимо от обновления основной информации в случае, если они указаны
> - Можно передавать только те реквизиты, которые надо обновить
> - Результат выносится в отдельный ответ "recv"

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

<pre><code class="php">
$params = [
	"login" => "vladislav@isaler.ru",
	"apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	"action"      => "update",
	"clid"        => "6214",
	"title"       => "Пробный клиент 5052",
	"phone"       => "+7(342)260-52-10, +7(342)260-52-11",
	"mail_url"    => "info@testplus5051.ru",
	"site_url"    => "testplus5052.ru",
	"territory"   => "Пермь",
	"clientpath"  => "Сайт isaler.com",
	"tip_cmr"     => "Текущий клиент",
	"idcategory"  => "Информационные технологии",
	"recv"        => [
		"castUrName"  => "ООО \"Пробный клиент 5052\"",
		"castInn"     => "590456789052",
		"castKpp"     => "590404300",
		"castBank"    => "Филиал ОАО «УРАЛСИБ» в г. Уфа",
		"castBankKs"  => "30101810600000000770",
		"castBankRs"  => "40702810301220001991",
		"castBankBik" => "048073770",
		"castOkpo"    => "58040260",
		"castOgrn"    => "1145958040260",
	]
];

$urlparams = http_build_query($params);

</code></pre>

**Ответ**:

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

<pre><code class="json">{"result":"Успешно; Реквизиты обновлены","data":1820}</code></pre>

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

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

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

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

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


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

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

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

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

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

**Ответ:**

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

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

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

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

