API: коммерческое предложение

POST /api/v1/documents/kp

Формирует печать коммерческого предложения (без сохранения в кабинете) и возвращает PDF или XLSX.

Список шаблонов: GET /api/v1/documents/kp/templates

Пример

{
  "format": "pdf",
  "template": 400,
  "response": "json",
  "number": "15",
  "date": "2026-08-23",
  "document_name": "Поставка и монтаж климатического оборудования",
  "document_address": "г. Москва, ул. Примерная, д. 1",
  "with_works": true,
  "note": "Срок действия предложения — 14 дней.",
  "seller": {
    "name": "ООО Ромашка",
    "inn": "7701234567",
    "kpp": "770101001",
    "address": "г. Москва",
    "phone": "495-000-00-00",
    "email": "info@example.com",
    "director": "Иванов Иван Иванович",
    "director_post": "Генеральный директор",
    "pseudo": "Исполнитель",
    "logo_url": "https://example.com/logo.png",
    "stamp_url": "https://example.com/stamp.png",
    "director_sign": "https://example.com/director.png"
  },
  "buyer": {
    "name": "ООО Покупатель",
    "inn": "7707654321",
    "pseudo": "Заказчик"
  },
  "items": [
    {
      "name": "Сплит-система",
      "quantity": 2,
      "price": 10000,
      "work_price": 1500,
      "vat": 20
    }
  ]
}

items можно передать и объектом с числовыми ключами. Пустой массив ([]) не считается ошибкой: в таблицу попадёт одна пустая строка.

Основные поля

Поле	Описание
format	pdf (по умолчанию) или xlsx
template	код печатной формы, по умолчанию 400
number, date	номер и дата документа
document_name	наименование объекта / предмета предложения
document_address	адрес объекта
with_works	учитывать стоимость работ (true / false)
note	примечание (также принимается conditions)
seller, buyer	реквизиты сторон
items	позиции; пустой массив печатает одну пустую строку
currency	код валюты, по умолчанию 643
print_stamp	печать и подписи
decimal_places	знаков после запятой в печати: 0–3; (алиасы decimals, znaki; см. Обзор)
number_format	отображение сумм: apostrophe (1'500.00) или space (1 500,00); (см. Обзор)
seller.logo, seller.logo_url	ссылка на логотип
seller.stamp, seller.stamp_url	ссылка на печать
seller.director_sign	ссылка на подпись директора
seller.pseudo / buyer.pseudo	подписи сторон, по умолчанию «Исполнитель» / «Заказчик»
discount	включить скидку (true)
discount_value	скидка по документу: 10 (сумма) или 10%
vat_correct	ручная сумма НДС в итоговой строке, например 1135.65. Если не передана, НДС считается по позициям
response	file или json

Шаблоны

template	Название
372	Коммерческое предложение #1
370	Коммерческое предложение #2
371	Коммерческое предложение #2 (компактная)

Актуальный список всегда в GET /api/v1/documents/kp/templates.

Позиция

Поле	Описание
name	наименование
quantity	обязательно, кроме заголовка, подитога и пустой строки
price	обязательно, кроме заголовка, подитога и пустой строки
work_price	цена работ за единицу (учитывается при with_works: true)
vat	ставка НДС
unit	ед. изм.
discount	скидка строки (10 или 10%), если включена скидка по документу
is_header	строка-заголовок таблицы
is_subtotal	строка-подитог
vat_value	игнорируется, считается на сервере
sum	игнорируется, считается на сервере

Заголовок:

{ "name": "Оборудование", "is_header": true }

Подитог (сумма считается на сервере по строкам выше до предыдущего подитога):

{ "name": "Итого по разделу", "is_subtotal": true }

Работы и НДС

При with_works: true для каждой позиции дополнительно считаются work_total и total_with_works. НДС по работам считается по той же ставке vat, что и у товара.

В JSON-ответе ("response": "json") в data.totals:

Поле	Описание
sum	сумма товаров/услуг
works	сумма работ
with_works	итог с работами
vat	НДС по ставкам

Для примера выше сумма товаров будет 20000.00, работы 3000.00, итог с работами 23000.00, НДС 3833.33 (товары 3333.33 + работы 500.00).