# Документы (document)

## Метод “document”

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

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

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

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

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

- **id** - идентификатор типа документа (idtype)
- **type** - название типа документа
- **role** - список ролей сотрудников, которым доступно создание документа конкретного типа
- **users** - идентификаторы сотрудников, которым доступно создание документа конкретного типа
- **number** - крайний номер документа
- **format** - формат, по которому генерируется номер документа
- **templates** - список шаблонов

<pre><code class="json">
{
	"data":[
		{
			"id":"1",
			"title":"Договор",
			"type":"Договор",
			"role":"Руководитель с доступом,Руководитель подразделения,Руководитель отдела,Менеджер продаж",
			"users":"",
			"number":"0",
			"format":"СД{cnum}",
			"templates":[
				{"id":"4","title":"Договор на услуги","file":"doc1.docx"},
				{"id":"8","title":"Договор на оборудование","file":"doc2.docx"},
				{"id":"18","title":"Договор. Услуги (обслуживание)","file":"doc3.docx"},
				{"id":"27","title":"Договор на внедрение","file":"doc4.docx"}
			]
		},
		{
			"id":"46",
			"title":"Договор на рекламу",
			"type":"Собственный",
			"role":"",
			"users":"",
			"number":"14",
			"format":"{cnum}-{DD}{MM}",
			"templates":[
				{"id":"14","title":"Договор вправе","file":"doc5.docx"}
			]
		},
		{
			"id":"47",
			"title":"Дополнительное соглашение",
			"type":"Собственный",
			"role":"",
			"users":"",
			"number":"32",
			"format":"{cnum}",
			"templates":[
				{"id":"20","title":"Документ 2","file":"doc6.docx"},
				{"id":"21","title":"Документ 2 с графиком","file":"doc7.docx"},
				{"id":"30","title":"Заявка","file":"doc10.docx"},
				{"id":"31","title":"Продление подписки","file":"doc11.docx"}
			]
		}
	]
}
</code></pre>


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

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

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

Запрос позволяет получить список статусов Документов для формирования дальнейших запросов.

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

- **id** - идентификатор статуса
- **title** - название статуса
- **color** - цветовая схема статуса
- **type** - массив, содержащий типы документов, к которым применяется статус (idtype => Название)

<pre><code class="json">
{
	"data":[
		{
			"id":"1",
			"title":"Создан",
			"color":"#9edae5",
			"type":{
				"2":"Акт приема-передачи",
				"9":"Акт сервисный",
				"1":"Договор",
				"46":"Договор на рекламу",
				"47":"Дополнительное соглашение"
			}
		},
		{
			"id":"3",
			"title":"Отправлен клиенту (электронно)",
			"color":"#008000",
			"type":{
				"2":"Акт приема-передачи",
				"9":"Акт сервисный",
				"1":"Договор",
				"47":"Дополнительное соглашение",
				"46":"Договор на рекламу"
			}
		},
		...
	]
}
</code></pre>


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

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

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

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

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

- **id** – уникальный идентификатор записи

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

<pre><code class="php">
$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	// указываем метод
	"action" => 'info',
	"id"     => 334
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

Ответ содержит следующие специфичные данные:

- **datum** - Дата создания документа
- **typeDoc** - Тип документа (title из запроса tips)
- **idtype** - ID типа документа (id из запроса tips)
- **description** - описание Документа
- **mcid** - id Компании, от которой ведется сделка
- **signer** - id подписанта
- **status** - id статуса документа
- **statusTitle** - расшифровка статуса
- **files** - массив файлов, вложенных в документ

<pre><code class="json">

{
	"data":{
		"deid":"334",
		"datum":"2018-07-06 13:22:49",
		"number":"32",
		"title":"Дополнительное соглашение",
		"date.start":"2018-07-06",
		"date.end":"2018-12-31",
		"typeDoc":"Документ TBS",
		"idtype":"47",
		"description":"",
		"clid":1781,
		"clientTitle":"Сейлзмен Рус",
		"payer":1781,
		"payerTitle":"Сейлзмен Рус",
		"did":902,
		"dealTitle":"СД4250: Сейлзмен Рус",
		"mcid":2,
		"signer":2,
		"status":1,
		"statusTitle":"Создан",
		"files":[
			{
				"name":"Дополнительное соглашение №32 от 06.07.2018.docx",
				"file":"http://sm2018.crm/files/1530865531.docx"
			}
		]
	}
}
</code></pre>

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

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

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

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

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

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

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

- **user** – ограничение по пользователю (указывается логин пользователя)
- **dateStart** – начальная дата напоминания (формат - YYYY-MM-DD)
- **dateEnd** – конечная дата напоминания (не обязательно, формат - YYYY-MM-DD)
  - только dateStart – вывод записей с датой выполнения больше указанной даты
  - только dateEnd – вывод записей с датой выполнения меньше указанной даты
- **word** – фильтр по названию, описанию или номеру документа
- **idtype** - по типу документа, список idtype (id из запроса tips) через запятую
- **clid** - фильтр по Клиенту
- **did** - фильтр по Сделке
- **signer** - id подписанта

> ### Примечание
> 
> Если не указан **user**, то будут выведены записи текущего пользователя и всех подчиненных

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

<pre><code class="php">
$params = [
    "login"     => "vladislav@isaler.ru",
    "apikey"    => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action"    => 'list',
	// страница, с учетом вывода 200 записей на страницу
	"offset"    => 0,
	// поле для упорядочивания записей
	"order"     => 'datum',
	// направление сортировки; new - по-умолчанию, old - сначала более старые
	"first"     => '',
	// ограничение по login пользователя
	//"user"    => 'marand@omadaru.ru',
	// даты создания
	"dateStart" => '2018-01-01',
	"dateEnd"   => '2018-08-31',
	// фильтр по названию, описанию или номеру документа
	"word"      => '',
	// по типу документа, список idtype (id из запроса tips) через запятую
	"idtype"    => 47,
	//фильтр по клиенту
	"clid"      => 0,
	//фильтр по сделке
	"did"       => 784
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{
	"data":[
		{
			"id":"334",
			"datum":"06.07.2018",
			"date.start":"06.07.2018",
			"date.end":"31.12.2018",
			"number":"32",
			"title":"Дополнительное соглашение",
			"clid":"1781",
			"client":"Сейлзмен Рус",
			"did":"902",
			"deal":"СД4250: Сейлзмен Рус",
			"payerid":"1781",
			"payer":"Сейлзмен Рус",
			"idtype":"47",
			"typeDoc":"Документ TBS",
			"mcid":"3",
			"signer":"1",
			"status":"1",
			"statusTitle":"Создан",
			"statusColor":"#9edae5"
		},
		{
			"id":"333",
			"datum":"06.07.2018",
			"date.start":"06.07.2018",
			"date.end":"31.12.2018",
			"number":"31",
			"title":"Дополнительное соглашение",
			"clid":"1781",
			"client":"Сейлзмен Рус",
			"did":"902",
			"deal":"СД4250: Сейлзмен Рус",
			"payerid":"1781",
			"payer":"Сейлзмен Рус",
			"idtype":"47",
			"typeDoc":"Документ TBS",
			"mcid":"3",
			"signer":"1",
			"status":"1",
			"statusTitle":"Создан",
			"statusColor":"#9edae5"
		}
	],
	"count":"2"
}
</code></pre>

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

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


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

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

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

- **user** – login пользователя в SalesMan CRM, которому назначается напоминание
- **title** - название документа. Если не указан, то принимается как Название шаблона
- **description** - описание
- **mcid** - mcid компании, от которой ведется сделка. Не обязательно, если указан did
- **signer** - id подписанта компании
- **idtype** - тип документа (id из запроса "tips")
- **template** - id шаблона (см. запрос "tips")
- **dateStart** - период действия. начало
- **dateEnd** - период действия. конец
- **status** - id статуса документа (см. запрос "statuses")
- **pdf** - yes, если требуется сгенерировать PDF-файл (дольше)
- **clid** - ID клиента
- **pid** - ID контакта
- **did** - ID сделки

> ### Примечание
> 
> 1. при пустом поле **user** Ответственным будет назначен текущий пользователь (из запроса)
> 2. если указан did сделки, то параметры clid и payer игнорируются

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

<pre><code class="php">
$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
	"action"      => 'add',
	//название документа. Если не указан, то принимается как Название шаблона
	//"title" => "Договор через API",
	//описание
	"description" => "Описание договора",
	//mcid компании, от которой ведется сделка. Не обязательно, если указан did
	"mcid"        => 2,
	//тип документа
	"idtype"      => 46,
	//период действия
	"dateStart"  => "2018-01-01",
	"dateEnd"    => "2018-12-31",
	//id статуса документа
	"status"      => 1,
	//сделка
	"did"         => 921,
	//заказчик
	"clid"        => 1781,
	//плательщик, если отличается от clid
	"payer"       => 1781,
	// login пользователя
	//"user"      => 'marand@omadaru.ru',
	//id шаблона
	"template"    => 14,
	//конвертировать файл в PDF. Если указан шаблон
	"pdf"         => "yes"
]

$urlparams = http_build_query($params);

</code></pre>


**Ответ:**

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

<pre><code class="json">
{
	"result":"Успешно: Создан документ",
	"text":"Документ Договор на рекламу №16-2007 от 20.07.2018.docx обработан",
	"data":344,
	"files":[
		{"name":"Договор на рекламу №16-2007 от 20.07.2018.docx","file":"http://sm2018.crm/files/1532087286.docx"},
		{"name":"Договор на рекламу №16-2007 от 20.07.2018.pdf","file":"http://sm2018.crm/files/1532087286.pdf"}
	]
}
</code></pre>


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

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

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

Запрос позволяет внести изменения в Документ

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

- **id** - идентификатор Документа
- **user** – login пользователя в SalesMan CRM, которому назначается напоминание
- **title** - название документа. Если не указан, то принимается как Название шаблона
- **description** - описание
- **idtype** - тип документа (id из запроса "tips")
- **template** - id шаблона (см. запрос "tips")
- **dateStart** - период действия. начало
- **dateEnd** - период действия. конец
- **status** - id статуса документа (см. запрос "statuses")
- **pdf** - yes, если требуется сгенерировать PDF-файл (дольше)
- **signer** - id подписанта компании
    
> ### Примечание
> 
> если указан параметр templates, то будет произведена перегенерация документа из шаблона. При этом все файлы документа будут удалены


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

<pre><code class="php">
$params = [
	"login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	// указываем метод
	"action"      => 'update',
	"id"          => 276,
	//название документа. Если не указан, то принимается как Название шаблона
	//"title" => "Договор через API",
	//описание
	"description" => "Давно выяснено, что при оценке дизайна и композиции читаемый текст мешает сосредоточиться",
	//тип документа
	"idtype"      => 1,
	//период действия
	"dateStart"   => "2018-08-01",
	"dateEnd"     => "2018-12-31",
	// login пользователя
	//"user"      => 'marand@omadaru.ru',
	//id шаблона
	"template"    => 18,
	//конвертировать файл в PDF. Если указан шаблон
	"pdf"         => "yes"
];

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{
	"result":"Успешно: Данные обновлены",
	"text":"Документ Договор №54-0718/2018 от 01.08.2018.docx обработан",
	"data":276,
	"files":[
		{"name":"Договор №54-0718/2018 от 01.08.2018.docx","file":"http://sm2018.crm/files/1532112460.docx"},
		{"name":"Договор №54-0718/2018 от 01.08.2018.pdf","file":"http://sm2018.crm/files/1532112460.pdf"}
	],
	"number":"54-0718/2018"
}
</code></pre>

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

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

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

Запрос позволяет изменить статус Документа по его id.

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

- **id** – уникальный идентификатор Документа (обязательное поле)
- **status** - новый статус документа
- **description** – комментарий к новому статусу

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

<pre><code class="php">
$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
	"action"      => 'status.change',
	//описание
	"description" => "Давно выяснено, что при оценке дизайна и композиции читаемый текст мешает сосредоточиться",
	"id"          => 276,
	"status"      => '4'
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{"result":"Успешно: Данные обновлены","data":276}
</code></pre>


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

    400 – Не верный API key
    401 – Неизвестный пользователь
    402 – Неизвестный метод
    403 – Не найдено
    500 – Системная ошибка

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

Запрос позволяет удалить Документ по его id.

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

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

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{"result":"Документ удален","data":276}
</code></pre>


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

    400 – Не верный API key
    401 – Неизвестный пользователь
    402 – Неизвестный метод
    403 – Не найдено
    500 – Системная ошибка

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

Позволяет отправить существующий документ в виде документа Word или PDF.

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

- **id** – уникальный идентификатор документа
- **user** – логин Ответственного
- **theme** - тема сообщения, если не указано, то будет установлено "Счет на оплату"
- **content** - тело сообщения, если не указано, то будет использован шаблон по-умолчанию
- **pdf** - если нужно отправить документ в виде PDF (pdf = yes)
- **status** - id статуса документа (см. запрос "[statuses](#statuses)")

> ### Примечание
> 
> - Сначала будет произведен поиск Контактов, прикрепленных к Сделке
> - Если Контакты в сделке не найдены, то будет произведен поиск Основного контакта Клиента
> - Если Контакты не найдены, то отправка будет произведена на Email, указанный в карточке Плательщика по сделке

**Шаблон сообщения:**

<pre><code class="html">
Приветствую, {{person}}

Отправляю Вам Документ "{{docTitle}}" на согласование.

Спасибо за внимание.
С уважением,
{{mName}}
Тел.: {{mPhone}}
Email.: {{mMail}}
==============================
{{mCompany}}

</code></pre>

**Применимые тэги:**

- **{{person}}** - заменяет ИМЯ контакта
- **{{mName}}** - Имя сотрудника
- **{{mPhone}}** - Телефон сотрудника
- **{{mMail}}** - Email сотрудника
- **{{mCompany}}** - Название компании (короткое) из справочника "Мои компании", за которой закреплена сделка
- **{{docTitle}}** - Название документа, включая Тип, Номер и Дата документа (например: Договор на рекламу №22-2007 от 01.01.2018)

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

<pre><code class="php">

$params = [
	"login"   => "vladislav@isaler.ru",
	"apikey"  => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	// указываем метод
	"action"  => 'mail',
	//id документа
	"id"      => 350,
	//id сделки
	"did"     => 921,
	//форма отправки - в оригинале или в виде PDF
	//"pdf"     => "yes",
	//тема сообщения
	//"theme"   => "Документ на согласование",
	//содержание сообщения
	//"content" => "",
	//id шаблона, если документ еще не сгенерирован
	"template"    => 18,
    //id статуса документа
    "status"      => 3
];

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

В поле “**result**“ приходит ответ обработчика, в поле “**data**” приходит id документа

<pre><code class="json">
{
	"result":"Успешно: Сделано",
	"data":350
}
</code></pre>

**В случае ошибки:**

<pre><code class="json">
{
	"result":"Error",
	"data":350,
	"error":{
		"code":"407",
		"text":"Не найден ни один получатель"
	}
}
</code></pre>

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

    400 – Не верный API key
    401 – Неизвестный пользователь
    402 – Неизвестный метод
    404 – Не найдено
	406 - Нечего отправлять. Попробуйте указать id шаблона
    407 – Не найден ни один получатель