VK.com Github Youtube

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

Метод “document”

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

URL для вызова:

http(s)://{{baseurl}}/developer/v3/document/запрос?параметр=значение

Пример ошибки:

{
    "result": "Error",
    "error": {
        "code": 404,
        "text": "Документ не найден"
    }
}

Запрос “tips”

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

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

GET http://{{baseurl}}/developer/v3/document/tips
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

Ответ:

  • id - идентификатор типа документа (idtype)
  • type - название типа документа
  • role - список ролей сотрудников, которым доступно создание документа конкретного типа
  • users - идентификаторы сотрудников, которым доступно создание документа конкретного типа
  • number - крайний номер документа
  • format - формат, по которому генерируется номер документа
  • templates - массив шаблонов
    • id - id шаблона
    • title - название шаблона
    • file - файл шаблона
{
    "data": [
        {
            "id": 1,
            "title": "Договор",
            "type": "Договор",
            "role": "Руководитель с доступом,Руководитель подразделения,Руководитель отдела,Менеджер продаж",
            "users": "",
            "number": "62",
            "format": "{cnum}-{MM}{YY}\/{YYYY}",
            "templates": [
                {
                    "id": 4,
                    "title": "Договор на услуги",
                    "file": "tbs_dogovor_uslygi.docx"
                },
                {
                    "id": 15,
                    "title": "Тестовый 200",
                    "file": "work._dogovor_na_razrabotky,_postoplata.docx"
                },
                {
                    "id": 18,
                    "title": "Договор. Услуги (обслуживание)",
                    "file": "tbs_dogovor_na_obslyjivanie.docx"
                },
                {
                    "id": 19,
                    "title": "Договор. Услуги (+ график платежей)",
                    "file": "tbs_dogovor_uslygi_with_invoices.docx"
                },
                {
                    "id": 27,
                    "title": "Договор на внедрение",
                    "file": "bs_dogovor_na_vnedrenie.docx"
                },
                {
                    "id": 28,
                    "title": "Док с подписью",
                    "file": "tbs_dogovor_uslygi_with_customsignature.docx"
                },
                {
                    "id": 150,
                    "title": "Договор с подписью",
                    "file": "bs_dogovor_na_po.docx"
                },
                {
                    "id": 160,
                    "title": "555",
                    "file": "tehnicheskoe_zadanie_proekti_v3.docx"
                }
            ]
        },
        {
            "id": 47,
            "title": "Дополнительное соглашение",
            "type": "Собственный",
            "role": "",
            "users": "",
            "number": "52",
            "format": "{cnum}",
            "templates": [
                {
                    "id": 20,
                    "title": "Документ TBS",
                    "file": "tbs_dogovor_uslygi.docx"
                },
                {
                    "id": 21,
                    "title": "Документ TBS с графиком",
                    "file": "tbs_dogovor_uslygi_with_invoices.docx"
                },
                {
                    "id": 25,
                    "title": "Здоровый мир",
                    "file": "tmp_hw.docx"
                },
                {
                    "id": 158,
                    "title": "Тэги из каталога",
                    "file": "tbs_dogovor_catalog_tags.docx"
                },
                {
                    "id": 159,
                    "title": "Тэги КакЧасы",
                    "file": "example.docx"
                }
            ]
        },
        {
            "id": 4,
            "title": "Ком.предложение",
            "type": "Собственный",
            "role": "Руководитель подразделения,Руководитель отдела,Менеджер продаж,Поддержка продаж",
            "users": "",
            "number": "51",
            "format": "{cnum}",
            "templates": []
        },
        {
            "id": 6,
            "title": "Холодное предложение",
            "type": "Собственный",
            "role": "",
            "users": "",
            "number": "0",
            "format": "",
            "templates": []
        }
    ]
}

Запрос “statuses”

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

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

GET http://{{baseurl}}/developer/v3/document/statuses
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

Ответ:

  • id - идентификатор статуса
  • title - название статуса
  • color - цветовая схема статуса
  • type - массив, содержащий типы документов, к которым применяется статус (idtype => Название)
{
    "data": [
        {
            "id": 1,
            "title": "Создан",
            "color": "#9edae5",
            "type": 1
        },
        {
            "id": 3,
            "title": "Отправлен клиенту (электронно)",
            "color": "#008000",
            "type": 1
        },
        {
            "id": 4,
            "title": "Распечатан",
            "color": "#95b3d7",
            "type": 1
        },
        {
            "id": 5,
            "title": "Отправлен клиенту (оригиналы)",
            "color": "#548dd4",
            "type": 1
        },
        {
            "id": 6,
            "title": "Получен от клиента (оригиналы)",
            "color": "#ff6600",
            "type": 1
        },
        {
            "id": 7,
            "title": "В архиве",
            "color": "#999999",
            "type": 1
        }
    ]
}

Запрос “info”

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

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

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

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

GET http://{{baseurl}}/developer/v3/document/info
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "number": "62-0524/2024",
    "id": 0
}

Ответ:

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

  • datum - Дата создания документа
  • typeDoc - Тип документа (title из запроса tips)
  • idtype - ID типа документа (id из запроса tips)
  • description - описание Документа
  • mcid - id Компании, от которой ведется сделка
  • signer - id подписанта
  • status - id статуса документа
  • statusTitle - расшифровка статуса
  • files - массив файлов, вложенных в документ
{
    "data": {
        "deid": 534,
        "datum": "2024-05-31 21:22:57",
        "number": "62-0524\/2024",
        "title": "Договор",
        "date.start": "2024-05-31",
        "date.end": "2025-06-01",
        "typeDoc": "Договор на услуги",
        "idtype": 1,
        "description": "",
        "clid": 1781,
        "clientTitle": "Сейлзмен Рус",
        "payer": 1781,
        "payerTitle": "Сейлзмен Рус",
        "did": 972,
        "dealTitle": "СД4320: Новая сделка",
        "mcid": 3,
        "signer": 0,
        "status": 1,
        "statusTitle": "Создан",
        "files": [
            {
                "name": "Договор №62-0524\/2024 от 31.05.2024.docx",
                "file": "http:\/\/sm2021.crm\/files\/1717143850.docx"
            }
        ]
    }
}

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

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 - фильтр по Сделке
  • signer - id подписанта

Примечание

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

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

GET http://{{baseurl}}/developer/v3/document/list
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "clid": 1839
}

Ответ:

{
    "data": [
        {
            "id": 500,
            "datum": "21.12.2022",
            "date.start": "21.12.2022",
            "date.end": "31.12.2022",
            "number": "19",
            "title": "Счет-фактура",
            "clid": 1839,
            "client": "Саморезы Сибири, ООО",
            "did": 787,
            "deal": "A26: Продажа для Саморезы",
            "payerid": 1839,
            "payer": "Саморезы Сибири, ООО",
            "mcid": 0,
            "signer": 0,
            "idtype": 91,
            "typeDoc": "Счет-фактура",
            "status": "0",
            "statusTitle": "--",
            "statusColor": "#fff"
        }
    ],
    "count": 1
}

Запрос “add”

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

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

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

Примечание

  1. при пустом поле user Ответственным будет назначен текущий пользователь (из запроса)
  2. если указан did сделки, то параметры clid и payer игнорируются

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

POST http://{{baseurl}}/developer/v3/document/add
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "did": 962,
    "dateStart": "2024-07-01",
    "dateEnd": "2024-12-31",
    "description": "Описание договора",
    "mcid": 1,
    "idtype": 1,
    "template": 19,
    "status": 1
}

Ответ:

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

{
    "result": "Успешно: Создан документ",
    "text": "Документ  №63-0624\/2024 от 01.07.2024.docx обработан",
    "data": 536,
    "files": [
        {
            "name": "№63-0624\/2024 от 01.07.2024.docx",
            "file": "http:\/\/sm2021.crm\/files\/1719399088.docx"
        }
    ],
    "number": "63-0624\/2024"
}

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

405 – Отсутствуют параметры

Запрос “update”

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

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

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

Примечание

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

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

POST http://{{baseurl}}/developer/v3/document/update
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "id": 536,
    "title": "Договор через API",
    "description": "Давно выяснено, что при оценке дизайна и композиции читаемый текст мешает сосредоточиться. Lorem Ipsum используют потому, что тот обеспечивает более или менее стандартное заполнение шаблона",
    "dateStart": "2024-07-02",
    "dateEnd": "2024-09-31",
    "mcid": 2,
    "idtype": 1,
    "template": 28,
    "status": 1
}

Ответ:

{
    "result": "Успешно: Данные обновлены",
    "text": "Документ Договор через API №63-0624\/2024 от 02.07.2024.docx обработан",
    "data": 536,
    "files": [
        {
            "name": "Договор через API №63-0624\/2024 от 02.07.2024.docx",
            "file": "http:\/\/sm2021.crm\/files\/1719400995.docx"
        }
    ],
    "number": "63-0624\/2024"
}

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

404 – Не найдено
405 – Отсутствуют параметры - id документа

Запрос “status.change”

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

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

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

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

POST http://{{baseurl}}/developer/v3/document/status.change
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "id": 536,
    "description": "Давно выяснено, что при оценке дизайна и композиции читаемый текст мешает сосредоточиться",
    "status": 3
}

Ответ:

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

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

404 – Не найдено
500 – Системная ошибка

Запрос “mail”

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

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

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

Примечание

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

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

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

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

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

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

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

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

POST http://{{baseurl}}/developer/v3/document/mail
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "id": 536,
    "status": 5
}

Ответ:

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

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

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

404 – Не найдено
406 - Нечего отправлять. Попробуйте указать id шаблона
407 – Не найден ни один получатель

Запрос “delete”

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

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

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

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

POST http://{{baseurl}}/developer/v3/document/delete
Content-Type: application/json
apikey: {{token}}
login: vladislav@isaler.ru

{
    "id": 536
}

Ответ:

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

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

404 – Не найдено
500 – Системная ошибка