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

Метод “task”

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

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

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

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

Запрос “fields”

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

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

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "fields"
]

$urlparams = http_build_query($params);

Ответ:


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

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

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

Запрос “tips”

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

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


$params = [
    "login"  => "vladislav@isaler.ru",
    "apikey" => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    "action" => "tips"
]

$urlparams = http_build_query($params);

Ответ:

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

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


{
    "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"}
    ]
}

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

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

Запрос “info”

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

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

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

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


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

$urlparams = http_build_query($params);

Ответ:


{
    "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: Поставка телефонов"
    }
}

Примечание:

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

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

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

Запрос “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-не успешно)

Примечание:

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

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


$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);

Ответ:

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

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

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

Запрос “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 сделки

Примечание:

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

Пример формирования запроса в 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);

Ответ:

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

{"result":"Успешно","data":3349}

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

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

Запрос “update”

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

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

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

Пример формирования запроса в 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);

Ответ:

{"result":"Успешно","data":3349}

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

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

Запрос “doit”

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

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

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

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


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

$urlparams = http_build_query($params);

Ответ:


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

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

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

Запрос “delete”

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

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

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

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


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

$urlparams = http_build_query($params);

Ответ:

{"result":"Успешно","data":"3350","message":"Запись удалена"}

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

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