REST: счета и платежи

Счета в Битрикс24 пережили смену модели: устаревшие crm.invoice.* уступили место смарт-счетам на движке смарт-процессов. Разберём, как создавать счета через crm.item с entityTypeId=31, добавлять товарные строки и связывать их с оплатами.

Две модели счетов: старая и новая

Исторически счета в CRM были отдельной сущностью с методами crm.invoice.add, crm.invoice.list, crm.invoice.update и справочником статусов crm.invoice.status.*. С переходом на «Счета нового поколения» (smart invoice) эта модель признана устаревшей, а новые счета реализованы поверх универсального движка смарт-процессов.

entityTypeId и универсальные методы

Смарт-счёт — частный случай элемента смарт-процесса, поэтому работает через универсальные методы crm.item:

• crm.item.add — создать счёт;
• crm.item.get / crm.item.list — чтение и выборка;
• crm.item.update — изменение;
• crm.item.delete — удаление;
• crm.item.fields — описание полей с указанием entityTypeId.

Идентификатор типа для счёта — 31 (константа SMART_INVOICE). У системной оценки и других встроенных смарт-типов свои id, а пользовательские смарт-процессы начинаются от 128.

Поля счёта именуются в «универсальном» стиле camelCase: title, opportunity, stageId, companyId, contactId, currencyId, begindate, closedate.

Создание смарт-счёта

Создадим счёт на сумму по компании и контакту:

POST /rest/1/xxxxxx/crm.item.add.json

{
  "entityTypeId": 31,
  "fields": {
    "title": "Счёт №2026-514",
    "companyId": 44,
    "contactId": 88,
    "opportunity": 125000,
    "currencyId": "RUB",
    "stageId": "DT31_1:N",
    "begindate": "2026-07-16T00:00:00+03:00"
  }
}

Ответ вернёт объект item с присвоенным id. Стадии счёта задаются в формате DT31_<categoryId>:<code> — например, черновик, отправлен, оплачен. Список стадий узнавайте через crm.status.list для сущности вида DYNAMIC_31_STAGE_<categoryId>.

Товарные строки счёта

Позиции счёта — это те же товарные строки CRM. В новой модели ими управляют универсальные методы:

• crm.item.productrow.set — записать полный набор строк владельца;
• crm.item.productrow.list — получить строки по владельцу;
• crm.item.productrow.add / crm.item.productrow.get / crm.item.productrow.delete.

// crm.item.productrow.set
{
  "ownerType": "T31",
  "ownerId": 730,
  "productRows": [
    { "productId": 51, "quantity": 2, "price": 50000, "taxRate": 20, "taxIncluded": "Y" },
    { "productName": "Настройка", "quantity": 1, "price": 25000 }
  ]
}

Префикс владельца ownerType для счёта — T31. После записи строк итоговая сумма счёта пересчитывается по полю opportunity, если включён режим расчёта по товарам.

Платежи и связь с модулем «Продажи»

Сам факт оплаты в Битрикс24 хранит модуль «Продажи» (Sale), а не CRM. Платежи по заказу доступны через методы sale.payment.*: sale.payment.add, sale.payment.list, sale.payment.update. Оплата привязывается к заказу (sale.order.*), а заказ связан со сделкой или счётом. На практике для полноценного приёма онлайн-оплат нужна связка из трёх сущностей: смарт-счёт в CRM для менеджера, заказ модуля «Продажи» и платёж в нём. Если же оплату вы принимаете на своей стороне, цепочку заказов можно не поднимать — достаточно двигать стадию счёта и хранить факт оплаты во внешней системе, синхронизируя её обратно вызовом crm.item.update.

Выборка и статусы

Получим неоплаченные счета по компании:

// crm.item.list
{
  "entityTypeId": 31,
  "filter": { "companyId": 44, "!stageId": "DT31_1:S" },
  "select": [ "id", "title", "opportunity", "stageId", "begindate" ],
  "order": { "id": "DESC" }
}

Символ ! перед именем поля означает отрицание. Для диапазонов сумм используйте префиксы >=opportunity и <=opportunity. Постраничность — через start, ответ содержит блок total. Важно помнить, что crm.item.list отдаёт максимум 50 элементов за вызов, поэтому для полной выгрузки счетов организуйте цикл по start либо перебор по возрастанию id с фильтром >id и start: -1. Второй способ работает заметно быстрее на больших объёмах, потому что не выполняет подсчёт общего количества строк.

Печатные формы и связанные сущности

Печать счёта в PDF и Word обеспечивает отдельный модуль генератора документов с методами crm.documentgenerator.document.add, crm.documentgenerator.document.list и шаблонами crm.documentgenerator.template.*. Документ создаётся по шаблону и привязывается к владельцу — счёту или сделке.

• Реквизиты. В печатной форме подставляются реквизиты компании и контакта из crm.requisite.*; их стоит заполнить до генерации.
• Ответственный. Поле assignedById счёта определяет менеджера, чьи данные попадут в подпись.
• Связь со сделкой. Смарт-счёт можно связать со сделкой через привязки смарт-процесса — тогда счёт виден в её карточке.

Такое разделение ответственности удобно: данные счёта и позиции ведёт CRM, а внешний вид документа — шаблон генератора, который можно менять без переписывания интеграции.

Итог

Современная работа со счетами в Битрикс24 идёт через смарт-счета и универсальные методы crm.item с entityTypeId=31, товарные строки — через crm.item.productrow.*, а фактические оплаты живут в модуле «Продажи» (sale.payment.*). Старый crm.invoice.* остаётся лишь для унаследованных порталов.

Мы в B2Bsite связываем выставление счетов и приём оплат с сайтом и 1С: заявка превращается в счёт, оплата возвращается в CRM, а взаиморасчёты синхронизируются с учётной системой. Если нужен корректный биллинг-обмен без ручных сверок — спроектируем и внедрим интеграцию.