Facebook Google Plus Youtube

Акты (akt)

Метод “akt”

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

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

Запрос “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":"Акт сервисный"
            }
        },
        {
            "id":"3",
            "title":"Отправлен клиенту (электронно)",
            "color":"#008000",
            "type":{
                "2":"Акт приема-передачи",
                "9":"Акт сервисный"
            }
        },
        ...
    ]
}

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

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

Запрос “templates” Новое

Запрос позволяет получить список шаблонов Актов.

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


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

$urlparams = http_build_query($params);

Ответ:

  • id - идентификатор шаблона
  • title - название шаблона
  • file - файл шаблона
  • typeid - идентификатор типа документа ( templateTypeID )

{ 
    "data" : [
        { "id" : "99", "title" : "Приёма-передачи. Права", "file" : "akt_prava.tpl", "typeid" : "2" },
        { "id" : "98", "title" : "Приёма-передачи. Услуги", "file" : "akt_simple.tpl", "typeid" : "2" },
        { "id" : "97", "title" : "Приёма-передачи. Услуги (расширенный)", "file" : "akt_full.tpl", "typeid" : "2" }, 
        { "id" : "144", "title" : "Тестовый", "file" : "ACT5c90d48a266a3_akt.tpl", "typeid" : "2" }
    ] 
}

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

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

Запрос “info”

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

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

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

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


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

$urlparams = http_build_query($params);

Ответ:

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

  • datum - Дата создания Акта
  • number - номер Акта
  • title - Название Акта
  • description - описание Акта
  • template - шаблон Акта
  • templateId - ID шаблона Акта
  • templateTitle - название шаблона Акта
  • templateTypeID - ID типа документа
  • mcid - id Компании, от которой ведется сделка
  • status - id статуса документа
  • statusTitle - расшифровка статуса
  • crid - идентификатор счета, если Сделка является сервисной
  • positions - список позиций, прикрепленных к акту ( частичная отгрузка )
    • id - id позиции
    • spid - id позиции спецификации
    • prid - id позиции прайса
    • kol - количество

{
    "data":{
        "deid":"330",
        "datum":"29.06.2018",
        "number":"60",
        "title":"Акт приема-передачи",
        "description":"Создан документ",
        "template":"akt_full.tpl",
        "templateTitle":"Акт приема-передачи (расширенный). Услуги",
        "templateTypeID":"2",
        "clid":"1835",
        "clientTitle":"911site.ru",
        "payer":"1835",
        "payerTitle":"911site.ru",
        "did":"913",
        "dealTitle":"СД4261: 911site.ru",
        "mcid":"3",
        "status":"1",
        "statusTitle":"Создан"
    }
}

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

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
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 – фильтр по описанию или номеру документа
  • 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" => '2017-01-01',
    "dateEnd"   => '2018-08-31',
    // фильтр по описанию или номеру документа
    "word"      => '',
    //фильтр по клиенту
    //"clid"    => 1781,
    //фильтр по сделке
    //"did"     => 913
]

$urlparams = http_build_query($params);

Ответ:


{
    "data":[
        {
            "id":"330",
            "datum":"29.06.2018",
            "number":"60",
            "template":"Акт приема-передачи (расширенный). Услуги",
            "clid":"1835",
            "client":"911site.ru",
            "did":"913",
            "deal":"СД4261: 911site.ru",
            "payerid":"1835",
            "payer":"911site.ru",
            "mcid":"3",
            "status":"1",
            "statusTitle":"Создан",
            "statusColor":"#9edae5"
        },
        {
            "id":"322",
            "datum":"22.05.2018",
            "number":"59",
            "template":"Акт приема-передачи (расширенный). Услуги",
            "clid":"1372",
            "client":"Уральская инвестиционно-строительная компания, ООО",
            "did":"548",
            "deal":"Внедрение",
            "payerid":"1372",
            "payer":"Уральская инвестиционно-строительная компания, ООО",
            "mcid":"2",
            "status":"1",
            "statusTitle":"Создан",
            "statusColor":"#9edae5"
        },
        ...
    ],
    "count":"10"
}

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

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

Запрос “add”

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

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

  • number - номер документа. Если не указан, то генерируется автоматически
  • user – логин Ответственного
  • date - дата акта
  • description - описание
  • template - файл шаблона (см. запрос "templates") или
  • templateID - ID шаблона (см. запрос "templates")
  • status - id статуса документа (см. запрос "statuses")
  • did - ID сделки
  • speka - массив позиций спецификации для акта ( частичная отгрузка ) [ см. Сделка ] -> speka
    • spid - id позиции спецификации
    • kol - количество ( возможно частичное )

Шаблоны актов:

  • simple - Акт приема-передачи. Услуги
  • full - Акт приема-передачи (расширенный). Услуги
  • prava - Акт приема-передачи. Права

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


$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"      => 'add',
    //номер акта, если не указано - будет сгенерирова по порядку
    "number"      => '',
    //дата акта
    "date"        => "2018-07-01",
    // шаблон Акта: имя файла или ID шаблона
    "template"    => "akt_full.tpl",
    "templateID"  => "97",
    //описание
    "description" => "Это текст - описание к акту",
    // id статуса документа
    "status"      => 1,
    // сделка
    "did"         => 918,
    // позиции спецификации ( частичная отгрузка )
    "speka" => [
        [
            "spid" => 345,
            "kol"  => 25
        ],
        [
            "spid" => 346,
            "kol"  => 10
        ]
    ]
];

$urlparams = http_build_query($params);

Ответ:

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


{
    "result":"Успешно",
    "data":{
        "id":362,
        "number":"71",
        "did":913
    }
}

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

400 – Не верный API key
401 – Неизвестный пользователь
402 – Неизвестный метод
405 – Отсутствуют параметры
408 - Акт уже добавлен к сделке (кроме сервисных сделок)
409 - Минимальный этап для акта - ХХХ%

Запрос “update”

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

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

  • id - идентификатор Акта
  • date - дата акта
  • template - файл шаблона (см. запрос "templates") или
  • templateID - ID шаблона (см. запрос "templates")
  • description - описание
  • status - id статуса документа (см. запрос "statuses")
  • speka - массив позиций спецификации для акта ( частичная отгрузка ) [ см. Сделка ] -> speka
    • spid - id позиции спецификации
    • kol - количество ( возможно частичное )

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


$params = [
    "login"       => "vladislav@isaler.ru",
    "apikey"      => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"      => 'update',
    //дата акта
    "date"        => "2018-07-01",
    // шаблон Акта: имя файла или ID шаблона
    "template"    => "akt_full.tpl",
    "templateID"  => "97",
    //описание
    "description" => "Это текст - описание к акту",
    // позиции спецификации ( частичная отгрузка )
    "speka" => [
        [
            "spid" => 345,
            "kol"  => 25
        ],
        [
            "spid" => 346,
            "kol"  => 10
        ]
    ]
];

$urlparams = http_build_query($params);

Ответ:


{"result":"Успешно","data":{"id":279,"number":"57","did":"920"}}

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

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”

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

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

  • id – уникальный идентификатор счета
  • invoice - номер счета
  • user – логин Ответственного
  • theme - тема сообщения, если не указано, то будет установлено "Счет на оплату"
  • content - тело сообщения, если не указано, то будет использован шаблон по-умолчанию
  • 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"     => 362,
    //тема сообщения
    //"theme"   => "Документ на согласование",
    //содержание сообщения
    //"content" => "",
    //id статуса документа
    "status"      => 3
];

$urlparams = http_build_query($params);

Ответ:

В поле “result“ приходит ответ обработчика, в поле “data” приходит расширенный отчет обработки


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

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


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

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

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

Запрос “html”

Запрос позволяет получить содержимое Акта в виде HTML

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

  • number - номер Акта
  • id - идентификатор записи (если номер не уникален или не указан)
  • nosignat - если равен "yes", то в ответе не будет изображения печати

Наличие параметра "number" ИЛИ "id" обязательно для поиска счета в базе. Получить список счетов с "id" и "number" можно с помощью метода list

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



$params = [
    "login"      => "vladislav@isaler.ru",
    "apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'invoice.html',
    //id счета
    "id"         => 925,
    //исключение печати из вывода
    //"nosignat" => "yes",
    //номер счета
    "invoice"    => "158",
];

$urlparams = http_build_query($params);

Ответ:

  • в поле “html“ приходит ответ HTML,
  • в поле “id” приходит id акта,
  • в поле "number" приходит номер акта

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

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

Запрос “pdf”

Запрос позволяет получить ссылку на счет в виде PDF

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

  • invoice - номер счета
  • id - идентификатор записи счета (если номер не уникален или не указан)
  • nosignat - если равен "yes", то в ответе не будет изображения печати

Наличие параметра "invoice" ИЛИ "id" обязательно для поиска счета в базе. Получить список счетов с "id" и "invoice" можно с помощью метода info

Примечание

если файл не существует, то он будет сгенерирован (требуется больше времени на обработку). Поэтому в cURL запросе следует установить повышенное время ожидания ответа (подбирается опытным путем, но >=20)

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



$params = [
    "login"      => "vladislav@isaler.ru",
    "apikey"     => "aMgiCQyj8bCToNc47BZZYrRICoWSIl",
    // указываем метод
    "action"     => 'invoice.html',
    //id счета
    "id"         => 925,
    //исключение печати из вывода
    //"nosignat" => "yes",
    //номер счета
    "invoice"    => "158",
];

$urlparams = http_build_query($params);

Ответ:

  • в поле “url“ приходит URL pdf-файла (слэши экранированы),
  • в поле “id” приходит id акта,
  • в поле "number" приходит номер акта

{
    "url":"http://sm2018.crm/files/akt_57.pdf",
    "id":"315",
    "number":"57"
}

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

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