VK.com Github Youtube

Акты (akt)

Метод “akt”

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

URL для вызова:

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

Запрос “statuses”

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

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

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

Ответ:

  • id - идентификатор статуса
  • title - название статуса
  • color - цветовая схема статуса
  • type - id типа документа, к которым применяется статус (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
        }
    ]
}

Запрос “templates”

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

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

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

Ответ:

  • 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
        }
    ]
}

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

404 – Шаблоны не найдены

Запрос “info”

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

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

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

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

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

{
    "id": 99
}

Ответ:

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

  • datum - Дата создания Акта
  • number - номер Акта
  • title - Название Акта
  • description - описание Акта
  • template - шаблон Акта
  • templateId - ID шаблона Акта
  • templateTitle - название шаблона Акта
  • templateTypeID - ID типа документа
  • mcid - id Компании, от которой ведется сделка
  • signer - id подписанта компании
  • status - id статуса документа
  • statusTitle - расшифровка статуса
  • crid - идентификатор счета, если Сделка является сервисной
  • positions - список позиций, прикрепленных к акту ( частичная отгрузка )
    • id - id позиции
    • spid - id позиции спецификации
    • prid - id позиции прайса
    • kol - количество
{
    "data": {
        "deid": 99,
        "datum": "12.03.2014",
        "number": "79-0214\/2014",
        "title": "Договор",
        "description": "",
        "template": null,
        "templateID": 0,
        "templateTitle": null,
        "templateTypeID": 0,
        "clid": 1439,
        "clientTitle": "Тестовая организация 2, ЗАО",
        "payer": 1439,
        "payerTitle": "Тестовая организация 2, ЗАО",
        "did": 709,
        "dealTitle": "Поставка шин Мишлен с установкой",
        "mcid": "2",
        "signer": 0,
        "status": "0",
        "statusTitle": false,
        "positions": []
    }
}

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

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, то будут выведены записи текущего пользователя и всех подчиненных

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

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

{
    "clid": 1440
}

Ответ:

{
    "data": [
        {
            "id": 510,
            "datum": "23.01.2023",
            "datum_start": null,
            "datum_end": null,
            "number": "121",
            "summaf": "642 800,00",
            "summa": 642800,
            "title": null,
            "clid": 1440,
            "client": "Тестовая 3",
            "pid": 0,
            "person": null,
            "did": 968,
            "deal": "СД4316: Новая сделка",
            "payerid": 1440,
            "payer": "Тестовая 3",
            "crid": 0,
            "invoice": "258",
            "invoices": [
                "258"
            ],
            "user": "Андреев Владислав",
            "statuson": "1",
            "status": "Создан",
            "statusTitle": "Создан",
            "statusColor": "#9edae5",
            "mc": "ООО ”Рога и Ко”",
            "mcid": 3,
            "complect": 100
        },
        {
            "id": 189,
            "datum": "14.04.2014",
            "datum_start": null,
            "datum_end": null,
            "number": "12",
            "summaf": "350 000,00",
            "summa": 350000,
            "title": null,
            "clid": 1440,
            "client": "Тестовая 3",
            "pid": 0,
            "person": null,
            "did": 710,
            "deal": "Поставка Светодиодов",
            "payerid": 1440,
            "payer": "Тестовая 3",
            "crid": 0,
            "invoice": "27",
            "invoices": [
                "27"
            ],
            "user": "Андреев Владислав",
            "statuson": "1",
            "status": null,
            "statusTitle": "--",
            "statusColor": "#fff",
            "mc": "ООО ”БИГСЕЙЛЗРУС”",
            "mcid": 2,
            "complect": 100
        }
    ],
    "params": {
        "clid": 1440,
        "page": 0,
        "ord": "datum",
        "tuda": "DESC"
    },
    "count": 2
}

Запрос “add”

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

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

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

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

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

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

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

{
    "date": "2024-06-25",
    "template": "akt_full.tpl",
    "description": "Это текст - описание к акту",
    "status": 1,
    "did": 954
}

Ответ:

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

{
    "result": "Успешно",
    "data": {
        "id": 535,
        "number": "123",
        "did": 954
    }
}

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

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

Запрос “update”

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

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

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

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

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

{
    "id": 535,
    "date": "2024-06-24",
    "template": "akt_full.tpl",
    "description": "Давно выяснено, что при оценке дизайна и композиции читаемый текст мешает сосредоточиться. Lorem Ipsum используют потому, что тот обеспечивает более или менее стандартное заполнение шаблона",
    "status": 1
}

Ответ:

{
    "result": "Успешно",
    "data": {
        "id": 535,
        "number": "123",
        "did": 954
    }
}

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

403 – Запись не найдена
405 – Отсутствуют параметры - id акта

Запрос “status.change”

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

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

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

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

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

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

Ответ:

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

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

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)

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

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

{
    "id": 535,
    "theme": "Документ на согласование",
    "status": 5
}

Ответ:

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

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

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

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

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

403 – Акт не найден
407 – Не найдено получателей

Запрос “html”

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

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

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

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

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

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

{
    "id": 535,
    "nosignat": "yes"
}

Ответ:

  • в поле “html“ приходит ответ HTML (специальные символы преобразованы в HTML-сущности),
  • в поле “id” приходит id акта,
  • в поле "number" приходит номер акта

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

403 – Акт по ID или Номеру не найден

Запрос “pdf”

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

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

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

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

Примечание

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

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

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

{
    "id": 535,
    "nosignat": "yes"
}

Ответ:

  • в поле “url“ приходит URL pdf-файла (слэши экранированы),
  • в поле “id” приходит id акта,
  • в поле "number" приходит номер акта
{
    "url": "http:\/\/sm2021.crmsm2021.crm\/files\/akt_123.pdf",
    "id": 535,
    "number": "123"
}

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

403 – Акт по ID или Номеру не найден

Запрос “delete”

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

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

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

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

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

{
    "id": 535
}

Ответ:

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

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

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