Шаблоны счетов и скрипты

Шаблоны документов (счета)

BillBill может формировать HTML, а затем PDF счёта на основе шаблона мерчанта.

• Шаблоны хранятся как сущности document template (Merchant API: document_templateNew, document_templateEdit, document_templateDetail).
• Для счёта используется тип шаблона invoice (внутреннее имя в коде API).
• Если у плана задана привязка к конкретному шаблону, он имеет приоритет; иначе подставляется шаблон мерчанта по умолчанию для типа; при отсутствии — системный шаблон по умолчанию.

EJS

HTML шаблона обрабатывается движком EJS на стороне API. В контекст передаются, в частности:

• invoice — детализация счёта;
• merchant — данные мерчанта;
• user — покупатель;
• gateway — шлюз (если применимо).

Используйте синтаксис EJS для подстановки полей и циклов по строкам счёта. Ошибки рендера приводят к пустому HTML — проверяйте шаблон на тестовом счёте.

PDF

После рендера HTML PDF может строиться через Gotenberg (конфигурация на стороне развёртывания API). Альтернативно используется встроенный генератор PDF для упрощённого макета — поведение зависит от пути кода, вызванного для конкретного счёта.

Пользовательские скрипты мерчанта

Отдельно от шаблонов существуют MerchantScript — JS-сценарии, исполняемые в изолированной среде (Goja) на сервере. Типичный сценарий: постобработка после приёма события метрики (postReceiveScript у метрики).

Возможности:

• создание / редактирование / список скриптов через Merchant API (script/*);
• отладка через script.Debug с передачей тестового контекста.

Ограничения по времени выполнения и ресурсам задаются на стороне API; при превышении выполнение прерывается.

Рекомендации

• Версионируйте шаблоны (комментарии / отдельные черновики в вашем процессе).
• Не помещайте секреты в шаблоны и скрипты — они доступны администраторам мерчанта с доступом к настройкам.