Шаблоны счетов-фактур

Шаблон счёта-фактуры - это HTML-макет PDF-счёта, который получает аккаунт. Макросы вроде ${AMOUNT_DUE} заменяются показателями аккаунта за расчётный период, а табличные макросы повторяют строку для каждого звонка или начисления. У каждого клиента свои шаблоны; каждый аккаунт использует один из них. Как и когда выставляются счета-фактуры, описано в разделе Счета-фактуры.

Где найти

Откройте Payments → Invoice Templates в левой боковой панели. URL - /invoice_templates.php. Пункт доступен администраторам и реселлерам, чьи логины не ограничены уровнем доступа.

Screenshot "admin-panel/invoice-templates" has not been generated yet — see scripts/screenshots/screens.yml.

Что вы видите

Колонка	Значение
Name (название)	Название шаблона, ссылка на форму
Description (описание)	Произвольный текст
Action (действие)	Значок корзины для удаления шаблона. Для системного шаблона не показывается

Фильтр сопоставляет Name с условиями is like или is not like без учёта регистра и со всем названием; используйте % как подстановочный символ. Корневой клиент также видит системный шаблон Default Account Invoice (стандартный счёт-фактура аккаунта). Он доступен только для чтения, является шаблоном по умолчанию для новых аккаунтов и лучше всего подходит как основа для собственного.

Создание шаблона

1. Нажмите Add Based on Existing (добавить на основе существующего).
2. Выберите Base Template (базовый шаблон), например Default Account Invoice. Поле Name заполняется как Copy of …; измените его.
3. Нажмите Proceed (продолжить). Форма открывается с копией макета и CSS.
4. Отредактируйте макет в редакторе, а стили - в поле CSS.
5. Нажмите Preview PDF (предварительный просмотр PDF), чтобы проверить результат.
6. Нажмите Save & Close (сохранить и закрыть).

Add New (добавить новый) вместо этого начинает с пустого макета. Name обязательно и должно быть уникальным среди ваших шаблонов.

Осторожно

Шаблон рендерится при Save (сохранить). Если его не удаётся отрендерить, панель отклоняет его с сообщением Wrong Invoice Template parameters. Типичные причины: ${TABLE} без ${TABLE_END}, таблица внутри другой таблицы, ${TD} вне таблицы, ${EVAL} с буквами и max_rows за пределами 1–1000.

Форма шаблона

Basic Parameters (основные параметры) содержит Name и Description. Invoice Template (шаблон счёта-фактуры) содержит CSS и редактор.

Редактор - это визуальный HTML-редактор. На его панели инструментов есть Insert Macro (вставить макрос), который вставляет любой макрос из приведённых ниже и показывает краткую справку по каждому, инструменты таблиц, кнопка изображения и кнопка, открывающая HTML-код. Табличные макросы редактируйте в HTML-коде: они должны стоять в отдельных строках.

Preview PDF рендерит текущее содержимое редактора, сохранённое или нет, с тестовыми данными и открывает PDF в новом окне. Чтобы увидеть счёт-фактуру с реальными цифрами, назначьте шаблон тестовому аккаунту и воспользуйтесь Generate Invoice (сформировать счёт-фактуру) (см. Счета-фактуры). Save и Save & Close скрыты для системного шаблона.

Screenshot "admin-panel/invoice-template-form" has not been generated yet — see scripts/screenshots/screens.yml.

Макросы

Суммы указываются в валюте аккаунта и округляются до её количества знаков после запятой. Даты имеют вид 31-Oct-2026. Длительности имеют вид [h:]mm:ss.

Аккаунт

Макрос	Значение
${I_INVOICE}	Номер счёта-фактуры: внутренний ID счёта-фактуры, уникальный на коммутаторе
${I_ACCOUNT}	ID аккаунта
${USERNAME}	Имя аккаунта
${SALUTATION}, ${FIRST_NAME}, ${LAST_NAME}, ${COMPANY_NAME}	С вкладки Address (адрес) аккаунта
${STREET_ADDR}, ${POSTAL_CODE}, ${CITY}, ${STATE}, ${COUNTRY}	С вкладки Address аккаунта
${CURRENCY}	Валюта аккаунта

Период

Макрос	Значение
${INVOICE_START_DATE}	Первый день периода, за который выставлен счёт-фактура
${INVOICE_END_DATE}	Последний день периода, за который выставлен счёт-фактура
${BILL_DATE}	Дата окончания периода, то есть дата выставления счёта-фактуры
${LAST_BILL_DATE}	Дата предыдущего счёта-фактуры; начало периода, если его нет

Суммы

Макрос	Значение
${TOTAL_CHARGES}	Начисления по сервисному плану и плата за пакеты минут в периоде
${ADDITIONAL_CHARGES}	Все прочие начисления в периоде: плата за DID, ручные начисления и т. п.
${TARIFF_CALLS_PRICE}	Стоимость звонков, тарифицированных по тарифу, то есть сверх минут сервисного плана
${TOTAL_DID_CALLS_CHARGES}	Стоимость входящих звонков на DID аккаунта
${PAYMENTS_AMOUNT}	Платежи, полученные в периоде
${LAST_BILL_AMOUNT}	Сумма предыдущего счёта-фактуры; 0, если его нет
${FORWARD_AMOUNT}	Перенесённый долг: отрицательный баланс на начало периода в виде положительного числа; иначе 0
${BALANCE}	Баланс на конец периода
${AMOUNT_DUE}	Сумма, которую аккаунт должен на конец периода; 0, если баланс не ниже нуля

Длительности

Макрос	Значение
${ALL_CALLS_DURATION}	Тарифицированная длительность всех звонков в периоде
${PLAN_CALLS_DURATION}	Тарифицированная длительность, покрытая минутами сервисного плана
${TARIFF_CALLS_DURATION}	Тарифицированная длительность сверх минут сервисного плана

Таблицы

Табличный макрос повторяет одну строку HTML-таблицы для каждой записи. Поместите ${TABLE:<name>} в отдельную строку, ячейки ${TD:<field>} - в следующую строку, а ${TABLE_END} - в отдельную строку после неё. Строки с ${TABLE} и ${TABLE_END} удаляются из результата.

<table>
  <tr><th>#</th><th>Date</th><th>Number</th><th>Length</th><th>Cost</th></tr>
  <tr><td colspan="5">${TABLE:cdrs;max_rows=500}</td></tr>
  <tr>
    <td>${TD:_num}</td>
    <td>${TD:date} ${TD:time}</td>
    <td>${TD:cld_in}</td>
    <td>${TD:duration;fmt=duration}</td>
    <td>${TD:cost} ${CURRENCY}</td>
  </tr>
  <tr><td colspan="5">${TABLE_END}</td></tr>
</table>

Таблицы нельзя вкладывать друг в друга. ${TD:_num} - номер строки в любой таблице. Десятичные значения округляются до количества знаков после запятой валюты; добавьте ;fmt=duration, чтобы показать количество секунд в виде [h:]mm:ss.

Таблица	Параметры	Поля
cdrs: звонки аккаунта, завершившиеся в периоде, по времени начала	max_rows: 1–1000, по умолчанию 100. show_zero_cdrs: true, чтобы включить звонки нулевой длительности, по умолчанию false	date (26 Oct), time (15:04), cld_in, cli_in, duration, billed_duration, cost, prefix, remote_ip, код country и description направления и любое другое поле CDR
cdrs_summary: те же звонки, сгруппированные по направлению	group_by: country,description (по умолчанию) или country. order_by: country, description, num_calls, effective_rate, duration или cost, с необязательным :ASC или :DESC	country (название), description, num_calls, duration (секунды), cost, effective_rate (стоимость минуты). Звонки с неизвестной страной показываются как Unknown
charges: начисления аккаунту в периоде	max_rows: 1–1000, по умолчанию 100	charge_time, date, time, amount, currency, name (тип начисления), description
service_plan_charges: регулярные начисления сервисного плана аккаунта	нет	description, price
service_plan_minutes: пакеты минут сервисного плана	нет	description, price, seconds_total, destinations

Параметры идут после названия таблицы через точку с запятой: ${TABLE:cdrs;show_zero_cdrs=true;max_rows=1000}, ${TABLE:cdrs_summary;group_by=country;order_by=cost:DESC}.

Заметка

Счёт-фактура содержит не более 1 000 строк в каждой таблице. Для аккаунтов с большим количеством звонков за период нужен итог (cdrs_summary) в счёте-фактуре, а полный перечень - в виде экспорта CDR.

Вычисления

${EVAL:<expression>;<format>} вычисляет значение после замены всех остальных макросов. Выражение может содержать только цифры, пробелы, +, -, *, /, скобки и десятичную точку. Формат - это шаблон в стиле printf, например %.2f; без него выводится необработанный результат.

Пример	Результат
${EVAL: ${TOTAL_CHARGES} * 1.2 ; %.2f}	Начисления по сервисному плану плюс 20% налога
${EVAL: ${TOTAL_CHARGES} * 0.2 ; %.2f}	Только налог
${EVAL: ${TARIFF_CALLS_PRICE} + ${ADDITIONAL_CHARGES} ; %.2f}	Звонки плюс прочие начисления

Внутри ${EVAL} используйте только макросы сумм и чисел. Текстовый макрос или пустое значение делает выражение недействительным, и счёт-фактуру не удаётся отрендерить.

Изображения и стили

1. Откройте /images.php (у экрана Images (изображения) нет пункта в боковой панели).
2. Загрузите логотип или другие изображения. Принимаются JPG, GIF и PNG размером примерно до 500 КБ.
3. В редакторе шаблона нажмите кнопку изображения и выберите изображение из списка.

Изображения встраиваются в PDF при рендеринге счёта-фактуры, поэтому PDF не зависит от доступности панели. Шаблон может использовать только изображения своего клиента.

Поле CSS содержит таблицу стилей счёта-фактуры; редактор тоже её показывает. Стандартный шаблон использует её для заголовков и выравнивания таблиц:

h2 {
  background-color: #ff9900;
  border: 1px solid #544f4f;
  text-align: center;
}

table.fixed {
  width: 100%;
  table-layout: fixed;
}

Назначение шаблона

Откройте аккаунт, перейдите на вкладку Advanced (дополнительно), отметьте Invoicing Enabled (выставление счетов-фактур включено) и выберите Invoice Template. Для многих аккаунтов сразу заполните колонки Invoicing Enabled и Invoice Template в файле загрузки аккаунтов. См. Счета-фактуры.

Удаление шаблона

1. Нажмите значок корзины в строке.
2. Нажмите Yes (да) в подтверждении.

Аккаунты, которые использовали шаблон, переходят на системный шаблон Default Account Invoice. Уже выставленные счета-фактуры не меняются.

Совет

Никогда не редактируйте рабочий шаблон напрямую. Скопируйте его с помощью Add Based on Existing, измените копию и просмотрите её, затем переведите на неё тестовый аккаунт и сформируйте счёт-фактуру, прежде чем переводить клиентов.

Связанные страницы

• Счета-фактуры
• Аккаунты
• Тарифные планы
• Формирование счетов-фактур через API