Invoicing

Invoice templates

Invoice templates are the XHTML documents with embedded macros that are converted into the XSL Formatting Objects document using the ~ssp/etc/xsl/xhtml2fo.xsl, the slightly modified version of the style sheet from  http://antennahouse.com/. The resulting XSL FO document is finally converted into the PDF file using Apache FOP. Starting from 5.0 Sippy version wkhtmltopdf is used as PDF converter.


The invoice templates are stored in the database, table invoice_templates. The templates with the i_invoice_template field values in the range from 1 to 1000 are system templates, which is additionally indicated by the invoice_templates.is_system = True.


Invoice templates for accounts

An invoice template is a mandatory attribute of a Service Plan (billing_plans.i_invoice_template). It has a system default value (see below). Accounts in turn also have optional attribute for an invoice template (accounts.i_invoice_template) which can override the setting from the Service Plan. The accounts also have setting to enable generation of invoices which are sent via e-mail to the address specified in the contacts of the account, this is a field accounts.invoicing_enabled.


On the Sippy web page the account can get the invoicing enabled by checking the Invoicing Enabled in his settings (the owner of that account, after logging in as the customer can change it.)

The particular Invoice template can be chosen from Invoice Template list after enabling the invoicing.

The same could be done using the bulk upload feature for multiple account as well.


Currently assigned system templates

  • 1 - The default invoice template for accounts

Available macros list

Starting from 5.0 version of Sippy the list of available macros are accessible from invoice editor:



Macros that contain the attributes of an account:

  • ${I_INVOICE} - Unique invoice identifier
  • ${I_ACCOUNT} - Unique account identifier
  • ${USERNAME} - Account name
  • ${SALUTATION} - Salutation from account preferences. Mr./Mrs.
  • ${FIRST_NAME} - First name from account preferences
  • ${LAST_NAME} - Last name from account preferences
  • ${CURRENCY} - Account base currency
  • ${STREET_ADDR} - Street address from account preferences
  • ${POSTAL_CODE} - Postal code from account preferences
  • ${CITY} - City from account preferences
  • ${COUNTRY} - Country from account preferences


Macros containing the current invoice information are:


${TOTAL_CHARGES} - Total sum of all minute plans and charges from the Service Plan

${PAYMENTS_AMOUNT} - Amount of payments for the current billing period

${FORWARD_AMOUNT} - Unpaid amount from the previous period

${LAST_BILL_AMOUNT} - Amount due from the previous invoice

${AMOUNT_DUE} - Amount account owes at the beginning/end of the billing period. Will contain non-zero values only if the account's balance is below zero.

${TARIFF_CALLS_PRICE} - Total sum of the calls exceeding the service plan minutes.

${ADDITIONAL_CHARGES} - Charges that were applied in the current billing period in addition to the service plan price

${BILL_DATE} - Date at the moment of an invoice creation

${LAST_BILL_DATE} - Date at which the previous invoice was issued

${TOTAL_DID_CALLS_CHARGES} - Total sum of DID calls charges to the account. (starting from 5.0)


Tables:

  • ${TABLE:service_plan_charges} - Contains all fields from the service_charges database table.
  • ${TABLE:service_plan_minutes} - Contains all fields from the service_plan database table.
  • ${TABLE:cdrs} - Contains all fields from the cdrs table plus the following additional fields. The fields should be placed inside the TABLE macros:
    • _num - Sequential number of the record
    • date - Date part of the connect_time field
    • time - Time part of the connect_time field

           Examples:

  • ${TD:cld_in} - cld_in field
  • ${TD:cost} - cost field

The cdrs table accepts two optional parameters:

  • max_rows - Maximum number of CDRs to display in invoice, default is 100
  • show_zero_cdrs - Display zero duration CDRs in invoice, default is false

Examples:

  • ${TABLE:cdrs;max_rows=0} - fetch unlimited number of CDRs
  • ${TABLE:cdrs;show_zero_cdrs=true;max_rows=10000} - display zero duration cdrs in the invoice, max 10000 records


Macro substitutions

Invoice template can contain macros. The macros can be of two types - common and context specific.

  • Common macros

  • Macros to create tables

To represent a table data there are a macros ${TABLE}, ${TD} and ${TABLE_END} which are designed to be used as shown in the example:

 

<table>
<tr>
  <th>Call</th>
  <th>Date</th>
  <th>Time</th>
  <th>Number Called</th>
</tr><tr>
  <td>${TABLE:cdrs}</td>
</tr><tr>
  <td>${TD:_num}</td>
  <td>${TD:date}</td>
  <td>${TD:time}</td>
  <td>${TD:cld_in}</td>
</tr><tr>
  <td>${TABLE_END}</td>
</tr>
</table> 

All rows between the macros ${TABLE} and ${TABLE_END} are repeated as many times as many rows has to be displayed, and the HTML table rows containing these macros are always skipped and never included in the final document.

EVAL macro

With this macro you are allowed to make arbitrary arithmetical calculations and place them on the page in a desired format. The general form for the macro is:

${EVAL:<expression>[;<format>]}


Examples:

Round the result to second digit after the dot:

${EVAL: ( ${TOTAL_CHARGES} ) ; %.02f }

Perform the division with 3 and round to the second digit after the dot:

${EVAL: ( ${LAST_BILL_AMOUNT} / 3.0 ) ; %.02f }

Some arithmetic operation:

${EVAL: ( ${TD:_num} + 15 ) / 2 }


To edit invoice template use web applications using direct links:

/invoice_templates.php
/images.php


List of supported formats for the images:

JPG, JPEG, PNG, GIF(static)


List of supported fonts:

Sans Serif

Monospace

Serif