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

Метод “document”

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

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

Запрос “tips”

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

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


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

$urlparams = http_build_query($params);

Ответ:

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


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

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

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

Запрос “statuses”

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

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


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

$urlparams = http_build_query($params);

Ответ:

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


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

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

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

Запрос “info”

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

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

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

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


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

$urlparams = http_build_query($params);

Ответ:

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

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



{
    "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",
        "status":"1",
        "statusTitle":"Создан",
        "files":[
            {
                "name":"Дополнительное соглашение №32 от 06.07.2018.docx",
                "file":"http://sm2018.crm/files/1530865531.docx"
            }
        ]
    }
}

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

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 – фильтр по названию, описанию или номеру документа
idtype - по типу документа, список idtype (id из запроса tips) через запятую
clid - фильтр по Клиенту
did - фильтр по Сделке

Примечание

Если не указан 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',
    // фильтр по названию, описанию или номеру документа
    "word"      => '',
    // по типу документа, список idtype (id из запроса tips) через запятую
    "idtype"    => 47,
    //фильтр по клиенту
    "clid"      => 0,
    //фильтр по сделке
    "did"       => 784
]

$urlparams = http_build_query($params);

Ответ:


{
    "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",
            "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",
            "status":"1",
            "statusTitle":"Создан",
            "statusColor":"#9edae5"
        }
    ],
    "count":"2"
}

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

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

Запрос “add”

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

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

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

Примечание

при пустом поле user Ответственным будет назначен текущий пользователь (из запроса)

если указан did сделки, то параметры clid и payer игнорируются

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

Ответ:

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


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

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

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

Запрос “update”

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

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

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

Примечание

если указан параметр templates, то будет произведена перегенерация документа из шаблона. При этом все файлы документа будут удалены

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

Ответ:


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

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

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

Запрос “status.change”

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

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

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

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


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

$urlparams = http_build_query($params);

Ответ:


{"result":"Успешно: Данные обновлены","data":276}

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

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

Запрос “delete”

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

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

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

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


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

$urlparams = http_build_query($params);

Ответ:


{"result":"Документ удален","data":276}

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

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

Запрос “mail”

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

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

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

Примечание

Сначала будет произведен поиск Контактов, прикрепленных к Сделке

Если Контакты в сделке не найдены, то будет произведен поиск Основного контакта Клиента

Если Контакты не найдены, то отправка будет произведена на Email, указанный в карточке Плательщика по сделке

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


Приветствую, {{person}}

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

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

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

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

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



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

Ответ:

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


{
    "result":"Успешно: Сделано",
    "data":350
}

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


{
    "result":"Error",
    "data":350,
    "error":{
        "code":"407",
        "text":"Не найден ни один получатель"
    }
}

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

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