# Напоминания (task)

## Метод “task”

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

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

Специфичные признаки, используемые далее:

- **tid** – уникальный идентификатор напоминания (в запросах идет как **id**)
- **active** – признак активности напоминания (yes - активно или no - выполнено)
- **priority** – важность (1 – не важно, 0 – нормально*, 2 – важно)
- **speed** – срочность (1 – не срочно, 0 – нормально*, 2 – срочно)
- **status** – статус выполнения (1-успешно, 2-не успешно)

<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":{
		"tid":"Идентификатор напоминания",
		"title":"Тема","des":"Агенда",
		"tip":"Тип напоминания",
		"active":"Признак: выполнено,активно",
		"priority":"Важность",
		"spees":"Срочность",
		"iduser":"Ответственный",
		"autor":"Автор напоминания",
		"clid":"ID клиента",
		"pid":"ID контакта",
		"did":"ID сделки"
	}
}
</code></pre>


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

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

<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>

**Ответ:**

Парметр **filter** в ответе означает принадлежность активности:

1. **all** - относится и к Напоминаниям и к Истории активностей
2. **activ** - относится только к Истории активностей
3. **task** - относится только к Напоминаниям

<pre><code class="json">
{
	"data":[
		{"title":"Первичный звонок","color":"#009900","filter":"all"},
		{"title":"Факс","color":"#cc00cc","filter":"activ"},
		{"title":"Встреча","color":"#ffcc00","filter":"all"},
		{"title":"Задача","color":"#ff6600","filter":"all"},
		{"title":"Предложение","color":"#66ccff","filter":"activ"},
		{"title":"Событие","color":"#666699","filter":"activ"},
		{"title":"исх.Почта","color":"#cccc00","filter":"all"},
		{"title":"вх.Звонок","color":"#99cc00","filter":"all"},
		{"title":"вх.Почта","color":"#cc3300","filter":"all"},
		{"title":"Поздравление","color":"#009999","filter":"task"},
		{"title":"исх.2.Звонок","color":"#339966","filter":"all"},
		{"title":"Отправка КП","color":"#ff0000","filter":"all"},
		{"title":"Исходящий звонок КЦ","color":"#3498DB","filter":"activ"},
		{"title":"+ Сделка","color":"#339966","filter":"all"},
		{"title":"Вакансия","color":"#c67c00","filter":"all"},
		{"title":"Холодный звонок","color":"#99ccff","filter":"activ"}
	]
}
</code></pre>


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

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

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

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

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

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

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{
	"data":{
		"tid":"3222",
		"datum":"2018-03-02",
		"totime":"13:30",
		"title":"Работы по проекту Установка и настройка программного аппарата",
		"des":"Lorem Ipsum - это текст-рыба, часто используемый в печати и вэб-дизайне",
		"tip":"Задача",
		"active":"yes",
		"priority":"0",
		"speed":"0",
		"iduser":"1",
		"user":"vladislav@isaler.ru",
		"autor":"0",
		"autorlogin":"",
		"clid":"1781",
		"client":"Сейлзмен Рус",
		"person":[
			{"pid":"2723","person":"Ларшин Олег"},
			{"pid":"2513","person":"Васильев Дмитрий"},
			{"pid":"2475","person":"Андреев Владислав Германович"}
		],
		"did":"784",
		"dogovor":"A25: Поставка телефонов"
	}
}
</code></pre>

**Примечание:**

1. Если в ответе autor = 0, то автором является сам ответственный
2. Контакты возвращаются в виде массива


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

    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** – слово поиска по полям title, des, tip
- **tip** – поиск по определенному типу напоминания (title в ответе запроса tips)
- **active** - фильтр по статусу выполнения: yes - активное, no - выполненное
- **clid** - фильтр по Клиенту
- **did** - фильтр по Сделке
- **status** - фильтр по статусу выполнения (1-успешно, 2-не успешно)

**Примечание:**

1. По умолчанию выводятся напоминания на текущий день
2. Если не указан **user**, то будут выведены записи текущего пользователя и всех подчиненных
2. Если указан статус выполнения **status**, то будут выведены записи только выполненных напоминаний

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

<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',
	// фильтр по полям title, des, tip
	"word"      => '',
	//фильтр по статусу выполнения: yes - активное, no - выполненное
	"active"    => 'yes',
	//фильтр по клиенту
	"clid"      => 0,
	//фильтр по сделке
	"did"       => 784,
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

- Ответ аналогичен запросу **info**

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

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


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

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

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

- **user** – login пользователя в SalesMan CRM, которому назначается напоминание
- **datum** => Дата в формате YYYY-MM-DD (по умолчанию текущая дата)
- **totime** => Время в формате H:i (по умолчанию текущее время + 1 час)
- **title** => Тема
- **des** => Агенда
- **tip** => Тип напоминания
- **priority** => Важность
- **speed** => Срочность
- **autor** => логин Автора напоминания (по умолчанию текущий пользователь)
- **clid** => ID клиента
- **pid** => ID контакта
- **did** => ID сделки

**Примечание:**

1. при пустом поле **user** Ответственным будет назначен текущий пользователь (из запроса)
2. уведомление будет отправлено пользователю в зависимости от его настроек
3. следующие параметры передаются в явном, текстовом виде:
   - **tip** – Тип напоминания
   - В случае отсутствия переданных значений в справочниках будут созданы новые записи типа Активности

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

<pre><code class="php">
$params = [
    "login"    => "vladislav@isaler.ru",
    "apikey"   => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action"   => 'add',
	// login пользователя
	"user"     => 'marand@omadaru.ru',
	"datum"    => '2018-08-11',
	"totime"   => '15:30',
	"title"    => 'Перезвонить клиенту с сайта',
	"des"      => 'Это описание',
	"tip"      => 'Задача',
	"priority" => '2',
	"speed"    => '0',
	"clid"     => '1781',
	"pid"      => '2475,2723',
	"did"      => '784',
]

$urlparams = http_build_query($params);

</code></pre>


**Ответ:**

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

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


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

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

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

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

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

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

<pre><code class="php">
$params = [
    "login"    => "vladislav@isaler.ru",
    "apikey"   => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action"   => 'update',
	"id"       => 3349,
	// login пользователя
	"user"     => 'marand@omadaru.ru',
	"datum"    => '2018-08-15',
	"totime"   => '16:30',
	"title"    => 'Перезвонить клиенту по счету',
	"des"      => 'Это описание 2',
	"tip"      => 'Задача',
	"priority" => '2',
	"speed"    => '2',
	"clid"     => '1781',
	"pid"      => '2475,2723',
	"did"      => '784',
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

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


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

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

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

Запрос позволяет отметить напоминание выполненным по его id. При этом можно зафиксировать результат выполнения.

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

- **id** – уникальный идентификатор контакта (обязательное поле)
- **description** – результат выполнения напоминания
- **tip** - тип события для внесения в Историю активностей. Если не указано, будет взято из напоминания
- **status** – статус выполнения (1-успешно,2-не успешно)

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

<pre><code class="php">
$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action"      => 'doit',
	"id"          => 3349,
	"description" => 'Я перезвонил клиенту. Круто-чо!',
	"tip"         => 'Исх.звонок'
]

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">
{
	"result":"Успешно",
	"data":"3349",
	"message":"Добавлена Активность\nОтправлено сотруднику Андреев Владислав",
	"historyID":17944
}
</code></pre>


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

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

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

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

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

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

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

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

$urlparams = http_build_query($params);

</code></pre>

**Ответ:**

<pre><code class="json">{"result":"Успешно","data":"3350","message":"Запись удалена"}</code></pre>


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

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