API: справка КС-3

POST /api/v1/documents/ks3

Формирует печать справки о стоимости выполненных работ и затрат (унифицированная форма № КС-3) без сохранения в кабинете и возвращает PDF или XLSX.

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

Пример

{
  "format": "pdf",
  "template": 381,
  "response": "json",
  "number": "15",
  "date": "2026-08-23",
  "currency": "643",
  "name_construction": "на установку системы кондиционирования на 2 этаже",
  "address_construction": "г. Москва, ул. Малая Якиманка, д. 16",
  "name_object_construction": "Административное здание",
  "number_contract": "114",
  "date_contract": "2012-12-04",
  "sum_contract": "1500000",
  "reporting_period_from": "2026-08-01",
  "reporting_period_for": "2026-08-31",
  "nds": "20",
  "print_stamp": true,
  "seller": {
    "name": "ООО Подрядчик",
    "inn": "7701234567",
    "kpp": "770101001",
    "okpo": "12345678",
    "address": "г. Москва, ул. Подрядная, д. 1",
    "phone": "495-000-00-00",
    "fax": "495-000-00-01",
    "director": "Иванов Иван Иванович",
    "director_post": "Генеральный директор",
    "stamp_url": "https://example.com/stamp.png",
    "director_sign": "https://example.com/director.png"
  },
  "buyer": {
    "name": "ООО Заказчик",
    "inn": "7707654321",
    "kpp": "770701001",
    "okpo": "87654321",
    "address": "г. Москва, ул. Заказная, д. 2",
    "phone": "495-111-11-11",
    "director": "Петров Пётр Петрович",
    "director_post": "Генеральный директор"
  },
  "investor": {
    "name": "ООО Инвестор",
    "okpo": "11223344",
    "address": "г. Москва, ул. Инвестиционная, д. 3",
    "phone": "495-222-22-22"
  },
  "items": [
    {
      "name": "Прокладка трубопровода",
      "product_code": "01-02",
      "quantity": 1,
      "price": 15000,
      "total_start": "50000",
      "total_year": "20000"
    }
  ]
}

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

В кабинете у КС-3 нет колонок «цена» и «количество»: сумма за отчётный период вводится целиком. Через API то же самое — quantity: 1 и price равный этой сумме.

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

Поле	Описание
`format`	`pdf` (по умолчанию) или `xlsx`
`template`	код печатной формы, по умолчанию `381`
`number`, `date`	номер и дата справки (также принимаются `doc_number`, `doc_date`)
`name_construction`	наименование стройки (алиас `document_name`)
`address_construction`	адрес стройки (алиас `document_address`)
`name_object_construction`	наименование объекта; в бланке `381` не выводится
`number_contract`	номер договора подряда
`date_contract`	дата договора подряда `Y-m-d`
`sum_contract`	сметная (договорная) стоимость; в бланке `381` не выводится
`reporting_period_from`	отчётный период с `Y-m-d`
`reporting_period_for`	отчётный период по `Y-m-d`
`okdp`	вид деятельности по ОКДП; в бланке `381` ячейка пока пустая
`nds`	ставка НДС документа: `20`, `+20`, `5`, `0`, `-` и т.п. (см. Обзор). Алиасы `vat_rate`, `vatRate`
`vat_correct`	ручная сумма НДС в строке «Сумма НДС», например `1135.65`
`seller`	подрядчик (субподрядчик)
`buyer`	заказчик (генподрядчик)
`investor`	инвестор
`items`	позиции; пустой массив печатает одну пустую строку
`currency`	код валюты, по умолчанию `643`
`print_stamp`	вывести печать и подпись подрядчика
`decimal_places`	знаков после запятой в печати: `0`–`3`; (алиасы `decimals`, `znaki`; см. Обзор)
`number_format`	отображение сумм: `apostrophe` (`1'500.00`) или `space` (`1 500,00`); (см. Обзор)
`response`	`file` или `json`

В шапке справки для сторон выводятся наименование, адрес, телефон, факс и ОКПО. Строка «Стройка» собирается из name_construction и address_construction. Подписи заказчика и подрядчика берутся из buyer.director / buyer.director_post и seller.director / seller.director_post.

Печать и подпись подрядчика используются только при print_stamp или если переданы изображения подписи/печати.

НДС и итоги

В печатной форме три итоговые строки по графе «за отчётный период»:

Итого — сумма графы 6 без НДС.
Сумма НДС.
Всего по акту — итого + НДС.

Как считается НДС:

Если передана vat_correct — в строку «Сумма НДС» берётся она.
Иначе, если у позиций указан vat и по ним получилась сумма НДС — берётся она. Для шаблона 381 суммы в графах 4–6 печатаются без НДС: ставка 20 вычитается из price / total_start / total_year, ставка +20 добавляется сверху только к итогу.
Иначе берётся ставка документа nds: НДС = сумма графы 6 × ставка / 100. Так работает форма в кабинете: у строк свой vat обычно 0, а ставка одна на весь документ.

Для примера выше (nds: 20, период 15000):

графы 4 / 5 / 6: 50000 / 20000 / 15000
Итого 15000.00
Сумма НДС 3000.00
Всего по акту 18000.00

Стороны

Поля seller, buyer и investor одинаковые. Для печати КС-3 важны:

Поле	Описание
`name`	наименование
`okpo`	ОКПО
`address`	адрес
`phone`	телефон (алиас `phones`)
`fax`	факс
`inn`, `kpp`	ИНН и КПП (передаются в запросе)
`director`	ФИО руководителя (расшифровка подписи)
`director_post`	должность (алиасы `director_status`, `director_caption`)
`stamp` / `stamp_url`	печать подрядчика
`director_sign`	подпись руководителя подрядчика

Шаблоны

`template`	Название
`381`	КС-3

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

Пример ответа шаблонов:

{
  "data": [
    { "id": 381, "name": "КС-3" }
  ]
}

Позиция

В печатной форме КС-3 три графы стоимости: накопительные суммы передаются явно, сумма за отчётный период считается из quantity и price.

Поле	Описание
`name`	наименование пусковых комплексов, этапов, объектов, видов работ, оборудования, затрат
`product_code`	код (графа 3)
`quantity`	обязательно, кроме пустой строки; для одной суммы за период передайте `1`
`price`	обязательно, кроме пустой строки; вместе с `quantity` даёт графу «в том числе за отчётный период»
`vat`	ставка НДС строки: `20`, `+20`, `0`, `-` и т.п. (см. Обзор). Если не передана или `0`, НДС считается по `nds` документа
`total_start`	стоимость с начала проведения работ (графа 4; алиас `totalStart`)
`total_year`	стоимость с начала года (графа 5; алиас `totalYear`)
`vat_value`	игнорируется, считается на сервере
`sum`	игнорируется, считается на сервере

Заголовки разделов и подитоги (is_header, is_subtotal) в печатной форме КС-3 не выводятся.

НДС в строке, а не в nds документа:

{
  "name": "Прокладка трубопровода",
  "product_code": "01-02",
  "quantity": 1,
  "price": 15000,
  "vat": 20,
  "total_start": "50000",
  "total_year": "20000"
}

Для шаблона 381 графа 6 будет 12500.00 (НДС вычтен из цены), «Сумма НДС» — 2500.00, «Всего по акту» — 15000.00. Графы 4 и 5 тоже печатаются без НДС.

Ответ JSON

При "response": "json":

{
  "data": {
    "id": null,
    "type": "ks3",
    "number": "15",
    "date": "2026-08-23",
    "format": "pdf",
    "template": 381,
    "filename": "Справка КС-3 № 15 от 23.08.2026.pdf",
    "url": "https://example.com/temp-file/....pdf",
    "totals": {
      "sum": "15000.00",
      "vat": []
    }
  },
  "meta": {
    "limit": 100,
    "used": 1,
    "remaining": 99
  }
}

Поле	Описание
`data.totals.sum`	сумма за отчётный период (`quantity` × `price`), без начисления `nds` документа
`data.totals.vat`	НДС по ставкам позиций (ключ — ставка, значение — сумма). Пустой массив, если НДС задан только через `nds`
`meta`	дневной лимит API

Заголовки ответа: X-RateLimit-Limit, X-RateLimit-Remaining.

data.totals не повторяет строки «Сумма НДС» и «Всего по акту» печатной формы: они считаются при печати по правилам выше.

Пример​

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

НДС и итоги​

Стороны​

Шаблоны​

Позиция​

Ответ JSON​