# Акты (akt)

## Метод “akt”

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

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

<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":"Акт сервисный"
			}
		},
		{
			"id":"3",
			"title":"Отправлен клиенту (электронно)",
			"color":"#008000",
			"type":{
				"2":"Акт приема-передачи",
				"9":"Акт сервисный"
			}
		},
		...
	]
}
</code></pre>


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

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


<a id="templates"></a>
### Запрос “templates” <sup>Новое</sup>

Запрос позволяет получить список шаблонов Актов.

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

- **id** - идентификатор шаблона
- **title** - название шаблона
- **file** - файл шаблона
- **typeid** - идентификатор типа документа ( templateTypeID )

<pre><code class="json">
{ 
	"data" : [
		{ "id" : "99", "title" : "Приёма-передачи. Права", "file" : "akt_prava.tpl", "typeid" : "2" },
		{ "id" : "98", "title" : "Приёма-передачи. Услуги", "file" : "akt_simple.tpl", "typeid" : "2" },
		{ "id" : "97", "title" : "Приёма-передачи. Услуги (расширенный)", "file" : "akt_full.tpl", "typeid" : "2" }, 
		{ "id" : "144", "title" : "Тестовый", "file" : "ACT5c90d48a266a3_akt.tpl", "typeid" : "2" }
	] 
}
</code></pre>


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

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



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

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

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

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

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

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

- **datum** - Дата создания Акта
- **number** - номер Акта
- **title** - Название Акта
- **description** - описание Акта
- **template** - шаблон Акта
- **templateId** - ID шаблона Акта
- **templateTitle** - название шаблона Акта
- **templateTypeID** - ID типа документа
- **mcid** - id Компании, от которой ведется сделка
- **signer** - id подписанта компании
- **status** - id статуса документа
- **statusTitle** - расшифровка статуса
- **crid** - идентификатор счета, если Сделка является сервисной
- **positions** - список позиций, прикрепленных к акту ( частичная отгрузка )
	- **id**   - id позиции
	- **spid** - id позиции спецификации
	- **prid** - id позиции прайса
	- **kol**  - количество

<pre><code class="json">
{
	"data":{
		"deid":"330",
		"datum":"29.06.2018",
		"number":"60",
		"title":"Акт приема-передачи",
		"description":"Создан документ",
		"template":"akt_full.tpl",
		"templateTitle":"Акт приема-передачи (расширенный). Услуги",
		"templateTypeID":"2",
		"clid":"1835",
		"clientTitle":"911site.ru",
		"payer":"1835",
		"payerTitle":"911site.ru",
		"did":"913",
		"dealTitle":"СД4261: 911site.ru",
		"mcid":"3",
		"signer":"1",
		"status":"1",
		"statusTitle":"Создан"
	}
}
</code></pre>

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

    400 – Не верный API key
    401 – Неизвестный пользователь
    402 – Неизвестный метод
    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** – фильтр по описанию или номеру документа
- **clid** - фильтр по Клиенту
- **did** - фильтр по Сделке

> ### Примечание
>
> Если не указан **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" => '2017-01-01',
	"dateEnd"   => '2018-08-31',
	// фильтр по описанию или номеру документа
	"word"      => '',
	//фильтр по клиенту
	//"clid"    => 1781,
	//фильтр по сделке
	//"did"     => 913
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{
	"data":[
		{
			"id":"330",
			"datum":"29.06.2018",
			"number":"60",
			"template":"Акт приема-передачи (расширенный). Услуги",
			"clid":"1835",
			"client":"911site.ru",
			"did":"913",
			"deal":"СД4261: 911site.ru",
			"payerid":"1835",
			"payer":"911site.ru",
			"mcid":"3",
			"signer":"1",
			"status":"1",
			"statusTitle":"Создан",
			"statusColor":"#9edae5"
		},
		{
			"id":"322",
			"datum":"22.05.2018",
			"number":"59",
			"template":"Акт приема-передачи (расширенный). Услуги",
			"clid":"1372",
			"client":"Уральская инвестиционно-строительная компания, ООО",
			"did":"548",
			"deal":"Внедрение",
			"payerid":"1372",
			"payer":"Уральская инвестиционно-строительная компания, ООО",
			"mcid":"2",
			"signer":"2",
			"status":"1",
			"statusTitle":"Создан",
			"statusColor":"#9edae5"
		},
		...
	],
	"count":"10"
}
</code></pre>

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

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


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

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

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

- **number** - номер документа. Если не указан, то генерируется автоматически
- **user** – логин Ответственного
- **date** - дата акта
- **description** - описание
- **signer** - id подписанта
- **template** - файл шаблона (см. запрос "templates") или
- **templateID** - ID шаблона (см. запрос "templates")
- **status** - id статуса документа (см. запрос "statuses")
- **did** - ID сделки
- **speka** - массив позиций спецификации для акта ( частичная отгрузка ) [ см. [Сделка](https://salesman.pro/api2/deal#info) ] -> speka
	- **spid** - id позиции спецификации
	- **kol** - количество ( возможно частичное )

**Шаблоны актов:**

- **simple** - Акт приема-передачи. Услуги
- **full** - Акт приема-передачи (расширенный). Услуги
- **prava** - Акт приема-передачи. Права


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

<pre><code class="php">
$params = [
	"login"       => "vladislav@isaler.ru",
	"apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	// указываем метод
	"action"      => 'add',
	//номер акта, если не указано - будет сгенерирова по порядку
	"number"      => '',
	//дата акта
	"date"        => "2018-07-01",
	// шаблон Акта: имя файла или ID шаблона
	"template"    => "akt_full.tpl",
	"templateID"  => "97",
	//описание
	"description" => "Это текст - описание к акту",
	// id статуса документа
	"status"      => 1,
	// сделка
	"did"         => 918,
	// позиции спецификации ( частичная отгрузка )
	"speka" => [
		[
			"spid" => 345,
			"kol"  => 25
		],
		[
			"spid" => 346,
			"kol"  => 10
		]
	]
];

$urlparams = http_build_query($params);

</code></pre>


**Ответ:**

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

<pre><code class="json">
{
	"result":"Успешно",
	"data":{
		"id":362,
		"number":"71",
		"did":913
	}
}
</code></pre>


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

    400 – Не верный API key
    401 – Неизвестный пользователь
    402 – Неизвестный метод
    405 – Отсутствуют параметры
	408 - Акт уже добавлен к сделке (кроме сервисных сделок)
	409 - Минимальный этап для акта - ХХХ%

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

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

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

- **id** - идентификатор Акта
- **date** - дата акта
- **signer** - id подписанта
- **template** - файл шаблона (см. запрос "templates") или
- **templateID** - ID шаблона (см. запрос "templates")
- **description** - описание
- **status** - id статуса документа (см. запрос "statuses")
- **speka** - массив позиций спецификации для акта ( частичная отгрузка ) [ см. [Сделка](https://salesman.pro/api2/deal#info) ] -> speka
	- **spid** - id позиции спецификации
	- **kol** - количество ( возможно частичное )

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

<pre><code class="php">
$params = [
	"login"       => "vladislav@isaler.ru",
	"apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	// указываем метод
	"action"      => 'update',
	//дата акта
	"date"        => "2018-07-01",
	// шаблон Акта: имя файла или ID шаблона
	"template"    => "akt_full.tpl",
	"templateID"  => "97",
	//описание
	"description" => "Это текст - описание к акту",
	// позиции спецификации ( частичная отгрузка )
	"speka" => [
		[
			"spid" => 345,
			"kol"  => 25
		],
		[
			"spid" => 346,
			"kol"  => 10
		]
	]
];

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{"result":"Успешно","data":{"id":279,"number":"57","did":"920"}}
</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”

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

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

- **id** – уникальный идентификатор счета
- **invoice** - номер счета
- **user** – логин Ответственного
- **theme** - тема сообщения, если не указано, то будет установлено "Счет на оплату"
- **content** - тело сообщения, если не указано, то будет использован шаблон по-умолчанию
- **status** - id статуса документа (см. запрос "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"     => 362,
	//тема сообщения
	//"theme"   => "Документ на согласование",
	//содержание сообщения
	//"content" => "",
	//id статуса документа
	"status"      => 3
];

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

В поле “result“ приходит ответ обработчика, в поле “data” приходит расширенный отчет обработки

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

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

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

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

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

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

Запрос позволяет получить содержимое Акта в виде HTML

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

- **number** - номер Акта
- **id** - идентификатор записи (если номер не уникален или не указан)
- **nosignat** - если равен "yes", то в ответе не будет изображения печати

Наличие параметра "number" ИЛИ "id" обязательно для поиска счета в базе. Получить список счетов с "id" и "number" можно с помощью метода **list**

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

<pre><code class="php">

$params = [
	"login"      => "vladislav@isaler.ru",
	"apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	// указываем метод
	"action"     => 'invoice.html',
	//id счета
	"id"         => 925,
	//исключение печати из вывода
	//"nosignat" => "yes",
	//номер счета
	"invoice"    => "158",
];

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

- в поле “html“ приходит ответ HTML,
- в поле “id” приходит id акта,
- в поле "number" приходит номер акта


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

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

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

Запрос позволяет получить ссылку на счет в виде PDF

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

- **invoice** - номер счета
- **id** - идентификатор записи счета (если номер не уникален или не указан)
- **nosignat** - если равен "yes", то в ответе не будет изображения печати

Наличие параметра "invoice" ИЛИ "id" обязательно для поиска счета в базе. Получить список счетов с "id" и "invoice" можно с помощью метода **info**

> ### Примечание
>
> если файл не существует, то он будет сгенерирован (требуется больше времени на обработку). Поэтому в cURL запросе следует установить повышенное время ожидания ответа (подбирается опытным путем, но >=20)

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

<pre><code class="php">

$params = [
	"login"      => "vladislav@isaler.ru",
	"apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
	// указываем метод
	"action"     => 'invoice.html',
	//id счета
	"id"         => 925,
	//исключение печати из вывода
	//"nosignat" => "yes",
	//номер счета
	"invoice"    => "158",
];

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

- в поле “url“ приходит URL pdf-файла (слэши экранированы),
- в поле “id” приходит id акта,
- в поле "number" приходит номер акта

<pre><code class="json">
{
	"url":"http://sm2018.crm/files/akt_57.pdf",
	"id":"315",
	"number":"57"
}
</code></pre>

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

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