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

Метод “task”

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

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

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

  • tid – уникальный идентификатор напоминания (в запросах идет как id)
  • active – признак активности напоминания (yes - активно или no - выполнено)
  • priority – важность (1 – не важно, 0 – нормально*, 2 – важно)
  • speed – срочность (1 – не срочно, 0 – нормально*, 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 в ответе означает принадлежность активности:

  1. all - относится и к Напоминаниям и к Истории активностей
  2. activ - относится только к Истории активностей
  3. 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: Поставка телефонов"
    }
}

Примечание:

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

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

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 - фильтр по Сделке

Примечание:

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

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


$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 сделки

Примечание:

  1. при пустом поле user Ответственным будет назначен текущий пользователь (из запроса)
  2. уведомление будет отправлено пользователю в зависимости от его настроек
  3. следующие параметры передаются в явном, текстовом виде:
    • 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 - тип события для внесения в Историю активностей. Если не указано, будет взято из напоминания

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


$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 напоминания