Шаблони рахунків-фактур

Шаблон рахунку-фактури - це 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